cplots 0.0.5

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:

Arrays · DataFrames · xarray · GetDist      Solver results (CLASS, CAMB, eft4py)
               │                                      │ as_observables
               │                              Observables   one vocabulary, with units
               └──────────────→ PlotData ←────────────┘     immutable input containers
                                   ↓
                                PlotSpec                    backend-agnostic IR
                                   ↓
                 Backend   matplotlib · plotly · altair · ultraplot

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 plots into grids with colspan/rowspan, shared axes, and custom ratios
• LaTeX labels — pass raw LaTeX strings through to plotly's MathJax renderer
• 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, label="z=0").show()

# Interactive HTML with LaTeX labels
cplots.PKSpectrum(
    k, pk,
    x_label=r"$k\;[h\,\mathrm{Mpc}^{-1}]$",
    y_label=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 (Python ≥ 3.12; from source until a release ships BackgroundGrid.to_hiclass()).

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)