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
seabornpackage (for examplepip install seaborn) and import it asimport seaborn as sns. The documentation used here is seaborn 0.13.2. - MATLAB:
swarmchartis a built-in MATLAB function introduced in R2020b. Horizontal swarm charts (jitter along y) were added in R2023b. - R: the
ggbeeswarmpackage addsgeom_beeswarmto ggplot2; the walkthrough is in the R pointer section below. - SHAP: install the
shappackage (for examplepip install shap); the plot isshap.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.
- Import the library and load data:
import seaborn as sns, thentips = sns.load_dataset('tips'). - Draw one swarm for a single numeric variable:
sns.swarmplot(data=tips, x='total_bill'). - 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 setorient='h'explicitly. - Add a second grouping with colour:
sns.swarmplot(data=tips, x='total_bill', y='day', hue='sex'). - Separate the colour groups side by side: add
dodge=True. - Shrink the markers if the plot is crowded:
size=3. Thesizeargument is the marker radius in points and defaults to 5. - 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). - 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
- Create the grouping variable x and the measurement y as vectors of equal length.
- 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 isswarmchart(tbl,xvar,yvar). - Return the chart object with
s = swarmchart(___)to change properties afterwards, for examples.XJitter = 'rand'ands.XJitterWidth = 0.5. - For overlapping points, use transparency:
swarmchart(x,y,'filled',MarkerFaceAlpha=0.5,MarkerEdgeAlpha=0.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?
- Start with the value axis. Read where each group’s points sit along the measurement axis and compare their centres and ranges.
- 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.
- 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.
- Look for gaps, clusters and outliers that a summary would smooth over.
- 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.
- 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.
Free alternatives and related tools
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
- seaborn: seaborn.swarmplot, version 0.13.2 documentation, checked 2026-11-20
- MathWorks: swarmchart (MATLAB documentation), checked 2026-11-20
- SHAP documentation: shap.plots.beeswarm, checked 2026-11-20
- SHAP documentation: beeswarm plot example notebook, checked 2026-11-20
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.
| Tool | Function | Placement rule | Key parameters | Version note |
|---|---|---|---|---|
| seaborn (Python) | seaborn.swarmplot | Categorical scatter with points adjusted along the categorical axis; overlap and a warning when too dense | size (default 5), dodge, native_scale, orient, hue, warn_thresh (default 0.05) | native_scale added in 0.13.0; docs 0.13.2 |
| MATLAB | swarmchart | Random jitter weighted by a Gaussian kernel density estimate of y (XJitter='density' default) | XJitter (none, density, rand, randn), XJitterWidth, YJitter | Introduced R2020b; YJitter added R2023b |
| SHAP (Python) | shap.plots.beeswarm | One dot per sample on each feature row; x position is the SHAP value, colour is the feature value | max_display (10), order, color, alpha, s (16), group_remaining_features, show | Takes a shap Explanation (samples x features) |
| ggbeeswarm (R) | geom_beeswarm | See the site's ggbeeswarm guide | See the site's ggbeeswarm guide | See the site's ggbeeswarm guide |
Sources
- seaborn.swarmplot documentation (accessed 2026-11-20)
- MathWorks swarmchart (accessed 2026-11-20)
- SHAP shap.plots.beeswarm (accessed 2026-11-20)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







