beeswarm: Bee swarm plot

Description

Create a bee swarm plot. A bee swarm plot is a one-dimensional scatter plot similar to "stripchart", except that would-be overlapping points are separated such that each is visible.

Usage

## S3 method for class 'formula':
beeswarm(formula, data = NULL, subset, na.action = NULL, 
         pwpch = NULL, pwcol = NULL, pwbg = NULL, dlab, glab, ...)
## S3 method for class 'default':
beeswarm(x, 
    method = c("center", "hex", "square", "smile"), 
    vertical = TRUE, horizontal = !vertical, 
    cex = par("cex"), spacing = 1, breaks = NULL,
    labels, at = NULL, 
    pch = 1, col = 1, bg = col,
    pwpch = NULL, pwcol = NULL, pwbg = pwcol,
    do.plot = TRUE, add = FALSE, 
    xlim, ylim, log = FALSE, 
    xlab = NULL, ylab = NULL, dlab = "", glab = "",
    ...)

Arguments

formula

A formula, such as y ~ grp, where y is a numeric vector of data values to be split into groups according to the grouping variable grp (usually a factor).

data

A data.frame (or list) from which the variables in formula should be taken.

subset

An optional vector specifying a subset of observations to be used for plotting.

na.action

A function which indicates what should happen when the data contain NAs. The default is to ignore missing values in either the response or the group.

A list of numeric vectors, each of which is plotted as an individual swarm.

method

Method for arranging points (see Details).

vertical, horizontal

Orientation of the plot. horizontal takes precedence if both are specified.

cex

Relative size of points. Unlike other plotting functions, this must be a single value.

spacing

Relative spacing between points.

breaks

Breakpoints (optional). If NULL, breakpoints are chosen automatically. If NA, bins are not used (similar to stripchart with method = "stack").

labels

Labels for each group. By default, these are inferred from the data.

Numeric vector giving the locations where the swarms should be drawn; defaults to 1:n where n is the number of groups.

pch, col, bg

Plotting characters and colors, specified by group (see Details).

pwpch, pwcol, pwbg

"Point-wise" plotting characters and colors, specified for each data point (see Details).

do.plot

Draw a plot?

add

Add to an existing plot?

xlim, ylim

Limits of the plot.

log

Use a logarithmic scale on the data axis?

xlab, ylab

Axis labels.

dlab, glab

An alternate way to specify axis labels (see Details).

...

Further arguments passed to plot.

Value

A data frame with plotting information, invisibly.

Details

This function is similar to stripchart, except with different methods for placing the points, and with a few extra features.

Several methods for placing the points are available; each is designed to avoid overlapping points:

The first three methods first discretize the values along the data axis, in order to create more efficient packing: square stacks the points on a square grid, whereas hex uses a hexagonal grid. center uses an adjusted square grid to produce a symmetric swarm.

By default, the number of breakpoints for discretization is determined by a combination of the available plotting area and the plotting character size. Therefore, in contrast to most plotting functions, changing the plotting window size will often change the position of the points.

The discretization of the data can be explicitly controlled using breaks. If breaks is set to NA, the data will not be grouped into intervals; this may be a sensible option if the data is already discrete.

The fourth method, smile, does not discretize the data. Instead the points are simply shifted sideways (along the group axis) by a minimal amount, producing a somewhat erratic looking figure. breaks is ignored.

The plotting characters and colors can be controlled in two ways. First, the arguments pch, col and bg can specify plotting characters and colors in the same way as stripchart and boxplot: in short, the arguments apply to each group as a whole (and are recycled if necessary).

Alternatively, the characteristics of each individual data point can be controlled using pwpch, pwcol, and pwbg, which override pch, col and bg if these are also specified. These arguments can be specified as a list or vector. If supplied using the formula method, the arguments can be specified as part of the formula interface; i.e. they are affected by data and subset.

The dlab and glab labels may be used instead of xlab and ylab if those are not specified. dlab applies to the continuous data axis (the Y axis unless horizontal is TRUE), glab to the group axis.

This function is intended to be mostly compatible with calls to stripchart or boxplot. Thus, code that works with these functions should work with beeswarm with minimal modification.

Examples

Run this code

## One of the examples from 'stripchart'
  beeswarm(decrease ~ treatment,
    data = OrchardSprays, log = TRUE, 
    pch = 16, col = rainbow(8))

  ## Demonstrating the use of 'pwcol'
  data(breast)
  beeswarm(ESR1 ~ ER, data = breast,
    pch = 16, pwcol = event_survival + 1)
  legend('topleft', legend = c('censored', 'metastasis'),
    pch = 16, col = 1:2)

  ## Demonstrating 'smile' method
  beeswarm(time_survival ~ event_survival, data = breast,
    method = 'smile',
    pch = 16, pwcol = as.numeric(ER),
    xlab = '', ylab = 'Follow-up time (months)',
    labels = c('Censored', 'Metastasis'))
  legend('topright', legend = levels(breast$ER),
    title = 'ER', pch = 16, col = 1:2)

  ## The list interface
  distributions <- list(runif = runif(100, min = -3, max = 3), 
                        rnorm = rnorm(100))
  beeswarm(distributions, col = 2:3)

  ## the "bg" argument only has an effect if "pch" is in 21:25
  beeswarm(distributions, pch = 21, bg = 2:3)

  ## the "smile" method
  beeswarm(distributions, col = 2:3, method = 'smile')

  ## use of pwcol with the list interface 
  myCol <- lapply(distributions, cut, breaks = 8)
  beeswarm(distributions, pch = 16, pwcol = myCol)
  
  ## log scale
  beeswarm(1:200, log = TRUE)