p9beeswarm

p9beeswarm provides beeswarm-style geoms for plotnine, modelled after the R ggbeeswarm package. The distribution also exposes the upstream algorithm compatibility modules as beeswarm and vipor, mirroring the corresponding R packages.

Installation

Install p9beeswarm from PyPI with:

python -m pip install p9beeswarm

Usage

import plotnine as p9
from plotnine.data import penguins
from p9beeswarm import geom_quasirandom

penguins_plot = (
    p9.ggplot(penguins.dropna(subset=["species", "body_mass_g"]),
              p9.aes("species", "body_mass_g", color="species"))
    + geom_quasirandom(width=0.35)
    + p9.labs(
        title="Penguin body mass by species",
        x="Species",
        y="Body mass (g)",
    )
    + p9.theme_bw()
)

Rendered output:

The side-by-side ggbeeswarm examples recreate the upstream README plots with both the Python and R implementations. Render them with:

quarto render docs/ggbeeswarm-examples.qmd

The README figure is generated by docs/update_readme_figure.py. If you change the example above, regenerate the image with:

uv run python docs/update_readme_figure.py

Upstream R tools

p9beeswarm is heavily inspired by the following upstream R packages. The Python implementations and compatibility tests follow their algorithms and plotting behavior:

License

p9beeswarm is licensed under the GNU GPLv3 or later.

Testing

The package is managed with [uv]. The core test suite covers the beeswarm and vipor compatibility modules, along with the plotnine position/geom integration:

uv run --extra test pytest

Upstream comparison tests

Beyond the core suite, the tests include parity checks against the original R packages. These tests use rpy2 to call the upstream R implementations and assert that the Python results match numerically:

uv run --extra test --extra r-test pytest

The R dependencies are pinned in renv.lock and restored by the GitHub Actions workflow with r-lib/actions/setup-renv. To update the pinned versions, run these commands from the repository root:

Rscript -e 'if (!requireNamespace("renv", quietly = TRUE)) install.packages("renv", repos = "https://cloud.r-project.org")'
Rscript -e 'renv::restore(prompt = FALSE)'
Rscript -e 'renv::update(c("beeswarm", "vipor", "ggbeeswarm", "ggplot2"), prompt = FALSE)'
Rscript -e 'renv::snapshot(prompt = FALSE)'

Review the resulting renv.lock diff, run the upstream comparison tests, and commit the updated lockfile along with any dependency changes.

Type checking

Type-check using mypy.

uv run --extra test --extra r-test mypy src/ tests/