A Tukey box-and-whisker plot

This function is a wrapper around a typical ggplot based box-and-whisker plot, i.e. using geom_boxplot, which implements the Tukey variant of the box-and-whisker plot. The y variable is the outcome variable whose distribution is represented by the box-and-whisker plot. If the x variable is missing, then a single box-and-whisker plot using all values of y is shown. If an x variable is used, this is used an the independent variable and one box-and-whisker plot is provided for each set of y values that correspond to each unique value of x. For this reason, x is usually a categorical variable. If x is a continuous numeric variable, it ideally should have relatively few unique values, so that each value of x corresponds to a sufficiently large set of y values.

tukeyboxplot(
  y,
  x,
  data,
  by = NULL,
  jitter = FALSE,
  box_width = 1/3,
  jitter_width = 1/5,
  xlab = NULL,
  ylab = NULL
)

Arguments

y

The outcome variable

x

The optional independent/predictor/grouping variable

data

The data frame with the y and (optionally) x values.

by

An optional variable, usually categorical (factor or character), by which the points in the box-and-whisker plots are grouped and coloured.

jitter

A logical variable, defaulting to FALSE, that indicates if all points in each box-and-whisker plot should be shown as jittered points.

box_width

The width of box in each box-and-whisker plot. The default used, box_width = 1/3, means that boxes will be relatively narrow.

jitter_width

The width of the jitter relative to box width. For example, set jitter_width = 1 if you want the jitter to be as wide the box.

xlab

The label of the x-axis (defaults to the x variable name).

ylab

The label of the y-axis (defaults to the y variable name).

Value

A ggplot2::ggplot object, which may be modified with further ggplot2 commands.

Examples

# A single box-and-whisker plot
tukeyboxplot(y = time, data = vizverb)

# One box-and-whisker plot for each value of a categorical variable
tukeyboxplot(y = time, x = task, data = vizverb)

# Box-and-whisker plots with jitters
tukeyboxplot(y = time, x = task, data = vizverb,  jitter = TRUE)

# `tukeyboxplot` can be used with a continuous numeric variable too
tukeyboxplot(y = len, x = dose, data = ToothGrowth)

tukeyboxplot(y = len, x = dose, data = ToothGrowth,
             by = supp, jitter = TRUE, box_width = 0.5, jitter_width = 1)