## 11.6pirateplot()

Table 11.4: pirateplot() function arguments
Argument Description
formula A formula specifying a y-axis variable as a function of 1, 2 or 3 x-axis variables. For example, formula = weight ~ Diet + Time will plot weight as a function of Diet and Time
data A dataframe containing the variables specified in formula
theme A plotting theme, can be an integer from 1 to 4. Setting theme = 0 will turn off all plotting elements so you can then turn them on individually.
pal The color palette. Can either be a named color palette from the piratepal() function (e.g. "basel", "xmen", "google") or a standard R color. For example, make a black and white plot, set pal = "black"
cap.beans If cap.beans = TRUE, beans will be cut off at the maximum and minimum data values

A pirateplot a plot contained in the yarrr package written specifically by, and for R pirates The pirateplot is an easy-to-use function that, unlike barplots and boxplots, can easily show raw data, descriptive statistics, and inferential statistics in one plot. Figure 11.5 shows the four key elements in a pirateplot:

Table 11.5: 4 elements of a pirateplot()
Element Description
Points Raw data.
Bar / Line Descriptive statistic, usually the mean or median
Bean Smoothed density curve showing the full data distribution.
Band Inference around the mean, either a Bayesian Highest Density Interval (HDI), or a Confidence Interval (CI)

The two main arguments to pirateplot() are formula and data. In formula, you specify plotting variables in the form y ~ x, where y is the name of the dependent variable, and x is the name of the independent variable. In data, you specify the name of the dataframe object where the variables are stored.

Let’s create a pirateplot of the ChickWeight data. I’ll set the dependent variable to weight, and the independent variable to Time using the argument formula = weight ~ Time:

yarrr::pirateplot(formula = weight ~ Time, # dv is weight, iv is Diet
data = ChickWeight,
main = "Pirateplot of chicken weights",
xlab = "Diet",
ylab = "Weight")

### 11.6.1 Pirateplot themes

There are many different pirateplot themes, these themes dictate the overall look of the plot. To specify a theme, just use the theme = x argument, where x is the theme number:

For example, here is a pirateplot height data from the pirates dataframe using theme = 3. Here, I’ll plot pirates’ heights as a function of their sex and whether or not they wear a headband. I’ll also make the plot all grayscale by using the pal = "gray" argument:

yarrr::pirateplot(formula = height ~ sex + headband,    # DV = height, IV1 = sex, IV2 = headband
data = pirates,
theme = 3,
main = "Pirate Heights",
pal = "gray")

### 11.6.2 Customizing pirateplots

Regardless of the theme you use, you can always customize the color and opacity of graphical elements. To do this, specify one of the following arguments. Note: Arguments with .f. correspond to the filling of an element, while .b. correspond to the border of an element:

Table 11.6: Customising plotting elements
element color opacity
points point.col, point.bg point.o
beans bean.f.col, bean.b.col bean.f.o, bean.b.o
bar bar.f.col, bar.b.col bar.f.o, bar.b.o
inf inf.f.col, inf.b.col inf.f.o, inf.b.o
avg.line avg.line.col avg.line.o

For example, I could create the following pirateplots using theme = 0 and specifying elements explicitly:

pirateplot(formula = weight ~ Time,
data = ChickWeight,
theme = 0,
main = "Fully customized pirateplot",
pal = "southpark", # southpark color palette
bean.f.o = .6, # Bean fill
point.o = .3, # Points
inf.f.o = .7, # Inference fill
inf.b.o = .8, # Inference border
avg.line.o = 1, # Average line
bar.f.o = .5, # Bar
inf.f.col = "white", # Inf fill col
inf.b.col = "black", # Inf border col
avg.line.col = "black", # avg line col
bar.f.col = gray(.8), # bar filling color
point.pch = 21,
point.bg = "white",
point.col = "black",
point.cex = .7)

If you don’t want to start from scratch, you can also start with a theme, and then make selective adjustments:

pirateplot(formula = weight ~ Time,
data = ChickWeight,
main = "Adjusting an existing theme",
theme = 2,  # Start with theme 2
inf.f.o = 0, # Turn off inf fill
inf.b.o = 0, # Turn off inf border
point.o = .2,   # Turn up points
bar.f.o = .5, # Turn up bars
bean.f.o = .4, # Light bean filling
bean.b.o = .2, # Light bean border
avg.line.o = 0, # Turn off average line
point.col = "black") # Black points

Just to drive the point home, as a barplot is a special case of a pirateplot, you can even reduce a pirateplot into a horrible barplot:

# Reducing a pirateplot to a (at least colorful) barplot
pirateplot(formula = weight ~ Diet,
data = ChickWeight,
main = "Reducing a pirateplot to a (horrible) barplot",
theme = 0,                                    # Start from scratch
pal = "black",
inf.disp = "line",                            # Use a line for inference
inf.f.o = 1,                                  # Turn up inference opacity
inf.f.col = "black",                          # Set inference line color
bar.f.o = .3)                                

There are many additional arguments to pirateplot() that you can use to complete customize the look of your plot. To see them all, look at the help menu with ?pirateplot or look at the vignette at

Table 11.7: Additional pirateplot() customizations.
Element Argument Examples
Background color back.col back.col = 'gray(.9, .9)'
Gridlines gl.col, gl.lwd, gl.lty gl.col = 'gray', gl.lwd = c(.75, 0), gl.lty = 1
Quantiles quant, quant.lwd, quant.col quant = c(.1, .9), quant.lwd = 1, quant.col = 'black'
Average line avg.line.fun avg.line.fun = median
Inference Calculation inf.method inf.method = 'hdi', inf.method = 'ci'
Inference Display inf.disp inf.disp = 'line', inf.disp = 'bean', inf.disp = 'rect'
# Additional pirateplot customizations
pirateplot(formula = weight ~ Diet,
data = ChickWeight,
main = "Adding quantile lines and background colors",
theme = 2,
cap.beans = TRUE,
back.col = transparent("blue", .95), # Add light blue background
gl.col = "gray", # Gray gridlines
gl.lwd = c(.75, 0),
inf.f.o = .6, # Turn up inf filling
inf.disp = "bean", # Wrap inference around bean
bean.b.o = .4, # Turn down bean borders
quant = c(.1, .9), # 10th and 90th quantiles
quant.col = "black") # Black quantile lines

### 11.6.3 Saving output

If you include the plot = FALSE argument to a pirateplot, the function will return some values associated with each bean in the plot. In the next chunk, I’ll

# Create a pirateplot
pirateplot(formula = tattoos ~ sex + headband,
data = pirates)


# Save data from the pirateplot to an object
tattoos.pp <- pirateplot(formula = tattoos ~ sex + headband,
data = pirates,
plot = FALSE)

Now I can access the summary and inferential statistics from the plot in the tattoos.pp object. The most interesting element is $summary which shows summary statistics for each bean (aka, group): # Show me statistics from groups in the pirateplot tattoos.pp ##$summary
##      sex headband bean.num   n  avg inf.lb inf.ub
## 1 female       no        1  55  5.0    4.3    5.5
## 2   male       no        2  47  4.3    3.2    5.0
## 3  other       no        3  11  5.3    2.5    7.2
## 4 female      yes        4 409 10.0    9.8   10.3
## 5   male      yes        5 443 10.0    9.7   10.3
## 6  other      yes        6  35 10.6    9.9   11.4
##
## $avg.line.fun ## [1] "mean" ## ##$inf.method
## [1] "hdi"
##
## \$inf.p
## [1] 0.95

Once you’ve created a plot with a high-level plotting function, you can add additional elements with low-level functions. For example, you can add data points with points(), reference lines with abline(), text with text(), and legends with legend().