pirateplot() guide in the yarrr package

Nathaniel Phillips

2016-10-08

What is a pirateplot()?

A pirateplot, from the yarrr package (devtools::install_github('ndphillips/yarrr', build_vignette = T) is the RDI (Raw data, Descriptive statistics, and Inferential statistics) plotting choice of R pirates who are displaying the relationship between 1 or two categorical independent variables, and one continuous dependent variable.

A pirateplot() has 4 distinct 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 and others (2008)) representing a smoothed density
  4. inf, a rectangle representing an inference interval (either a Bayesian Highest Density Interval or a frequentist confidence interval)

Main arguments

The major arguments to pirateplot() are a dataframe and a formula in the form formula = y ~ x1 + x2, where y is a dependent variable, x1 is a categorical independent variable, and x2 is an optional second independent variable. You can also include most of the the main plotting parameters that you would use for normal plotting functions like main(), xlab(), ylim() (etc.)

pirateplot(formula = time ~ cleaner + type,
           data = poopdeck,
           main = "Poopdeck Cleaning Time")

Colors

You can adjust colors in many ways. You can select an overall color palette using the pal argument, where pal is the name of a color palette in the piratepal() function (to see all the palettes, run piratepal(palette = "all"))

pirateplot(formula = weight ~ Diet,
           data = ChickWeight,
           pal = "xmen")   # Use the xmen color palette

If you specify a single color name in the pal argument, all plotting elements will be that color. For example, to make a gray-scale pirateplot, just use pal = "black"

pirateplot(formula = weight ~ Diet,
           data = ChickWeight,
           pal = "black")

You can override the color of any specific element by using one of the x.col arguments (e.g.; bar.col, point.col, inf.col, line.col). In this example, I’ll change the palette to southpark (try running yarrr::piratepal("southpark", "show")), and then make the points and bars gray.

pirateplot(formula = weight ~ Time,
           data = ChickWeight,
           pal = "southpark",   # Use the southpark color palette,
           point.col = "gray",  # gray points
           bean.border.col = "gray", # gray bean borders
           bar.col = "gray")   # gray bars

Opacities

You can adjust the opacities of individual plotting elements in one of two ways. The theme.o argument allows you to specify an opacity theme. There are currently 3 themes supported. For example, theme.o = 2 will turn off the inference boxes and turn up the bars:

pirateplot(formula = weight ~ Diet,
           data = ChickWeight,
           theme.o = 2, # Use opacity theme 2
           main = "Opacity themes with theme.o")

Or, you can turn off all of the opacities with theme.o = 0 and then selectively turn up individual elements with bar.o, bean.o, point.o, and inf.o:

Here is a plot with only the points

pirateplot(formula = weight ~ Diet,
           data = ChickWeight,
           theme.o = 0, # Turn off all opacities,
           point.o = .1) # Turn point opacities up to .1

Now I’ll add the beans

pirateplot(formula = weight ~ Diet,
           data = ChickWeight,
           theme.o = 0, 
           point.o = .1,
           bean.o = .5) # Turn on beans to .5

Or just make a barplot with HDIs (and a gray palette)

pirateplot(formula = weight ~ Time,
           data = ChickWeight,
           theme.o = 0, 
           bar.o = .5, # Turn bar up to .5
           inf.o = .8, # Turn 95% HDI to .8
           pal = gray(.1))

You can specify the x.o arguments as vectors to selectively turn up (or down) specific elements for specific groups:

pirateplot(formula = weight ~ Diet,
           data = ChickWeight,
           pal = "basel",
           theme.o = 0, # Turn off all opacities,
           point.o = c(.1, .05, .2, .05), # Selectively turn up point opacities
           inf.o = c(.9, .1, .9, .1), # Selectively turn up inf opacities
           bean.o = c(1, .1, 1, .1), # Selective bean opacity adjustment
           main = "Adjusting opacities between groups")

Additional arguments

You can use up to two independent variables in the formula, change the color of the background with back.col, and the color of the gridlines with gl.col

pirateplot(formula = weight ~ Diet + Time,
           data = ChickWeight,
           pal = "google",
           theme.o = 1, # Turn off all opacities,
           back.col = gray(.96),
           gl.col = "white",
           main = "back.col, gl.col")

References

Kampstra, Peter, and others. 2008. “Beanplot: A Boxplot Alternative for Visual Comparison of Distributions.” Journal of Statistical Software 28 (1): 1–9.