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

1. points, symbols representing the raw data (jittered horizontally)
2. bar, a vertical bar showing central tendencies
3. bean, a smoothed density (inspired by Kampstra et al. (2008)) representing a smoothed density
4. 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()

Themes

pirateplot() currently supports three themes which change the default look of the plot. To specify a theme, use the theme argument:

# Theme 1 (the default)
pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  theme = 1,
  main = "theme = 1"
)

# Theme 2
pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  theme = 2,
  main = "theme = 2"
)

# Theme 3
pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  theme = 3,
  main = "theme = 3"
)

# Theme 4
pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  theme = 4,
  main = "theme = 4"
)

# 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:

piratepal("all")

For example, here is a pirateplot using the "pony" palette

pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  pal = "pony",
  theme = 1,
  main = "pony 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 from theme 2 by specifying pal = 'black'

pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  theme = 2,
  pal = "black",
  main = "pal = 'black"
)

Customising elements

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:

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:

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

Additional arguments

There are several more arguments that you can use to customize your plot:

Here’s an example using a background color, and quantile lines.

pirateplot(
  formula = weight ~ Time,
  data = ChickWeight,
  main = "Adding quantile lines and background colors",
  theme = 2,
  back.col = gray(.98), # Add light gray background
  gl.col = "gray", # Gray gridlines
  gl.lwd = c(.75, 0), # Gridline widths (alternating)
  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
  yaxt.y = seq(0, 400, 50) # Locations of y-axis tick marks
)

Multiple IVs

You can use up to 3 categorical IVs in your plot. Here are some examples:

pirateplot(
  formula = height ~ sex + eyepatch,
  data = pirates,
  theme = 2,
  inf.disp = "bean"
)

# Same as before, but with second IV on different plots by including beside = FALSE
pirateplot(
  formula = height ~ sex + eyepatch,
  data = pirates,
  theme = 2,
  beside = FALSE,
  inf.disp = "bean"
)

# Same as before, but with second IV on different plots by including beside = FALSE
pirateplot(
  formula = weight ~ Time + Diet,
  data = ChickWeight,
  theme = 2,
  beside = FALSE
)

pirateplot(
  formula = height ~ sex + eyepatch + headband,
  data = pirates,
  theme = 2,
  inf.disp = "bean"
)

Output

If you include the plot = FALSE argument to a pirateplot, the function will return some values associated with the plot.

times.pp <- pirateplot(
  formula = time ~ sequel + genre,
  data = subset(
    movies,
    genre %in% c("Action", "Adventure", "Comedy", "Horror") &
      rating %in% c("G", "PG", "PG-13", "R") &
      time > 0
  ),
  plot = FALSE
)

Here’s the result. The most interesting element is $summary which shows summary statistics for each bean:

times.pp

## $summary
##   sequel     genre bean.num   n       avg    inf.lb   inf.ub
## 1      0    Action        1 233 114.73391 112.43863 117.0773
## 2      1    Action        2  80 120.47500 116.22305 123.9434
## 3      0 Adventure        3 206 106.36408 103.43893 109.1944
## 4      1 Adventure        4  78 118.64103 112.26745 124.9704
## 5      0    Comedy        5 400 102.01500 100.77308 102.9995
## 6      1    Comedy        6  51 101.21569  98.14873 103.9931
## 7      0    Horror        7  79 102.13924  98.47381 105.3967
## 8      1    Horror        8  23  97.65217  92.80024 101.7407
## 
## $avg.line.fun
## [1] "mean"
## 
## $inf.method
## [1] "hdi"
## 
## $inf.p
## [1] 0.95

Specifying individual point parameters

If you want to customize the look of individual points in the plot, you can specify them with an additional pointpars argument. This should be a dataframe with the same number of rows as data, and column names in the set col, bg, pch, labels, jitter.

For example, here is a plot with additional point labels and custom jitter values:

# Create a smaller version of the ChickWeight data
ChickWeight2 <- ChickWeight[sample(nrow(ChickWeight), size = 100), ]

# Define labels, jitter values, and colors for all individual points
pointpars <- data.frame(
  "labels" = 1:100,
  "jitter" = rep(c(-.1, .1),
    length.out = 100
  ),
  "col" = sample(colors(),
    size = 100,
    replace = TRUE
  )
)

# Createpireatplot with custom point parameters
pirateplot(
  formula = weight ~ Diet,
  data = ChickWeight2,
  pointpars = pointpars,
  point.o = 1
)

References

The pirateplot is really a knock-off of the great beanplot package and visualization from Kampstra et al. (2008).