What is a pirateplot()?
A pirateplot, is the RDI (Raw data, Descriptive statistics, and Inferential statistics) plotting choice of R pirates who are displaying the relationship between 1 to 3 categorical independent variables, and one continuous dependent variable.
A pirateplot has 4 main elements
- points, symbols representing the raw data (jittered horizontally)
- bar, a vertical bar showing central tendencies
- bean, a smoothed density (inspired by Kampstra and others (2008)) representing a smoothed density
- inf, a rectangle representing an inference interval (e.g.; Bayesian Highest Density Interval or frequentist confidence interval)

Main arguments
Here are the main arguments to pirateplot()
Main Pirateplot Arguments
formula |
A formula |
height ~ sex + eyepatch, weight ~ Time |
data |
A dataframe |
pirates, ChickWeight |
main |
Plot title |
‘Pirate heights’, ’Chicken Weights |
pal |
A color palette |
‘xmen’, ‘black’ |
theme |
A plotting theme |
0, 1, 2 |
inf |
Type of inference |
‘ci’, ‘hdi’, ‘iqr’ |
Themes
pirateplot()
currently supports three themes which change the default look of the plot. To specify a theme, use the theme
argument:
Theme 1
theme = 1
, the default theme, shows all four pirateplot elements:
# Default theme
pirateplot(formula = weight ~ Time,
data = ChickWeight,
theme = 1,
main = "theme = 1")

Theme 2
theme = 2
, emphasizes the beans and changes the look of the points:
# Default theme
pirateplot(formula = weight ~ Time,
data = ChickWeight,
theme = 2,
main = "theme = 2")

Theme 0
theme = 0
allows you to start a pirateplot from scratch – that is, it turns of all elements. You can then selectively turn elements on with individual arguments (e.g.; bean.f.o
, point.o
)
# Default theme
pirateplot(formula = weight ~ Time,
data = ChickWeight,
theme = 0,
main = "theme = 0\nStart from scratch")

Color palettes
You can specify a general color palette using the pal
argument. You can do this in two ways.
The first way is to specify the name of a color palette in the piratepal()
function. Here they are:

For example, here is a pirateplot using the "southpark"
palette
pirateplot(formula = weight ~ Time,
data = ChickWeight,
pal = "southpark",
theme = 2,
main = "southpark color palette")

The second method is to simply enter a vector of one or more colors. Here, I’ll create a black and white pirateplot of the same data by specifying pal = gray(.1)
pirateplot(formula = weight ~ Time,
data = ChickWeight,
pal = gray(.1),
main = "pal = gray(.1)")

You can even specify palette colors as a vector to selectively color elements:
pirateplot(formula = weight ~ Time,
data = ChickWeight,
main = "Selective color adjustment",
pal = gray(c(rep(.9, 5), .1, rep(.9, 3), .1)))

Customising elements
Regardless of the theme you use, you can always customise the color and opacity of graphical elements. To do this, specify one of the following arugments. Note: Arguments with .f.
correspond to the filling of an element, while .b.
correspond to the border of an element:
Customising plotting elements
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",
bean.f.o = .2, # Bean fill
point.o = .2, # Points
inf.f.o = .4, # Inference fill
inf.b.o = .8, # Inference border
avg.line.o = 1, # Average line
inf.f.col = "white", # Inf fill col
inf.b.col = "black", # Inf border col
point.col = "black", # point col
avg.line.col = "black", # avg line col
point.cex = .5 # Small points
)

If you don’t want to start from scratch, you can also start with a theme, and then make selective adustments:
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
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:
pirateplot(formula = weight ~ Time,
data = ChickWeight,
main = "Reducing a pirateplot to a barplot",
theme = 0, # Start from scratch
bar.f.o = .7, # Just turn on the bars
gl.col = gray(.7)
)

Additional arguments
There are several more arguments that you can use to customise your plot:
Additonal pirateplot elements
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 |
Here’s an example using a background color, gridlines, and quantile lines.
pirateplot(formula = weight ~ Time,
data = ChickWeight,
main = "Chicken weights by Time",
theme = 2,
back.col = gray(.95), # Add light gray background
gl.col = "gray", # Gray gridlines
gl.lwd = c(.75, .5),
quant = c(.1, .9), # 10th and 90th quantiles
quant.col = "black" # Black quantile lines
)

Multiple IVs
You can use up to 3 categorical IVs in your plot. Here are some examples:
pirateplot(formula = height ~ sex + eyepatch,
data = pirates,
main = "Pirate Heights",
theme = 2,
gl.col = gray(.7))

pirateplot(formula = time ~ genre + sequel,
data = subset(movies,
genre %in% c("Action", "Adventure", "Comedy") &
time > 0),
main = "Movie running times",
theme = 2,
gl.col = gray(.7),
inf.f.col = piratepal("basel")[1:3],
bean.f.o = .1,
point.o = .05,
avg.line.o = 0
)

Contribute!
I am very happy to receive new contributions and suggestions to improve the pirateplot. If you come up a new theme (i.e.; customisation) that you like, or have a favorite color palette that you’d like to have implemented, please contact me (yarrr.book@gmail.com) or post an issue at www.github.com/ndphillips/yarrr/issues and I might include it in a future update.