Skip to main content

plot3

ggplot2 for Python, plus what ggplot2 can't do: interactive 3D, animated data, and plots typed straight from an equation. Figures render with WebGL in the notebook and save as journal-ready PNG, SVG, or PDF.

Gapminder: life expectancy against GDP per capita, animated from 1952 to 2007 A lidar driving scene with detection boxes, orbiting
+ transition_time("year"): gapminder in one line geom_point3d() + geom_box3d(): a 220k-point lidar sweep with detection boxes
An animated ripple surface z = sin(r - t) A beta density reshaping as two sliders move
geom_function("z = sin(sqrt(x^2 + y^2) - t)") + transition_time(t=(0, 6.28)) geom_function("y = dbeta(x, a, b)") + slider(a=…, b=…)
pip install plot3

Contents: Plot an equation · Animate your data · 3D and point clouds · One figure, two outputs · It's ggplot2 · Notebooks, SolveIt, CRAFT · Install · Full reference

Plot an equation

Write the maths as you would on paper. geom_function works out whether it's a curve, an implicit shape, a region, or a 3D surface, and picks a sensible window.

from plot3 import *

(ggplot() + geom_function("y = sin(x)", xlim=(-4, 4))                        # a function and
 + geom_function("y = x - x^3/6", xlim=(-4, 4)))                            # its Taylor polynomial
ggplot() + geom_function("(x^2 + y^2 - 1)^3 = x^2 y^3")                     # implicit: a heart
ggplot() + geom_function("y > x^2", xlim=(-2, 2))                           # shaded region
ggplot() + geom_function("r = 1 + cos(theta)") + coord_polar()              # polar cardioid
ggplot() + geom_function(r"z = \frac{\sin\sqrt{x^2+y^2}}{\sqrt{x^2+y^2}}",  # LaTeX in, 3D sombrero out
                         xlim=(-10, 10), ylim=(-10, 10))
ggplot() + geom_vector_field("dx = y, dy = -sin(x) - 0.3y",                # a damped pendulum's
                          xlim=(-6, 6), ylim=(-3, 3), stream=True)          # phase portrait

sin(x) and its Taylor polynomial Implicit heart curve Shaded region y > x^2 Polar cardioid 3D sombrero surface Streamlines of a damped pendulum

Probability and calculus, with the answer printed. No SciPy needed:

inf = float("inf")
ggplot() + geom_function("y = dbeta(x, 2, 5)") + area(0.2, 0.5)          # labels P(0.2 ≤ X ≤ 0.5) = 0.546
ggplot() + geom_function("y = dnorm(x)") + area(-inf, -1.96) + area(1.96, inf)
ggplot() + geom_function("y = x^3 - 3x") + tangent(at=1) + derivative()

Turn any coefficient into a slider or an animation:

ggplot() + geom_function("y = dbeta(x, a, b)") + slider(a=(0.5, 5), b=(0.5, 5))
ggplot() + geom_function("y = sin(x - t)") + transition_time(t=(0, 6.28))   # travelling wave

Equations mix freely with data: ggplot(df, aes(x="dose", y="response")) + geom_point() + geom_function("y = 2 + 0.6x"). ^ is power and 2x means 2*x. All functions, densities, and rules are in the reference.

Animate your data

gganimate's grammar: add a transition and the plot plays. The viewer interpolates between frames in the browser, with play, pause, scrubbing, speed control, and one-click video export.

import pandas as pd
gapminder = pd.read_csv("https://raw.githubusercontent.com/kirenz/datasets/master/gapminder.csv")

(ggplot(gapminder, aes(x="gdpPercap", y="lifeExp", size="pop", colour="continent", group="country"))
 + geom_point(alpha=0.7)
 + scale_x_log10()
 + transition_time("year")
 + labs(title="{frame_time}", x="GDP per capita", y="Life expectancy"))

{frame_time} in the title shows the current year as it plays. transition_states("phase") steps through categories instead of time.

Click a bubble to trace it: its path through every frame appears, with the years along it and its name (from group=) riding beside it as it plays. Click it again, or empty space, to clear it. This works in 3D too.

Run this without downloading anything (made-up gapminder-shaped data)
import pandas as pd

countries = {"Brazil": "Americas", "China": "Asia", "Egypt": "Africa",
             "France": "Europe", "India": "Asia", "Mexico": "Americas"}
gapminder = pd.DataFrame([
    {"country": country, "continent": continent, "year": year,
     "gdpPercap": 800 * (1.03 + 0.01 * i) ** (year - 1952),
     "lifeExp": 45 + 0.35 * (year - 1952) + 2 * i,
     "pop": 2e7 * (1.02 + 0.002 * i) ** (year - 1952)}
    for i, (country, continent) in enumerate(countries.items())
    for year in range(1952, 2008, 5)
])

(ggplot(gapminder, aes(x="gdpPercap", y="lifeExp", size="pop", colour="continent", group="country"))
 + geom_point() + scale_x_log10() + transition_time("year") + labs(title="{frame_time}"))

3D and point clouds

Map z and the plot becomes a 3D scene you can orbit, zoom, and hover. Hundreds of thousands of points stay smooth because they're drawn on the GPU.

import numpy as np

rng = np.random.default_rng(0)
arm = rng.integers(0, 2, 20_000)
r = rng.gamma(2, 1.2, 20_000)
theta = r * 0.9 + arm * np.pi + rng.normal(0, 0.25, 20_000)
galaxy = pd.DataFrame({"x": r * np.cos(theta), "y": r * np.sin(theta),
                       "z": rng.normal(0, 0.15, 20_000), "r": r})

(ggplot(galaxy, aes(x="x", y="y", z="z", colour="r"))
 + geom_point3d(size=0.01) + scale_colour_viridis_c(option="magma")
 + coord_3d(elev=40) + theme_lidar() + guides(colour="none"))

A 20,000-point spiral galaxy, orbiting The peaks surface coloured by height Nested density isosurfaces of three clusters

Surfaces, isosurfaces, and self-driving scenes use the same grammar:

ggplot(grid, aes(x="x", y="y", z="height", fill="height")) + geom_surface()
ggplot(points, aes(x="x", y="y", z="z")) + geom_isosurface(levels=[0.2, 0.5, 0.8])

(ggplot(sweep, aes(x="x", y="y", z="z"))                 # a nuScenes / KITTI lidar sweep
 + geom_point3d()                                         # coloured by height, as lidar viewers do
 + geom_box3d(aes(length="l", width="w", height="h", angle="yaw", colour="class"), data=boxes)
 + coord_3d(azim=180, elev=28, zoom=1.6)                 # chase camera behind the car
 + theme_lidar())

read_bin("scan.pcd.bin") loads nuScenes-style point clouds, and NumPy arrays work by column position: aes(x=0, y=1, z=2, colour=3). Camera, aspect, and point-budget options are in the reference under coord_3d.

One figure, two outputs

The same object is an interactive figure in the notebook and a publication figure on disk, with real fonts, correct DPI metadata, and theme_bw by default.

ggsave("fig1.pdf", p, width=3.5, height=2.6, units="in")         # vector, one journal column
ggsave("fig1.png", p, width=7, height=4.5, units="in", dpi=300)   # two columns
ggsave("fig1.html", p)                                            # interactive page to share

It's ggplot2

If you know ggplot2, you already know plot3: + layers, aes(), geoms, stats, scales, facets, themes, labs(), and patchwork's | and /, with ggplot2's names and defaults.

rng = np.random.default_rng(1)
arms = ["placebo", "low", "high"]
trial = pd.DataFrame({"arm": pd.Categorical(rng.choice(arms, 150), categories=arms),
                      "dose": rng.uniform(0, 10, 150)})
slope = trial.arm.map({"placebo": 0.05, "low": 0.35, "high": 0.7}).astype(float)
trial["response"] = 2 + slope * trial.dose + rng.normal(0, 0.9, 150)

a = (ggplot(trial, aes(x="dose", y="response", colour="arm"))
     + geom_point(alpha=0.7) + geom_smooth(method="lm", se=False)
     + scale_colour_hue() + theme_grey() + theme(legend_position="bottom"))
b = (ggplot(trial, aes(x="arm", y="response", fill="arm"))
     + geom_violin() + geom_jitter(width=0.1, height=0)
     + scale_fill_hue() + theme_grey() + theme(legend_position="none"))
fig = ((a | b) + plot_layout(widths=[3, 2])
       + plot_annotation(title="Response by dose and arm", tag_levels="A"))

scale_colour_hue() and theme_grey() are ggplot2's own defaults, so the figure looks as it would from R. plot3's defaults are theme_bw() for saved files and theme_dark() in the viewer.

Two-panel figure in ggplot2's grey theme: response against dose with one fitted line per arm, and violins of response by arm

Everything else you'd expect is there, including histograms, densities, boxplots, bar positions, stat_summary, error bars, heatmaps, hexbins, 2D densities, facet_wrap / facet_grid, Brewer, viridis, and Okabe–Ito scales, date axes, theme() with element_*(), and coord_flip / coord_polar. See the full reference for what plot3 supports and how it differs from ggplot2, or use the ggplot2 docs directly; the names match.

In notebooks, bare column names work as in R: aes(x=dose, y=response).

Notebooks, SolveIt, and CRAFT

  • Jupyter / SolveIt: bare column names and backticks work in aes(), facet_wrap(), and facet_grid() (aes(x=First Name)). Toggle with enable_r_style() / disable_r_style(). .py files keep quoted strings.

  • Layers on their own lines, as in R, with no parentheses:

    ggplot(gapminder, aes(x=gdpPercap, y=lifeExp, colour=continent))
    + geom_point(alpha=0.7)       # comments are fine
    + scale_x_log10()
    

    A line starting with + and a plot3 function continues the plot above it. Import plot3 in an earlier cell: IPython reads a whole cell before running any of it. .py files keep the outer parentheses.

  • SolveIt draws figures inline and hides their HTML from the model's context (autohide(False) to opt out).

  • VS Code notebooks block WebGL in output cells, so plot3 opens figures in your browser (PLOT3_DISPLAY=browser|iframe to force a mode). The page is written to .plot3_preview/latest.html in the notebook's folder, or to the system temp folder when that folder is read-only.

  • CRAFT / %gpu: the same ggplot(...) code runs on the remote kernel; stats run where the data lives and only a compact payload comes back.

%run /path/to/plot3/plot3.py        # loads plot3 locally and seeds the GPU kernel
%plot3 df x=wt y=mpg color=cyl       # optional shortcut magic

Install

pip install plot3

Python 3.10 or newer; NumPy and pandas are the only required packages. Notebooks, pandas, and Polars tables work with no extras.

For PDF, and PNG with real fonts, add cairosvg and the Cairo library. SVG needs neither.

pip install cairosvg
brew install cairo

(apt install libcairo2 on Debian and Ubuntu.) pip install "plot3[pdf]" installs plot3 and cairosvg together.

The latest unreleased code installs from GitHub with pip install "plot3 @ git+https://github.com/rleyvasal/plot3".

Development

git clone https://github.com/rleyvasal/plot3 && cd plot3
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q                       # includes every example in this README and docs/reference.md
python examples/showcase_2d.py  # 2D gallery in the browser
python examples/showcase_3d.py  # 3D gallery

The code is in plot3/: geoms.py (grammar objects), scaling.py (scale functions), build.py (stats to a figure spec), stat2d.py and flip.py (statistical layers), static.py (PNG/SVG/PDF), viewer.py (the WebGL viewer), expr.py / function.py / calculus.py (formulas), compose.py (multi-panel figures). See CHANGELOG.md for changes between versions.

License

MIT. See LICENSE.

Metadata

Release files for plot3 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for plot3 0.11.0
File Size Uploaded Provenance Actions
plot3-0.11.0.tar.gz 408.6 kB With provenance Details for plot3-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for plot3 0.11.0
File Interpreter ABI Platform Actions
plot3-0.11.0-py3-none-any.whl Python 3 none any Details for plot3-0.11.0-py3-none-any.whl

Total release size: 735.0 kB

Release files / plot3-0.11.0.tar.gz

Download URL plot3-0.11.0.tar.gz
Size 408.6 kB
Tags Source
SHA-256 checksum
How to use checksums
86afa62528d3081a1c2ae2ff1a3ba9bd78c5d557bb2999ba5a7f72ab97296627
BLAKE2b-256 checksum
How to use checksums
e4f382afce5e06b4181bface4c0d0cef5f1aad9f255bda1e07ae3e9af2b344ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / plot3-0.11.0-py3-none-any.whl

Download URL plot3-0.11.0-py3-none-any.whl
Size 326.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9519aa4fed50373f1138d65236228e4be490fff214eb3f1e039c4b37395c5d62
BLAKE2b-256 checksum
How to use checksums
725c275970106b76e641ed79f19979aa5d90a26a4853aba385a69989288b7685
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for plot3 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for plot3-0.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page