Skip to content

Home

cplots wordmark

A backend-agnostic plotting library.

Write your analysis once; render using matplotlib, plotly, altair or ultraplot with a single flag. No lock-in to any rendering engine.

Get started Browse the API

How it works

Every plot flows through the same layers, whether it starts from arrays or from a Boltzmann/dark-energy solver:

flowchart TD
    raw["Arrays · DataFrames · xarray · GetDist"]
    solver["Solver results<br/>CLASS · CAMB · eft4py"]
    obs["<b>Observables</b><br/>one vocabulary, with units"]
    data["<b>PlotData</b><br/>immutable input containers"]
    spec["<b>PlotSpec</b><br/>backend-agnostic IR"]
    backend["<b>Backend</b><br/>matplotlib · plotly · altair · ultraplot"]

    solver -- as_observables --> obs
    raw -- to_plot_data --> data
    obs --> data
    data -- "Plot.spec()" --> spec
    spec -- "render · show · save" --> backend

Plot subclasses never import backends. Backends never import plot subclasses. Swap the backend at call time, via a context manager, or globally — the plot code stays unchanged.

Features

  • Plot types

    General: XYPlot · XYZColored · XYZColoredGrid · PhasePortrait. Cosmology: PKSpectrum · ClSpectrum · PrimordialSpectrum · BackgroundEvolution · BackgroundPanels · ThermodynamicsEvolution. Inference: TrianglePlot · PosteriorBands. Residuals: ResidualFigure.

    Plot types

  • Four backends

    Publication figures via matplotlib or ultraplot, interactive HTML via plotly, Vega-Lite JSON via altair.

    Backends

  • Multi-panel figures

    Compose plots with (a | b) / c, or an explicit grid with colspan/rowspan, shared axes and custom column/row ratios.

    Multi-panel figures

  • LaTeX labels

    Labels, including the defaults like $P(k)$, render as math in matplotlib; plotly shows Unicode, or MathJax with latex_labels=True.

    LaTeX labels

  • Styles

    Chainable, immutable formatting and a Style cascade. Every plot starts from cplots.DEFAULT: Computer Modern, FiveThirtyEight colours, inward ticks.

    Formatting and styles

  • Solver adapters

    CLASS / hi_class, CAMB and eft4py outputs through one vocabulary, with units tracked and converted, and code comparisons in one call.

    Solver adapters

  • Command line

    Triangle plots from chains and line plots from data files, without Python: cplots distributions triangle, cplots lines xy.

    Command line

Quick example

import numpy as np
import cplots

k  = np.logspace(-3, 0, 200)
pk = k ** -1.5

cplots.PKSpectrum(k, pk, labels="z=0").show()

# Interactive HTML — LaTeX rendered by MathJax
cplots.PKSpectrum(
    k, pk,
    xlabel=r"$k\;[h\,\mathrm{Mpc}^{-1}]$",
    ylabel=r"$P(k)\;[h^{-3}\,\mathrm{Mpc}^3]$",
    latex_labels=True,
).save("pk.html", backend="plotly")

fig = cplots.Figure.grid([
    [cplots.PKSpectrum(k, pk), cplots.BackgroundEvolution(z, {"H": Hz})],
    [cplots.XYPlot(x, y, labels=["theory", "data"])],
])
fig.show()

Install

pip install cplots[matplotlib]              # matplotlib only
pip install cplots[matplotlib,plotly]       # two backends
pip install cplots[all]                     # matplotlib, plotly, altair, chain engines, pandas/polars, scipy

Development install

git clone https://github.com/rcalderonb6/cplots
pip install -e ".[matplotlib,dev]"