SecretPlots

Publication-ready scientific figures in a few readable lines of Python.
Journal presets · statistics built in · colour-blind-safe palettes · fonts embedded

Documentation · Gallery · Journal-ready figures · Changelog · Report a bug

Same calls, better figure

If you can write matplotlib, you can write SecretPlots. Same data, same figure size, no styling code on either side:

matplotlib	SecretPlots
import matplotlib.pyplot as plt fig, ax = plt.subplots(figsize=(6, 3.7), layout="constrained") for arm, g in tumours.groupby("arm", sort=False): ax.plot(g["day"], g["volume"], marker="o", label=arm) ax.set(xlabel="Day", ylabel="Tumour volume (mm³)", title="Tumour growth") ax.legend()	import SecretPlots as sp ( sp.plot(tumours, x="day", y="volume", hue="arm") .markers() .labels(x="Day", y="Tumour volume (mm³)", title="Tumour growth") )

You get a colour-blind-safe palette, a quiet grid, a titled legend outside the data and readable type without touching rcParams. From there, one more step labels the lines directly (.endlabels()), one argument summarises replicate animals with confidence bands (error="ci"), and one line makes it a journal figure.

From table to journal figure

import SecretPlots as sp

sp.use(preset="nature")                         # 89 mm column, 5–7 pt text, 300 dpi

(
    sp.box(cells, x="treatment", y="area")
    .points()                                   # show every cell
    .compare(ref="Control", correction="holm")  # significance brackets
    .colors({"Control": "#BBBBBB", "siRNA": "#EE6677", "siRNA + rescue": "#4477AA"})
    .labels(x="", y="Cell area (µm²)")
    .save("figure1.pdf")                        # fonts embedded, ready to upload
)

Why SecretPlots?

• Journal presets. Nature, Science, Cell, PNAS, AHA, Elsevier, Springer, IEEE, ACM and NeurIPS presets set column widths, font limits, dpi and file formats from each publisher's author guidelines.
• Statistics where you need them. Significance brackets with Holm or Bonferroni correction, confidence bands, percentile intervals of the observations, linear fits with R², KDEs and hierarchical clustering. Most plots return their computed numbers as tables (.source_data(), .test_results()).
• Every observation visible. Points over boxes, individual trajectories under means, rainclouds and rugs, the patterns reviewers ask for with small samples.
• Colour-blind safe. Palettes and colormaps come from SecretColors. Unsafe maps are flagged, and a print-bw theme renders the figure in greys.
• Readable, chainable API. One constructor plus small steps. plot.arguments() lists what the constructor takes, plot.options() every step, and plot.options("legend") explains one.
• Honest defaults. Missing data raises instead of being silently dropped. Font and palette fallbacks are reported, and plot.explain("font_size") says where any style value came from.

Installation

pip install SecretPlots          # or: uv add SecretPlots

Requires Python 3.12+. Depends only on matplotlib, numpy, pandas and SecretColors.

Version 3 is a ground-up rewrite and is not compatible with the 0.1.x releases; pin SecretPlots<1 if you depend on the old API.

Gallery

Every image below is unretouched SecretPlots output at Nature single-column size. The gallery has the complete, runnable code for each.

Compare groups and conditions

sp.bar(qpcr, x="gene", y="fold", hue="genotype", error="sd").refline(1, linestyle=":").ticklabels(italic=True)
sp.raincloud(stroop, x="condition", y="rt").compare(ref="Congruent", format="stars")

Follow change over time

sp.line(tumours, x="day", y="volume", hue="arm", units="mouse", error="ci").endlabels().log("y")
sp.line(pk, x="hours", y="conc", hue="dose", error="sd").errorbars("bars").markers().log("y")

Find the pattern in a matrix

sp.heatmap(expression).scale("row").groups(rows="pathway").cluster(cols=False).tracks(cols={"Condition": condition})
sp.heatmap(cohort.corr(), square=True).mask("upper").cmap("tol_bu_rd", center=0).values(".2f")

Relationships and distributions

sp.scatter(genes, x="lfc", y="log_p", hue="call").refline(-1, 1, axis="x").refline(2, axis="y")
sp.scatter(biopsies, x="bmi", y="lipid", hue="tissue").fit("linear", stats=True)
sp.histogram(serum, x="level", hue="cohort", stat="density").kde().show_n()
sp.violin(behaviour, x="genotype", y="score", hue="sex", split=True, inner="quartiles")

Clinical results

sp.forest(trial, label="subgroup", estimate="hr", lower="lower", upper="upper", group="variable").summary("All patients").table(left={"Drug": "drug"})
sp.survival(patients, time="months", event="died", hue="arm").risk_table().median().pvalue().hazard_ratio()

One figure, any journal

Presets describe where a figure is going; themes describe how it looks. Switch either one without touching your plotting code:

sp.use(preset="nature")                    # for the whole session
plot.preset("ieee")                        # or for one plot
plot.size(width="double", height="60mm")   # the journal's named widths, or any length
plot.theme("print-bw").encode_groups()     # greyscale with dashes and markers

Journal presets cite the guidelines they were built from. If you set a value outside a journal's limits, you get a LimitExceededWarning instead of a silent change. Newsroom presets ending in -like are inspired by publicly visible chart conventions; they are not affiliated with those publishers and use open fallback fonts. You can write your own preset in a few lines of TOML.

Plot types

Find any option without leaving Python

No need to open the docs or call help(). Every plot type describes itself as a table you can read or search:

sp.BarPlot.arguments()          # what sp.bar(...) accepts: allowed values, defaults
sp.BarPlot.arguments("error")   # one argument
plot.options()                  # every chainable step for this plot
plot.options("legend")          # one step's parameters, allowed values and defaults
sp.theme_options()              # every style field accepted by .theme(...)
plot.explain("font_size")       # where a style value came from

Development

uv sync --group dev --group docs
uv run pre-commit install
uv run pytest --mpl                       # tests, including image comparisons
uv run python scripts/render_docs.py      # regenerate documentation figures
uv run mkdocs serve                       # preview the documentation

See CONTRIBUTING.md for adding presets and documentation. Bug reports, preset requests and pull requests are very welcome.

License

MIT © Rohit Suratekar and contributors. Colour palettes and colormaps by SecretColors.