plot_io

Plots for PDF, PNG and JPEG in Python, drawn with pdf_io. No other dependency.

• Familiar: a figure of plots; scatter, line, fill, box, heatmap, bar, hist, kde (1-D and 2-D), ecdf, violin, strip, swarm, area, errorbar, stem, regression, hist2d, hexbin, contour, pie; reference lines, spans, text and annotations; color, marker, alpha, limits, scale, legend.
• Units: lengths in px, pt, in, mm, em, % of the axes or of another setting, data units and durations (width="1.5in", tick_length="0.5em", width="60%", cap_length="12h"); var() and calc() relate settings ("calc(var(--gap) * 2)").
• One way to set things: keywords at creation or set(...) on any object; figure settings (font, palette, line width…) are inherited by plots and series.
• Layouts: an explicit grid of ids with spans, or automatic rows and columns; plots sized individually; axis lines (or plot borders) aligned across the figure; margins from the real text metrics; shared axes; secondary axes; facets of a table.
• Data: columns of any table by name (data=: dicts, pandas, polars, numpy), one series per group (group=), numbers given as colors or sizes, point density (scipy's gaussian_kde, in C) for colors, sizes, opacity and drawing order.
• Axes: linear, log, log2, log10, sqrt, exp, symlog, logit, time and category scales; limits such as "0/max" or "q:0.01/q:0.99"; ticks with shared decimals and ×10ᵏ factors, calendar ticks for dates.
• Colors: a colorblind-safe palette, color maps interpolated in Oklab, colorbars; marker sizes by area, equal for every shape.
• Styles: style="matplotlib", "seaborn", "ggplot2", "altair", "matlab", "chartjs", "plotly", "bokeh", "observable", "excel", "fivethirtyeight", "economist", "tufte" and variants give the look of those libraries; styles are presets of settings, and your own build on them.
• Large data: one million points mapped and drawn in C; simplify="auto" drops what cannot be seen, rasterize= turns a series into an image inside the PDF.

Install

pip install /path/to/pdf_io      # pdf_io 0.6 or later
pip install .

Python 3.11+.

Quick start

import plot_io as pl

s = pl.Scatter(x, y, name="data")
s.plot.x_axis(label="Time (s)")
s.plot.save("scatter.pdf")

fig = pl.Figure(grid=[[1, 1, 2], [3, 4, 2]])
p = fig.plot(1, title="Signal")
p.line(t, v, name="raw")
p.fill(t, upper, lower, alpha=0.3)
p.y_axis(scale="log10", label="Power")
fig.plot(2).box({"a": va, "b": vb})
h = fig.plot(3).heatmap(matrix, x=columns, y=rows, cmap="magma", colorbar=True)
fig.plot(4).scatter(x, y, c=z, cmap="viridis")
fig.save("figure.pdf")
fig.save("figure.png", dpi=200)

fig = pl.Figure(style="ggplot2")                         # or a dict: {"base": "seaborn", "font_size": 9}

p = pl.Plot(width="3in", font_size="9pt", vars={"accent": "#c00"})
p.x_axis(tick_length="0.5em", minor_tick_length="50%")
p.bar(categories, counts, width="60%", color="var(--accent)")
p.x_axis.explain("tick_length")                          # where a value comes from

p = pl.Plot()
p.scatter("umap_x", "umap_y", data=genes, c="density", order="density")   # columns of a table
p.scatter("x", "y", data=df, group="cluster", marker="auto")              # one series per group
fig = pl.facet(df, col="condition", row="replicate")                       # small multiples
fig.scatter("x", "y")

Documentation

• API.md: the complete reference, with every setting.
• EXAMPLES.md: worked examples.

Development

python -m unittest discover -s tests -t tests
flake8 --select F plot_io tests && mypy
python tools/bench.py --check       # timings against the targets
python tools/settings_doc.py        # regenerate the settings tables of API.md