cplots 0.0.6

A backend-agnostic cosmological plotting library.
Write your analysis once; render with matplotlib, plotly, or altair — no lock-in.

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 (getdist, chainconsumer or anesthetic engines), PosteriorBands
  • residual panels: ResidualFigure, plot.with_residuals(...)
• Four backends — publication figures via matplotlib or ultraplot, interactive HTML via plotly, Vega-Lite JSON via altair (multi-panel figures: matplotlib, plotly, altair)
• Solver adapters — CLASS / hi_class, CAMB and eft4py outputs through one interface: shared quantity names (H, dA, w_de, alpha_M, …), units tracked and converted, any redshift grid via z=
• Code comparisons — overlay several codes with {label: source}; units are matched automatically, and BackgroundPanels gives each kind of quantity its own panel
• Multi-panel figures: compose with (a | b) / c or an explicit grid with colspan/rowspan, shared axes and custom ratios (full support on matplotlib and plotly; altair has no rowspan or shared axes)
• Formatting and styles: chainable, immutable formatting (plot.axes(xlim=...).legend(...)) and a Style cascade (global, then with cplots.style(...), then figure, then plot) applied per render. Every plot starts from cplots.DEFAULT: Computer Modern text and math, FiveThirtyEight colours, boxed axes with inward ticks, magma colormaps
• LaTeX labels — labels (including the defaults, e.g. $P(k)$) render as math in matplotlib; plotly gets Unicode, or MathJax with latex_labels=True
• Command line — cplots distributions triangle CHAIN and cplots lines xy FILE (pip install "cplots[cli]")
• Data adapters — NumPy arrays, pandas / polars DataFrames, xarray Datasets, GetDist MCSamples
• Extensible, light imports — backends register via the cplots.backends entry point; data and solver adapters with @cplots.to_plot_data.register / @cplots.as_observables.register (a solver adapter subclasses Observables and implements one hook). Optional libraries are only imported when used.

Quick example

import numpy as np
import cplots

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

# Display with default backend (matplotlib)
cplots.PKSpectrum(k, pk, labels="z=0").show()

# Interactive HTML with LaTeX labels
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")

# Multi-panel figure
z  = np.linspace(0, 3)
Hz = 67.34 * np.sqrt(0.3 * (1 + z)**3 + 0.7)

fig = cplots.Figure.grid([
    [cplots.PKSpectrum(k, pk), cplots.BackgroundEvolution(z, {"H": Hz})],
])
fig.show()

Switching backends

# Per call
plot.show(backend="plotly")

# Context manager
with cplots.backend("altair"):
    plot.show()

# Global default
cplots.set_backend("plotly")

Cosmology solvers

Hand cplots a computed solver result; as_observables picks the adapter, and every code answers the same background() call in the same vocabulary:

out = cplots.as_observables(cosmo)          # classy.Class -> ClassOutput
bg = out.background(quantities=["H", "dA"], units={"H": "km/s/Mpc"}, z=np.linspace(0, 3, 100))

# Overlay codes: one line style per source, CAMB's km/s/Mpc and CLASS's 1/Mpc matched for you
cplots.BackgroundPanels(
    {"hi_class": cosmo, "eft4py": grid, "CAMB": camb_results},
    ["H", "dA"],
    units={"H": "km/s/Mpc"},
).show()

# Dark-energy quantities, from hi_class and an eft4py BackgroundGrid
cplots.BackgroundEvolution({"hi_class": cosmo, "eft4py": grid}, ["w_de"]).show()

P(k), Cℓ, primordial and thermodynamics outputs are available where a code provides them (out.pk(), out.cl(), …). See the Solver Adapters guide and the eft4py notebook.

Installation

pip install cplots[matplotlib]              # matplotlib only
pip install cplots[matplotlib,plotly]       # two backends
pip install cplots[all]                     # matplotlib, plotly, altair, pandas, polars, triangle engines, scipy
pip install cplots[ultraplot]               # ultraplot backend (not included in [all])
pip install cplots[camb]                    # CAMB adapter
pip install cplots[classy]                  # CLASS adapter (builds classy)
pip install cplots[cosmo]                   # both solvers (not included in [all])
pip install cplots[dynamics]                # scipy integrators for PhasePortrait

eft4py is not an extra: install it separately (pip install "eft4py>=0.0.6", Python ≥ 3.11).

Development install:

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

Documentation

Full documentation, including the API reference, user guide, and interactive examples, is available at rcalderonb6.github.io/cplots:

• Getting started
• Examples gallery
• Solver adapters (CLASS, CAMB, eft4py, writing your own)