A beeswarm plot displays individual data points along a numeric axis, spreading them out so they do not overlap (like a swarm of bees). It is a transparent alternative to box plots or violin plots because every observation is visible. When a grouping variable is supplied, one swarm is drawn per group along the opposite axis.
The layout is computed with a D3 force simulation that pulls each point toward its true value on the x-axis while resolving collisions so no two circles overlap.
The plot is interactive: hovering a point highlights it while dimming the
rest of the swarm, and (when tooltip columns are supplied) shows a
tooltip with those columns' values. When a group is supplied,
hovering a group label focuses that swarm and clicking a label toggles it
on or off. An optional mean/median reference line can be drawn per swarm.
The interactive behaviors are controlled by tooltip, hover,
animate, and stat.
beeswarm_plot(
data,
x,
group = NULL,
tooltip = NULL,
hover = TRUE,
animate = TRUE,
stat = c("none", "mean", "median"),
statColor = "#d62728",
col = "steelblue",
colorPalette = "Tableau10",
radius = 4,
opacity = 0.75,
stroke = "white",
strokeWidth = 0.5,
xtitle = NULL,
xtitleFontSize = 13,
title = NULL,
titleFontSize = 16,
xFontSize = 11,
yFontSize = 11,
font = "Verdana, Geneva, Tahoma, sans-serif",
bgcol = "white",
axisCol = "black",
width = NULL,
height = NULL
)The data frame containing the variables to consider.
The name of the numeric column whose distribution is displayed.
Optional. The name of a categorical column used to split
the data into separate swarms. Defaults to NULL (single swarm).
Optional. A column name, or a vector of column names, whose
values are shown in a tooltip when a point is hovered. Each column appears
on its own line as "column: value". When NULL (default) no
tooltip is shown.
Logical. When TRUE (default), hovering a point
enlarges it and dims the rest of the swarm to make it stand out.
Logical. When TRUE (default), points grow into
place with a short staggered entry animation on first render.
Character. Draws a reference line per swarm at the
"mean" or "median" of the values. Defaults to
"none" (no line).
Color of the mean/median reference line and its label.
Defaults to "#d62728".
Fill color of the points when no group is supplied.
Defaults to "steelblue".
D3 categorical color scheme used when group
is supplied (e.g. "Tableau10", "Category10", "Set2").
Defaults to "Tableau10".
Radius of each point in pixels. Defaults to 4.
Fill opacity of the points (0 to 1). Defaults to 0.75.
Stroke color of the points. Defaults to "white".
Stroke width in pixels. Defaults to 0.5.
Optional. Title of the x-axis.
Font size of the x-axis title. Defaults to 13.
Optional. Title of the chart.
Font size of the chart title. Defaults to 16.
Font size of the x-axis tick labels. Defaults to 11.
Font size of the y-axis group labels. Defaults to 11.
The font family used for all text. Defaults to
"Verdana, Geneva, Tahoma, sans-serif".
Background color of the SVG. Defaults to "white".
Color of axis lines, ticks, and labels. Defaults to
"black".
Optional. The width of the SVG output.
Optional. The height of the SVG output.
An SVG beeswarm plot.
library(ggplot2) # for the mpg dataset
# Single swarm — distribution of highway fuel economy
beeswarm_plot(
data = mpg,
x = "hwy",
col = "steelblue",
xtitle = "Highway miles per gallon",
title = "Distribution of hwy"
)
# Grouped swarm — hwy by vehicle class
beeswarm_plot(
data = mpg,
x = "hwy",
group = "class",
xtitle = "Highway miles per gallon",
title = "Highway fuel economy by vehicle class"
)
# Grouped swarm on the iris dataset
beeswarm_plot(
data = iris,
x = "Sepal.Length",
group = "Species",
colorPalette = "Set2",
radius = 5,
xtitle = "Sepal length (cm)",
title = "Sepal length by species"
)
# Interactive extras: median line per swarm and a tooltip label column
beeswarm_plot(
data = mpg,
x = "hwy",
group = "class",
tooltip = "model",
stat = "median",
xtitle = "Highway miles per gallon",
title = "Highway fuel economy by vehicle class"
)