Implement geom_beeswarm using a quasi-random algorithm by const-ae · Pull Request #1068 · has2k1/plotnine

const-ae · 2026-06-07T21:29:49Z

Fixes #318.

This PR implements a beeswarm algorithm that produces a (in my opinion) visually more appealing output than the random sampling implemented in geom_sina.

n = 200
df = pd.concat([
    pd.DataFrame({'y': np.random.RandomState(125).normal(0, 10, n), 'x': "beeswarm"}),
    pd.DataFrame({'y': np.random.RandomState(125).normal(0, 10, n), 'x': "sina"}),
])
(ggplot(df, aes(x = 'x', y = 'y')) +
    geom_beeswarm(data = lambda df: df[df['x'] == 'beeswarm'], maxwidth = 0.4) +
    geom_sina(data = lambda df: df[df['x'] == 'sina'], maxwidth = 0.4)
)

The code and unit testes are mostly copied from [geom|stat]_sina. I removed the random_state parameter as it isn't needed anymore (except when jitter is called). I wasn't sure what the best way to do here is, so any feedback would be appreciated.

I could also refactor the PR, so that stat_sina and stat_beeswarm use a common code base.

const-ae · 2026-07-11T15:38:38Z

Just checking if this feature is of interest?

has2k1 · 2026-07-16T16:00:51Z

Just checking if this feature is of interest?

Yes. I will get to it before the next minor release v0.16.0.

has2k1

I could also refactor the PR, so that stat_sina and stat_beeswarm use a common code base.

They do have a lot of code in common and it would be make sense if the refactor can extract some meaningful structure beyond the stat methods. Otherwise we can leave it as it is.

const-ae · 2026-08-22T10:45:46Z

Hey, I don't think I will get around to making the changes this week. If you would like to include the feature in the upcoming release, feel free to make any edits necessary. Otherwise, I hope to have some more free time for this in September :)

The method uses the van der Corput algorithm to produce a low discrepancy sequence between 0 and 1.

Add `random_state` to `stat_beeswarm` and use it when integer `y` values need jittering. This replaces the fixed seed and matches `stat_sina`'s random-state interface. Reduce the test's univariate chi-square degrees of freedom from 17 to 3 so all three distributions occupy comparable portions of the panel.

Move density estimation, width scaling, point offsets, and style mirroring into a shared swarm module. Keep each stat's distinct offset strategy and sparse-group density while removing the duplicated layout pipeline. Resolve `random_state` once during parameter setup. A seeded `stat_sina` layer therefore advances one random stream across its offset and jitter draws.

Pass the resolved stat parameters into the uniform-offset calculation and read `random_state` there. Both the offset calculation and integer `y` jitter now consume the same resolved random stream.

Multiply the pandas width fractions before the NumPy random values so the uniform-offset calculation retains the input index and returns a Series.

Rename the uniform and van der Corput offset calculations to `pseudorandom` and `quasirandom`. These names match the public spread strategies and prepare the calculations for shared dispatch.

Add `smiley` and `frowney` offset calculations. Both divide each group into `y` neighbourhoods and alternate ranked values across the swarm; `smiley` places extreme values near the edges, while `frowney` places them near the centre.

Map each spread name to its offset calculation and reject unknown values. This gives the beeswarm stat one entry point for selecting quasirandom, pseudorandom, smiley, or frowney placement.

Add the `spread` parameter to `stat_beeswarm` and `geom_beeswarm`. Users can select quasirandom, pseudorandom, smiley, or frowney point placement; quasirandom remains the default. Add visual coverage for the smiley and frowney strategies.

Mark the wrapped `spread` signature as a continued line so numpydoc parses its choices and default as one parameter declaration.

Add `geom_beeswarm` and `stat_beeswarm` to the API reference and describe their swarm placement in the changelog and class docs. Document the shared offset calculations, clarify how `random_state` affects pseudorandom placement, and list valid spread values in errors. Add pseudorandom visual coverage and align test names with their assertions.

codecov · 2026-09-14T15:17:49Z

Codecov Report

❌ Patch coverage is 81.28079% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.09%. Comparing base (019a08b) to head (13175eb).

Files with missing lines	Patch %	Lines
plotnine/stats/_swarm.py	77.48%	20 Missing and 14 partials ⚠️
plotnine/stats/stat_beeswarm.py	88.88%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1068      +/-   ##
==========================================
+ Coverage   88.05%   88.09%   +0.03%     
==========================================
  Files         223      226       +3     
  Lines       16440    16550     +110     
  Branches     2108     2116       +8     
==========================================
+ Hits        14477    14580     +103     
- Misses       1352     1357       +5     
- Partials      611      613       +2

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

has2k1 · 2026-09-14T16:01:27Z

@const-ae thanks for initiating this. I refactored it to use a common code base with geom_sina and also parameterised the spread of the points within the "swarm" to give the four variants quasirandom, pseudorandom, smiley and frowney. And geom_beeswarm with spread="pseudorandom" is really indistinguishable from geom_sina!

const-ae · 2026-09-14T16:58:58Z

Nice, looking forward to using this in the next release.

has2k1 requested changes Aug 18, 2026

View reviewed changes

Comment thread plotnine/stats/stat_beeswarm.py Outdated

Comment thread tests/test_geom_beeswarm.py Outdated

const-ae and others added 12 commits September 14, 2026 17:44

Implement geom_beeswarm using the quasirandom approach from ggbeeswarm

f60e891

The method uses the van der Corput algorithm to produce a low discrepancy sequence between 0 and 1.

refactor(stats): pass resolved parameters to sina offsets

b3e4bb8

Pass the resolved stat parameters into the uniform-offset calculation and read `random_state` there. Both the offset calculation and integer `y` jitter now consume the same resolved random stream.

fix(stats): preserve the sina offset series type

4d5ad19

Multiply the pandas width fractions before the NumPy random values so the uniform-offset calculation retains the input index and returns a Series.

refactor(stats): name swarm offsets by spread strategy

0719d0a

Rename the uniform and van der Corput offset calculations to `pseudorandom` and `quasirandom`. These names match the public spread strategies and prepare the calculations for shared dispatch.

feat(stats): add extreme-value swarm spreads

171bf08

Add `smiley` and `frowney` offset calculations. Both divide each group into `y` neighbourhoods and alternate ranked values across the swarm; `smiley` places extreme values near the edges, while `frowney` places them near the centre.

feat(stats): dispatch beeswarm spread strategies by name

309298e

Map each spread name to its offset calculation and reject unknown values. This gives the beeswarm stat one entry point for selecting quasirandom, pseudorandom, smiley, or frowney placement.

feat(stats): expose beeswarm spread strategies

6ca7da8

Add the `spread` parameter to `stat_beeswarm` and `geom_beeswarm`. Users can select quasirandom, pseudorandom, smiley, or frowney point placement; quasirandom remains the default. Add visual coverage for the smiley and frowney strategies.

fix(docs): join the beeswarm spread signature

724a652

Mark the wrapped `spread` signature as a continued line so numpydoc parses its choices and default as one parameter declaration.

test: promote geom_beeswarm baseline images

13175eb

has2k1 force-pushed the beeswarm branch from a9db017 to 13175eb Compare September 14, 2026 15:13

has2k1 merged commit cb5a46f into has2k1:main Sep 14, 2026
8 of 9 checks passed

Navigation Menu

Implement geom_beeswarm using a quasi-random algorithm - #1068

Implement geom_beeswarm using a quasi-random algorithm#1068
has2k1 merged 12 commits into
has2k1:mainfrom
const-ae:beeswarm

const-ae commented Jun 7, 2026 •

edited

Loading

Uh oh!

const-ae commented Jul 11, 2026

Uh oh!

has2k1 commented Jul 16, 2026 •

edited

Loading

Uh oh!

has2k1 left a comment

Uh oh!

Uh oh!

Uh oh!

const-ae commented Aug 22, 2026

Uh oh!

codecov Bot commented Sep 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

has2k1 commented Sep 14, 2026

Uh oh!

const-ae commented Sep 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

const-ae commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

const-ae commented Jul 11, 2026

Uh oh!

has2k1 commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

has2k1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

const-ae commented Aug 22, 2026

Uh oh!

codecov Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

has2k1 commented Sep 14, 2026

Uh oh!

const-ae commented Sep 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

const-ae commented Jun 7, 2026 •

edited

Loading

has2k1 commented Jul 16, 2026 •

edited

Loading

codecov Bot commented Sep 14, 2026 •

edited

Loading