beeswarm

beeswarm is an add-on package for the R statistical environment. The bee swarm plot is a one-dimensional scatter plot like "stripchart", but with closely-packed, non-overlapping points.

As with most R packages, beeswarm can be obtained from CRAN, or can can be downloaded and installed automatically by entering the following at the R prompt:

install.packages('beeswarm')

Please send questions or comments about beeswarm to Aron.

News

May 7, 2012: Version 0.1.5 is now available from CRAN. Notable new features:

• Proper stratification of formulae such as x ~ y * z (i.e. now beeswarm splits into groups according to both y and z, as "boxplot" does)
• "beeswarm" now has methods (selected by the argument "corral") to control the spread of swarms into adjacent groups (see example below).
• New accessory function "bxplot", a minimalistic interpretation of "boxplot" for adding quantile lines to beeswarm plots (see example below).

Aug 4, 2011: Version 0.1.1 is now available from CRAN. This version fixes several bugs, offers improved support for logarithmic scales, and features new stand-alone functions to add swarms to an existing plot. There are also minor interface changes; notably the "smile" method is now called "swarm", and this is now the default method.

Examples

library(beeswarm)

stripchart vs. beeswarm

stripchart(decrease ~ treatment, data = OrchardSprays, 
  vertical = TRUE, log = "y", method = 'jitter', jitter = 0.2, cex = 1,
  pch = 16, col = rainbow(8),
  main = 'stripchart')
beeswarm(decrease ~ treatment, data = OrchardSprays, 
  log = TRUE, pch = 16, col = rainbow(8),
  main = 'beeswarm')

The color of individual points can be specified

data(breast)
  beeswarm(time_survival ~ ER, data = breast,
    pch = 16, pwcol = 1 + as.numeric(event_survival),
    xlab = "", ylab = "Follow-up time (months)",
    labels = c("ER neg", "ER pos"))
  legend("topright", legend = c("Yes", "No"),
    title = "Censored", pch = 16, col = 1:2)

Compare the four methods for arranging points

## Generate some random data
set.seed(123)
distro <- list(runif = runif(100, min = -3, max = 3), 
               rnorm = rnorm(100))

for (m in c("swarm", "center", "hex", "square")) {
  beeswarm(distro, 
    col = 2:3, pch = 16,
    method = m, 
    main = paste('method = "', m, '"', sep = ''))
}

Compare the five "corral" methods

for (ii in c("none", "gutter", "wrap", "random", "omit")) {
  beeswarm(distributions, 
    pch = 21, col = 2:4, bg = "#00000050",
    corral = ii, 
    main = paste('corral = "', ii, '"', sep = ''))
}

Combining beeswarms with "boxplot" or "bxplot"

  boxplot(len ~ dose, data = ToothGrowth, 
    outline = FALSE,     ## avoid double-plotting outliers, if any
    main = 'boxplot + beeswarm')
  beeswarm(len ~ dose, data = ToothGrowth, 
    col = 4, pch = 16, add = TRUE)

  beeswarm(len ~ dose, data = ToothGrowth, 
    col = 4, pch = 16,
    main = 'beeswarm + bxplot')
  bxplot(len ~ dose, data = ToothGrowth, add = TRUE)