Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
The ggbeeswarm package in R is a specialized data visualization extension for ggplot2 that generates categorical scatterplots—frequently called beeswarm plots or violin point plots—by offsetting individual data points along the categorical axis to eliminate overplotting while faithfully displaying the underlying sample density and distribution shape. By arranging observations deterministically or through low-discrepancy quasi-random sequences rather than adding arbitrary stochastic noise, ggbeeswarm enables researchers to display raw experimental data alongside summary statistics without obscuring sample size, bimodal clustering, or outlier patterns.
What it is used for in research
In empirical scientific research across genomics, pharmacology, neuroscience, and clinical oncology, conveying the true distribution of experimental observations is critical for reproducible inference. For decades, scientific figures relied heavily on traditional summary graphics, such as dynamite plunger bar charts (mean plus standard error) or standard box plots. However, prominent statistical guidelines and editorial policies have repeatedly shown that summary statistics alone can conceal stark differences in sample size, severe skewness, multimodal distributions, and extreme outlier clusters.
To overcome these limitations, researchers frequently turn to stripcharts or jittered scatterplots. Yet standard jittering introduces arbitrary uniform random noise, which can generate artificial visual clusters, create spurious data gaps, or displace data points unpredictably across plot repetitions. The ggplots in R ecosystem solves this challenge through the ggbeeswarm package, created by Erik Clarke, Scott Sherrill-Mix, and Charlotte Dawson. Unlike uniform jittering, ggbeeswarm arranges data points using deliberate physical packing algorithms and low-discrepancy mathematical sequences.
Researchers utilize ggbeeswarm primarily for:
- Transparent reporting of small-to-moderate sample sizes: When comparing experimental cohorts (such as cell culture replicates, patient biopsy measurements, or animal drug trials with 10 to 300 observations per arm), plotting every individual data point is considered best practice. ggbeeswarm ensures that each data point remains distinct and visible.
- Detecting multimodal distributions: When a treated population splits into distinct responder and non-responder subgroups, a standard box plot merely shows an expanded interquartile range. In contrast, a beeswarm plot visually splits the points into distinct clusters along the measurement axis, exposing the underlying biology immediately.
- Combining raw points with summary metrics: ggbeeswarm integrates seamlessly with box plots in R and mean crossbars, enabling authors to present formal median and quartile thresholds without concealing the underlying point distribution.
- Multi-factor experimental comparisons: Using built-in dodging mechanics, ggbeeswarm displays treatment groups subdivided by genotypes, sex, or timepoints side by side without overlapping category boundaries.
By pairing deterministic point packing with the grammar of graphics, researchers produce figures that meet the rigorous reporting standards of high-impact biomedical journals.
How to install or access it
The stable, production-tested version of ggbeeswarm is officially distributed through the Comprehensive R Archive Network (CRAN). As of version 0.7.3 (published on November 29, 2025, licensed under GPL-3), ggbeeswarm requires R version 3.5.0 or higher and ggplot2 version 3.3.0 or higher. The package depends internally on the beeswarm and vipor packages for its point-offset algorithms, along with lifecycle and cli for messaging.
To install ggbeeswarm from CRAN within an interactive R terminal or RStudio console, run the standard package installer command:
# Install ggbeeswarm from CRAN
install.packages("ggbeeswarm")
To confirm that the package and its core dependencies are installed correctly and ready for analysis, load both ggplot2 and ggbeeswarm into your active R session:
# Load libraries into the R environment
library(ggplot2)
library(ggbeeswarm)
# Verify installed package version
packageVersion("ggbeeswarm")
# Expected output: [1] '0.7.3'
For researchers contributing to package development or requiring the latest unreleased patches, the source repository is hosted officially on GitHub at https://github.com/eclarke/ggbeeswarm. You can install the development version using the remotes package directly from GitHub:
# Install development version from official GitHub repository
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github("eclarke/ggbeeswarm")
Because ggbeeswarm contains pre-compiled point layout routines (via the fast C implementation in beeswarm), no specialized external compilation tools or Fortran compilers are required on modern Linux, macOS, or Windows operating systems.
Step-by-step instructions
Building publication-quality beeswarm plots requires mastering the primary geometries provided by ggbeeswarm: geom_beeswarm(), which relies on point-size collision packing from the beeswarm package, and geom_quasirandom(), which leverages low-discrepancy density-driven spacing from the vipor package. Follow these numbered steps to prepare research data, construct the plot, calibrate spacing, and apply publication styling.
1. Prepare experimental data in tidy format
ggplot2 expects data in tidy (long) format where each row represents an individual observation, one column designates the categorical group or condition, and another column contains the continuous numeric measurement. Here we simulate a controlled biomedical experiment comparing a vehicle control with two drug treatment doses across 150 biological replicates:
# Set seed for reproducible synthetic experimental cohort
set.seed(42)
# Construct tidy data frame
n_per_group <- 50
df_experiment <- data.frame(
Treatment = rep(c("Vehicle", "Dose_10mg", "Dose_50mg"), each = n_per_group),
Biomarker_Level = c(
rnorm(n_per_group, mean = 24.5, sd = 4.2),
rnorm(n_per_group, mean = 38.1, sd = 5.0),
c(rnorm(n_per_group - 15, mean = 55.4, sd = 4.8), rnorm(15, mean = 72.0, sd = 3.5))
),
Genotype = rep(c("WildType", "Knockout"), times = 75)
)
# Ensure categorical variables are factors with controlled level order
df_experiment$Treatment <- factor(df_experiment$Treatment, levels = c("Vehicle", "Dose_10mg", "Dose_50mg"))
df_experiment$Genotype <- factor(df_experiment$Genotype, levels = c("WildType", "Knockout"))
2. Construct a baseline plot using geom_beeswarm()
The core geometry geom_beeswarm() offsets points horizontally (when the categorical grouping is on the x-axis) such that points with similar values do not overlap. The fundamental syntax mirrors standard scatterplots in R layers:
# Basic beeswarm plot
p_basic <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level, color = Treatment)) +
geom_beeswarm(size = 2.0, alpha = 0.85) +
labs(
title = "Biomarker Response by Treatment Cohort",
x = "Treatment Arm",
y = "Serum Biomarker Concentration (ng/mL)"
)
print(p_basic)
3. Calibrate point spacing using cex, priority, and method
The arrangement and density of the swarm can be fine-tuned using three primary arguments in geom_beeswarm():
cex: A positive numeric multiplier that scales point spacing. Values between 1.0 and 3.0 work best. Increasingcexforces points farther apart, widening the swarm; decreasingcexpacks points more compactly.priority: Governs the sequence in which observations are arranged. The default is"ascending", which sorts values from lowest to highest. Using"density"places points located in high-density regions first, producing an aesthetically balanced swarm centered on the median. Other supported options are"descending","random", and"none".method: Selects the spatial packing algorithm. Options include"swarm"(default sequential placement),"compactswarm"(a greedy packing routine that minimizes distance to the center axis),"hex"(hexagonal lattice grid),"square"(square grid), and"center"(symmetric grid).
# Calibrated beeswarm using density priority and compact packing
p_tuned <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level, color = Treatment)) +
geom_beeswarm(
method = "compactswarm",
priority = "density",
cex = 1.8,
size = 2.2,
alpha = 0.8
)
print(p_tuned)
4. Contain runaway points using corral boundaries
When analyzing large cohorts or distributions with heavy tails, unconstrained beeswarm swarms can spread excessively wide, colliding with adjacent category columns. To prevent column overlap, geom_beeswarm() provides the corral and corral.width parameters:
corral = "none": Default behavior. Points spread as far as necessary to avoid collision.corral = "gutter": Constrains points within a bounding corridor (defined bycorral.width, default 0.9). Points that would exceed this width are placed neatly along the vertical boundary lines.corral = "wrap": Re-enters overflowing points from the opposite boundary side using periodic wrapping.corral = "random": Re-positions overflowing points randomly within the allotted corridor width.corral = "omit": Drops points that exceed the corridor boundary entirely.
# Enforcing gutter boundary coralling
p_corral <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level, color = Treatment)) +
geom_beeswarm(
method = "swarm",
cex = 2.0,
corral = "gutter",
corral.width = 0.8,
size = 2.0
)
print(p_corral)
5. Safeguard measurement accuracy with preserve.data.axis
In certain discretizing methods (such as "square", "hex", or "center"), the underlying algorithm may attempt to bin or slightly adjust point coordinates along the measurement (y) axis to facilitate grid packing. In clinical and laboratory research where exact numerical fidelity is paramount, set preserve.data.axis = TRUE. This guarantees that point coordinates on the measurement axis remain strictly unaltered:
# Ensure exact measurement coordinates are preserved
p_exact <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level, color = Treatment)) +
geom_beeswarm(
method = "center",
preserve.data.axis = TRUE,
cex = 1.5,
size = 2.0
)
print(p_exact)
6. Scale to larger cohorts using geom_quasirandom()
When visualizing cohorts with hundreds or thousands of observations, the collision-detection algorithm of geom_beeswarm() can become computationally expensive. The companion geometry geom_quasirandom() solves this by applying low-discrepancy quasi-random sequences (such as van der Corput sequences or Tukey texturing via the vipor package):
# Scalable quasi-random point layout with variable width
p_quasirandom <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level, color = Treatment)) +
geom_quasirandom(
method = "quasirandom",
varwidth = TRUE,
bandwidth = 0.4,
width = 0.35,
size = 1.8,
alpha = 0.75
)
print(p_quasirandom)
Here, setting varwidth = TRUE automatically scales the maximum width of each swarm relative to the total number of observations in that category, mirroring the intuitive behavior of violin plots.
7. Implement grouping and dodging for two-factor designs
When experiments test multiple factors simultaneously—such as treatment condition stratified by genotype—use the dodge.width parameter to separate factor levels cleanly within each primary category:
# Dodged beeswarm across two experimental factors
p_dodged <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level, color = Genotype)) +
geom_beeswarm(
dodge.width = 0.8,
cex = 1.6,
size = 1.9,
alpha = 0.85
) +
scale_color_manual(values = c("WildType" = "#2b5c8f", "Knockout" = "#d95f02"))
print(p_dodged)
8. Overlay summary statistics and apply publication themes
A complete research graphic combines raw point distributions with summary indicators. Overlay a minimalist box plot or mean crossbar beneath the beeswarm points, then apply a clean theme using ggplot themes conventions:
# Publication-ready combined figure
p_final <- ggplot(df_experiment, aes(x = Treatment, y = Biomarker_Level)) +
# Background box plot showing median and interquartile range
geom_boxplot(
width = 0.35,
outlier.shape = NA,
alpha = 0.3,
color = "#4a4a4a",
fill = "#eaeaea"
) +
# Foreground beeswarm displaying every observation
geom_beeswarm(
aes(color = Treatment),
method = "compactswarm",
priority = "density",
cex = 1.8,
size = 2.2,
alpha = 0.85,
show.legend = FALSE
) +
# Summary crossbar indicating mean +/- standard error
stat_summary(
fun.data = mean_se,
geom = "errorbar",
width = 0.15,
color = "#000000",
linewidth = 0.8
) +
scale_color_manual(values = c("Vehicle" = "#4393c3", "Dose_10mg" = "#f4a582", "Dose_50mg" = "#d6604d")) +
labs(
title = "Serum Biomarker Response Across Treatment Groups",
subtitle = "Points show individual replicates; box indicates median and IQR; error bars show mean +/- SEM",
x = "Treatment Group",
y = "Biomarker Level (ng/mL)"
) +
theme_classic(base_size = 12) +
theme(
plot.title = element_text(face = "bold", size = 14),
plot.subtitle = element_text(color = "#555555", size = 10, margin = margin(b = 10)),
axis.title = element_text(face = "bold"),
axis.text = element_text(color = "#222222")
)
print(p_final)
When compiling multi-panel manuscript figures, you can assemble multiple ggplot objects into aligned panels using cowplot or patchwork.
Output and how to read it
Interpreting a beeswarm graphic correctly requires understanding how point positions along both axes communicate statistical information:
- Measurement axis (vertical in standard orientation): Represents the exact continuous numerical value of each observation. Unless you deliberately bin values without preserving the axis, every point resides at its true vertical coordinate. Inspecting the vertical spread reveals the minimum, maximum, median, and quartile boundaries of each cohort.
- Categorical axis (horizontal in standard orientation): Represents group membership. The horizontal displacement of a point away from the group center line does not indicate a secondary measurement; instead, it is an offset calculated purely to prevent point overlap.
- Swarm profile and density contours: The horizontal width of the swarm at any given measurement level reflects local data density. A wide cluster of points indicates a region with high observation density (the mode), whereas narrow necks indicate sparse regions.
- Bimodal and multimodal patterns: In the Dose_50mg cohort generated in our walkthrough, observing two separate swollen lobes with an intermediate constriction immediately signals a bimodal response—revealing that a subpopulation of subjects responded with significantly higher biomarker levels. A standard box plot would have obscured this phenomenon completely.
- Outlier visibility: Unlike box plots that collapse multiple extreme values into single overlapping outlier asterisks, beeswarm plots display every outlier individually, showing whether extreme values represent isolated singletons or a cohesive cluster of high-magnitude responses.
- Corral boundaries: When
corral = "gutter"is enabled, points aligned in vertical columns along the outer perimeter represent observations that would have overlapped adjacent factor columns. Readers should recognize these perimeter columns as boundary-constrained points rather than distinct experimental sub-cohorts.
The resulting visual representation provides reviewers and readers with complete transparency regarding sample size, central tendency, variance, and distribution geometry in a single, scannable panel.
Troubleshooting
When deploying ggbeeswarm in automated data pipelines or generating figures for submission, researchers commonly encounter several recurring technical hurdles. Use the following diagnostic solutions:
1. Points overlapping or spilling into adjacent categorical columns
Cause: The sample size within a category is large, or points are clustered within an extremely narrow measurement range, causing the horizontal displacement to exceed column margins.
Resolution: Set corral = "gutter" with an explicit corral.width = 0.85 to enforce strict boundary corridors. Alternatively, reduce the point radius using size = 1.5, decrease the spacing multiplier to cex = 1.2, or expand the physical plot dimensions during rendering using ggsave(width = 8, height = 6).
2. Slow rendering and memory overhead on large cohorts
Cause: geom_beeswarm() uses an iterative, collision-based point-packing algorithm that scales quadratically (O(N^2)) with sample size.
Resolution: Ensure that fast = TRUE is active (the default), which executes the compiled C packing routine. For cohorts exceeding 500 observations per category, switch directly to geom_quasirandom(), which computes density kernels in O(N log N) time and renders instantaneously.
3. Dodged groups overlapping or misaligned
Cause: Using dodge.width when the grouping aesthetic (such as color or fill) is mapped to a continuous variable or an un-factored character vector.
Resolution: Explicitly convert the grouping variable to a factor using factor() before passing it to ggplot(). Ensure that dodge.width in geom_beeswarm() matches the dodge.width specified in any complementary summary layers (such as position_dodge(width = 0.8) in geom_boxplot()).
4. Data points subtly shifted off their exact measurement coordinates
Cause: Certain packing methods (such as "square" or "hex") discretize measurement values to fit points onto regular geometric lattices.
Resolution: Explicitly add preserve.data.axis = TRUE to the geom_beeswarm() call. This locks the measurement axis, forcing the algorithm to offset points strictly along the categorical axis.
5. Deprecated argument warnings regarding groupOnX or beeswarmArgs
Cause: Earlier versions of ggbeeswarm utilized groupOnX = TRUE and beeswarmArgs = list(...) to control orientation and pass low-level arguments.
Resolution: In ggbeeswarm version 0.7.3 and later, orientation is inferred automatically from aesthetic mappings. If you need to force horizontal layout where categories are on the y-axis, use orientation = "y" and pass parameters (such as cex, priority, and side) directly as named arguments to geom_beeswarm().
Free alternatives
While ggbeeswarm is the standard tool for categorical scatterplots in the ggplot2 ecosystem, several alternative geometries and packages exist across R and base graphics. The table below outlines key functional differences between available free approaches.
| Tool / Geometry | Package Source | Point Packing Strategy | Primary Strength | Best Cohort Size | License |
|---|---|---|---|---|---|
| geom_beeswarm | ggbeeswarm (CRAN) | Iterative collision avoidance | Strictly non-overlapping points, high visual appeal | 10 to 300 observations per group | GPL-3 |
| geom_quasirandom | ggbeeswarm / vipor (CRAN) | Low-discrepancy quasi-random dispersion | Extremely fast rendering, reflects density shape | 100 to 5,000 observations per group | GPL-3 |
| geom_jitter | ggplot2 (CRAN) | Uniform pseudorandom noise | Built into ggplot2, minimal computational overhead | 50 to 1,000 observations per group | MIT |
| geom_sina | ggforce (CRAN) | Density-bounded jittering (sinaplot) | Restricts jitter strictly within violin density contours | 100 to 10,000 observations per group | MIT |
| beeswarm | beeswarm (CRAN) | Base R non-overlapping swarm | Operates without ggplot2 dependencies in base graphics | 10 to 200 observations per group | Artistic-2.0 |
| stripchart | graphics (Base R) | 1D stacking or uniform jittering | Zero dependencies, available in standard R installations | 5 to 100 observations per group | Part of Base R |
For researchers evaluating these options, the data table below provides a comprehensive comparison of point-offset methods, computational complexities, and parameter controls across R visualization packages. When precise point separation is mandatory for cohorts under 300 samples, geom_beeswarm() remains the premier choice. For larger data volumes where density contour shaping is prioritized over zero-collision packing, geom_quasirandom() or ggforce::geom_sina() offer superior performance.
Frequently asked questions
What is the difference between geom_beeswarm() and geom_quasirandom()?
The primary difference lies in their underlying placement algorithms and computational scalability. geom_beeswarm() uses the beeswarm package algorithm to perform physical collision detection, spacing individual points by their exact point diameter to guarantee zero overlap. This makes it ideal for small-to-moderate sample sizes (10 to 300 observations). In contrast, geom_quasirandom() uses the vipor package to distribute points using mathematical low-discrepancy sequences (such as the van der Corput sequence) or Tukey texturing based on a kernel density estimate. geom_quasirandom() does not guarantee zero overlap, but it scales effortlessly to thousands of observations and renders significantly faster.
How do you prevent points from overlapping across categories in ggbeeswarm?
To prevent points in adjacent categories from overlapping, utilize the corral and corral.width parameters in geom_beeswarm(). Setting corral = "gutter" establishes hard boundaries around each category column (by default corral.width = 0.9). Points that would otherwise spread past the boundary are gathered neatly into vertical boundary gutters. Alternatively, setting corral = "wrap" wraps overflowing points back into the swarm from the opposite side, while corral = "omit" removes overflowing points entirely.
Can ggbeeswarm be combined with box plots or violin plots?
Yes. Because ggbeeswarm operates as a standard ggplot2 layer, you can stack it directly with geom_boxplot() or geom_violin(). When combining layers, place geom_boxplot() first with outlier.shape = NA so that extreme values are not plotted twice, and set alpha = 0.3 to keep the background summary translucent. Then place geom_beeswarm() on top to display every raw data point clearly over the box plot summary.
Does geom_beeswarm alter the actual numerical data values?
In standard usage with method = "swarm", geom_beeswarm() only offsets points along the categorical grouping axis, leaving the continuous measurement axis completely unchanged. However, when using discretizing packing methods such as "square", "hex", or "center", the algorithm may make subtle adjustments along the measurement axis to facilitate regular grid packing. To strictly prevent any modification to measurement values, set preserve.data.axis = TRUE in your geom_beeswarm() call.
How do you dodge beeswarm points across multiple experimental groups?
To display multiple sub-groups side by side within each categorical bin (for example, comparing WildType and Knockout genotypes across three treatment doses), map the sub-group variable to an aesthetic like color or fill, ensure that the variable is an R factor, and specify the dodge.width parameter in geom_beeswarm() (e.g., geom_beeswarm(aes(color = Genotype), dodge.width = 0.8)). Points belonging to different factor levels will be offset into distinct adjacent sub-columns.
Sources
- Clarke, E., Sherrill-Mix, S., and Dawson, C. (2025). ggbeeswarm: Categorical Scatter (Violin Point) Plots (R package version 0.7.3). Comprehensive R Archive Network (CRAN). https://cran.r-project.org/web/packages/ggbeeswarm/index.html (Accessed 2026-11-14).
- Clarke, E., and Sherrill-Mix, S. (2025). ggbeeswarm Reference Manual. Comprehensive R Archive Network (CRAN). https://cran.r-project.org/web/packages/ggbeeswarm/refman/ggbeeswarm.html (Accessed 2026-11-14).
- Eklund, A., and Trimble, J. (2021). beeswarm: The Bee Swarm Plot, an Alternative to Stripchart (R package version 0.4.0). Comprehensive R Archive Network (CRAN). https://cran.r-project.org/web/packages/beeswarm/index.html (Accessed 2026-11-14).
- Sherrill-Mix, S., and Clarke, E. (2023). vipor: Plot Categorical Data Using Quasirandom Noise and Density Estimates (R package version 0.4.7). Comprehensive R Archive Network (CRAN). https://cran.r-project.org/web/packages/vipor/index.html (Accessed 2026-11-14).
- Wickham, H. et al. (2024). ggplot2: Elegant Graphics for Data Analysis. Comprehensive R Archive Network (CRAN). https://ggplot2.tidyverse.org/reference/geom_jitter.html (Accessed 2026-11-14).
- R Core Team. (2024). 1-D Scatter Plots (stripchart). R Graphics Documentation. https://stat.ethz.ch/R-manual/R-devel/library/graphics/html/stripchart.html (Accessed 2026-11-14).
Data: Comparison of Categorical Point Dispersion Methods in R
An original comparative benchmark of categorical point-dispersion methods and geometries in R, compiled from official CRAN reference manuals and documentation for ggbeeswarm, vipor, beeswarm, ggplot2, and base R graphics.
Period covered: 2021/2026. Coverage: Global.
| Method / Geometry | Source Package | Dispersion Mechanism | Guarantees Zero Overlap | Measurement Axis Preserved | Typical Cohort Capacity (observations) |
|---|---|---|---|---|---|
| geom_beeswarm (swarm) | ggbeeswarm | Sequential minimum displacement collision packing | Yes | Yes | 300 |
| geom_beeswarm (compactswarm) | ggbeeswarm | Greedy centroid-adjacent packing | Yes | Yes | 500 |
| geom_beeswarm (square/hex) | ggbeeswarm | Discretized regular lattice packing | Yes | No (unless preserve.data.axis=TRUE) | 400 |
| geom_quasirandom (quasirandom) | ggbeeswarm / vipor | Van der Corput low-discrepancy sequence | No | Yes | 5000 |
| geom_quasirandom (tukey) | ggbeeswarm / vipor | Tukey regular density texturing | No | Yes | 3000 |
| geom_jitter | ggplot2 | Uniform pseudorandom noise perturbation | No | No | 2000 |
| stripchart (stack) | graphics (Base R) | Discrete 1D point stacking bins | Yes | Yes | 150 |
Sources
- ggbeeswarm CRAN Reference Manual (accessed 2026-11-14)
- vipor CRAN Reference Manual (accessed 2026-11-14)
- beeswarm CRAN Package Index (accessed 2026-11-14)
- ggplot2 geom_jitter Documentation (accessed 2026-11-14)
- Base R stripchart Documentation (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







