Skip to main content
v2026.11,986 entries · CC-BY 4.0

Beeswarm Plot: What It Shows and How to Make One in Python, MATLAB and R

What a beeswarm plot shows, how to read it, and how to make one with seaborn swarmplot, MATLAB swarmchart, R and SHAP, with the differences between them.

Written and maintained by CASRAI Editorial Board

Published

On this page

A beeswarm plot draws every observation as its own point along a single value axis and spreads the points sideways within each category so they do not sit on top of one another. It shows the full distribution of a measurement, group by group, without hiding the individual values behind a box or a bar. Python (seaborn swarmplot), MATLAB (swarmchart), R (ggbeeswarm) and the SHAP library for model explanation all produce one, but they do not arrange the points the same way.

What is a beeswarm plot, and what is it used for in research?

A beeswarm plot is a categorical scatter plot in which the position along the categorical axis is used only to keep points apart. The value being measured sits on the other axis. Because every point is plotted, a reader can see the sample size, the spread, clusters, gaps and outliers in each group at once. That is why journals and reporting guidelines that ask authors to show individual data points often get met with this chart type for small and moderate groups, such as assay replicates, per-patient measurements or per-run benchmark scores.

It sits between two familiar choices. A summary chart (bar, box or violin) compresses a group into a few numbers or a smoothed outline. A raw strip chart keeps every point but lets random jitter pile points up. The beeswarm keeps every point and uses a layout rule to separate them. For the box and violin alternatives see the site guide on seaborn violin plots; for the R-only treatment of the same chart see ggbeeswarm.

Swarm plot, swarmplot, swarmchart and seaborn stripplot: same thing?

The names are used for closely related charts. Swarmplot is the seaborn function name and swarmchart is the MATLAB function name; both draw a beeswarm. A strip plot (seaborn stripplot) draws the same kind of categorical scatter but offsets points with random jitter, so points can overlap. The practical difference is covered under the strip-plot question below, and the dedicated guide is strip plot.

What is the difference between a strip plot and a scatter plot?

A scatter plot places each observation by two numeric values, so both axes carry measurement. A strip plot is a scatter plot in which one axis is a category: points for each group fall in a single column (or row), and the small sideways offset carries no meaning. In a strip plot that offset is random jitter; in a beeswarm it is calculated to separate points. Use a scatter plot to show how two numeric variables relate and a strip or beeswarm plot to compare the distribution of one numeric variable across groups.

How do the Python, MATLAB, R and SHAP versions arrange the points?

The data table below compares the four implementations by function, placement rule and main parameters, using each project’s own documentation. The most important difference is the placement rule. According to the MATLAB documentation, swarmchart offsets points with uniform random values weighted by a Gaussian kernel density estimate of the y values, so the swarm shape follows the density but the placement is still random. The seaborn documentation describes swarmplot as a categorical scatter plot that adjusts points along the categorical axis, and warns that when there are too many points they overlap and a warning is issued. In practice that means the same data can look slightly different between tools, and a swarm from swarmchart can differ between runs unless the random state is fixed.

Install or access

Each tool is obtained from its own project.

  • Python, seaborn: install the seaborn package (for example pip install seaborn) and import it as import seaborn as sns. The documentation used here is seaborn 0.13.2.
  • MATLAB: swarmchart is a built-in MATLAB function introduced in R2020b. Horizontal swarm charts (jitter along y) were added in R2023b.
  • R: the ggbeeswarm package adds geom_beeswarm to ggplot2; the walkthrough is in the R pointer section below.
  • SHAP: install the shap package (for example pip install shap); the plot is shap.plots.beeswarm.

Step-by-step: make a beeswarm plot in Python with seaborn

These steps use the seaborn documentation’s own example data set, tips, which seaborn can load with sns.load_dataset.

  1. Import the library and load data: import seaborn as sns, then tips = sns.load_dataset('tips').
  2. Draw one swarm for a single numeric variable: sns.swarmplot(data=tips, x='total_bill').
  3. Split by a category: sns.swarmplot(data=tips, x='total_bill', y='day'). The categorical variable goes on one axis and the numeric variable on the other; seaborn infers orientation, or you can set orient='h' explicitly.
  4. Add a second grouping with colour: sns.swarmplot(data=tips, x='total_bill', y='day', hue='sex').
  5. Separate the colour groups side by side: add dodge=True.
  6. Shrink the markers if the plot is crowded: size=3. The size argument is the marker radius in points and defaults to 5.
  7. Keep a numeric axis honest: if the grouping variable is numeric and you want its real spacing, add native_scale=True (available from seaborn 0.13.0).
  8. For one panel per subgroup, use the figure-level function: sns.catplot(data=tips, kind='swarm', x='time', y='total_bill', hue='sex', col='day', aspect=.5).

Other keyword arguments listed in the signature include order, hue_order, palette, color, edgecolor, linewidth (default 0), log_scale, legend (default ‘auto’) and warn_thresh (default 0.05), and extra keyword arguments are passed to matplotlib’s Axes.scatter.

Step-by-step: make a beeswarm plot in MATLAB with swarmchart

  1. Create the grouping variable x and the measurement y as vectors of equal length.
  2. Call swarmchart(x,y). Optional arguments set marker size (swarmchart(x,y,sz)), colour (swarmchart(x,y,sz,c)) and filled markers (swarmchart(x,y,'filled')). A table form is swarmchart(tbl,xvar,yvar).
  3. Return the chart object with s = swarmchart(___) to change properties afterwards, for example s.XJitter = 'rand' and s.XJitterWidth = 0.5.
  4. For overlapping points, use transparency: swarmchart(x,y,'filled',MarkerFaceAlpha=0.5,MarkerEdgeAlpha=0.5).
  5. For a horizontal swarm in R2023b or later, jitter along y: swarmchart(x,y,YJitter='density').

The XJitter property accepts 'none', 'density' (the default), 'rand' and 'randn'. 'density' uses a kernel density estimate of the y values. XJitterWidth sets the maximum jitter in data units; by default the maximum spread is 0.9 times the smallest difference between unique x values.

R pointer

In R, geom_beeswarm from ggbeeswarm is the usual route, and ggforce offers related position adjustments. The site already documents both: see ggbeeswarm and ggforce. This guide does not repeat that material.

What is a SHAP beeswarm plot and how do you interpret it?

A SHAP beeswarm plot summarises a machine-learning model’s explanation across a whole data set. It is not a categorical scatter plot of raw data: it is built from a SHAP Explanation object (samples by features) and each row is a model feature. The SHAP documentation describes it as a plot coloured by feature values when they are provided: each instance is one dot on every feature row, the x position of the dot is its SHAP value, and colour shows the original value of that feature.

Rows are ordered by default using the mean absolute SHAP value of each feature (shap.Explanation.abs.mean(0)), so the feature with the largest average impact appears first. The documentation notes that ordering by the maximum absolute value instead can bring forward features that matter a great deal for a few individual cases. By default only the top 10 features are shown (max_display=10), and group_remaining_features=True adds one row that sums the rest. Calling it with show=False returns the matplotlib Axes so that you can adjust the figure.

How do you interpret a beeswarm plot?

  1. Start with the value axis. Read where each group’s points sit along the measurement axis and compare their centres and ranges.
  2. Treat the sideways spread as layout, not data. The category axis position inside a group has no numeric meaning. A wide swarm means many points at similar values in a seaborn plot, because points are pushed apart to avoid overlap. In MATLAB’s default mode the width follows the estimated density of the values.
  3. Count the points. Every dot is an observation, so small groups are visible as such. This is the main advantage over a bar or box chart.
  4. Look for gaps, clusters and outliers that a summary would smooth over.
  5. Add a summary if readers need one. Overlaying a median or mean marker is an editorial choice, not a feature of these functions: label what it represents.
  6. For a SHAP beeswarm, read each row as one feature: spread along x shows how much that feature moves model output across samples, and the colour shows whether high or low feature values sit on each side. A SHAP plot describes the fitted model, not causal effects in the world.

Beeswarm plot: common problems and fixes

Warning that points overlap or do not fit

seaborn’s documentation says swarmplot does not scale well to large numbers of observations; when the plot is too dense points are drawn overlapping in the gutters and a warning is issued. Reduce size, enlarge the figure, or switch to a strip plot with transparency or a violin or box plot for large groups.

The swarm looks different every time (MATLAB)

Because swarmchart jitters with random numbers shaped by density, two runs may not give the same picture. If you need a repeatable figure for a manuscript, set the random seed before plotting, or use XJitter='none' when you only need aligned points.

Categories drawn in the wrong order or spacing

In seaborn, pass order=[...] (and hue_order) to control the sequence. If a numeric grouping variable is being treated as equally spaced categories, use native_scale=True.

Colour groups on top of each other

Add dodge=True in seaborn so each hue level gets its own lane.

Points hidden in a SHAP plot

Raise max_display to show more features, or lower the marker size s (default 16) and set alpha below 1 to see overlapping dots.

Beyond the tools above, the same chart family can be built in several free open-source environments. The table below lists only the ones this guide’s sources document. The data table that follows compares the same tools in more detail.

Tool Function Where to read more
seaborn (Python) sns.swarmplot, sns.catplot(kind='swarm') seaborn documentation
ggbeeswarm (R) geom_beeswarm ggbeeswarm package documentation and the R pointer section above
SHAP (Python) shap.plots.beeswarm SHAP guide, SHAP documentation
MATLAB swarmchart MathWorks documentation (commercial software)

Frequently asked questions

What are beeswarm plots?

Beeswarm plots are categorical scatter plots in which each observation is a separate point and points within a category are offset sideways so they stay readable. They show the full distribution per group, including sample size, spread and outliers.

How do you interpret a beeswarm plot?

Read the measurement axis for location and spread, count the points for sample size, and ignore the sideways offset as a numeric quantity. In a SHAP beeswarm, each row is a feature, the x position of a dot is its SHAP value and colour is the feature’s original value.

What is the difference between a strip plot and a scatter plot?

A scatter plot uses two numeric axes. A strip plot has one categorical axis, and the offset within a category is only jitter to reduce overplotting. A beeswarm is a strip-style plot whose offsets are calculated to separate points.

Is swarmplot the same as a beeswarm plot?

Yes. swarmplot is seaborn’s function for drawing a beeswarm plot. MATLAB calls its version swarmchart.

When should I not use a beeswarm plot?

Avoid it for very large groups: seaborn’s documentation notes it does not scale well to large numbers of observations, and points will overlap. Use a violin plot, box plot or a transparent strip plot instead.

Sources

Data: Beeswarm plot functions compared: seaborn, MATLAB, SHAP and ggbeeswarm

Original compilation of how four documented beeswarm implementations differ in function name, point-placement rule, main parameters and introduction, compiled from the seaborn, MathWorks and SHAP documentation pages read on 2026-11-20 and the site's own ggbeeswarm guide.

Beeswarm plot functions compared: seaborn, MATLAB, SHAP and ggbeeswarm
ToolFunctionPlacement ruleKey parametersVersion note
seaborn (Python)seaborn.swarmplotCategorical scatter with points adjusted along the categorical axis; overlap and a warning when too densesize (default 5), dodge, native_scale, orient, hue, warn_thresh (default 0.05)native_scale added in 0.13.0; docs 0.13.2
MATLABswarmchartRandom jitter weighted by a Gaussian kernel density estimate of y (XJitter='density' default)XJitter (none, density, rand, randn), XJitterWidth, YJitterIntroduced R2020b; YJitter added R2023b
SHAP (Python)shap.plots.beeswarmOne dot per sample on each feature row; x position is the SHAP value, colour is the feature valuemax_display (10), order, color, alpha, s (16), group_remaining_features, showTakes a shap Explanation (samples x features)
ggbeeswarm (R)geom_beeswarmSee the site's ggbeeswarm guideSee the site's ggbeeswarm guideSee the site's ggbeeswarm guide

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · full access

Ask about Beeswarm Plot: What It Shows and How to Make One in Python, MATLAB and R

Full access: large monthly usage, up to 10 source passages behind each answer, and MCP and API access for Claude Code, Codex and other CLIs. Cancel any time.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →