beeswarm_plot: Create a beeswarm plot.

In ddplot: Create D3 Based SVG Graphics

Create a beeswarm plot.

Description

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.

Usage

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
)

Arguments

data	The data frame containing the variables to consider.
x	The name of the numeric column whose distribution is displayed.
group	Optional. The name of a categorical column used to split the data into separate swarms. Defaults to NULL (single swarm).
tooltip	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.
hover	Logical. When TRUE (default), hovering a point enlarges it and dims the rest of the swarm to make it stand out.
animate	Logical. When TRUE (default), points grow into place with a short staggered entry animation on first render.
stat	Character. Draws a reference line per swarm at the "mean" or "median" of the values. Defaults to "none" (no line).
statColor	Color of the mean/median reference line and its label. Defaults to "#d62728".
col	Fill color of the points when no group is supplied. Defaults to "steelblue".
colorPalette	D3 categorical color scheme used when group is supplied (e.g. "Tableau10", "Category10", "Set2"). Defaults to "Tableau10".
radius	Radius of each point in pixels. Defaults to 4.
opacity	Fill opacity of the points (0 to 1). Defaults to 0.75.
stroke	Stroke color of the points. Defaults to "white".
strokeWidth	Stroke width in pixels. Defaults to 0.5.
xtitle	Optional. Title of the x-axis.
xtitleFontSize	Font size of the x-axis title. Defaults to 13.
title	Optional. Title of the chart.
titleFontSize	Font size of the chart title. Defaults to 16.
xFontSize	Font size of the x-axis tick labels. Defaults to 11.
yFontSize	Font size of the y-axis group labels. Defaults to 11.
font	The font family used for all text. Defaults to "Verdana, Geneva, Tahoma, sans-serif".
bgcol	Background color of the SVG. Defaults to "white".
axisCol	Color of axis lines, ticks, and labels. Defaults to "black".
width	Optional. The width of the SVG output.
height	Optional. The height of the SVG output.

Value

An SVG beeswarm plot.

Examples

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"
)

ddplot documentation built on Aug. 25, 2026, 5:10 p.m.