Plots API¶

XYPlot¶

XYPlot ¶

XYPlot(x: NDArray[Any] | list[NDArray[Any]], y: NDArray[Any] | list[NDArray[Any]], *, labels: str | list[str] = '', x_label: str = '', y_label: str = '', title: str = '', x_scale: Literal['linear', 'log'] = 'linear', y_scale: Literal['linear', 'log'] = 'linear', theme: ThemeSpec | None = None, figsize: tuple[float, float] | None = None, latex_labels: bool = False)

Bases: Plot[Any]

Generic x/y line plot for arbitrary data.

Accepts a single trace or multiple traces when y is a list. A single x array is broadcast across all traces.

Example:

>>> # Single trace
>>> XYPlot(x, y, y_label="f(x)")

>>> # Multiple traces, shared x
>>> XYPlot(x, [y1, y2], labels=["sin", "cos"])

>>> # Multiple traces, individual x arrays
>>> XYPlot([x1, x2], [y1, y2], labels=["A", "B"])

Create an XYPlot.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[Any] \| list[NDArray[Any]]`	X-axis data. A single array is broadcast to all traces; a list provides per-trace arrays.	required
`y`	`NDArray[Any] \| list[NDArray[Any]]`	Y-axis data. A single array produces one trace; a list produces one trace per element.	required
`labels`	`str \| list[str]`	Legend label(s). A single string is reused for all traces; a list must match the number of traces.	`''`
`x_label`	`str`	X-axis label. Supports LaTeX when `latex_labels=True`.	`''`
`y_label`	`str`	Y-axis label.	`''`
`title`	`str`	Plot title.	`''`
`x_scale`	`Literal['linear', 'log']`	X-axis scale — `"linear"` or `"log"`.	`'linear'`
`y_scale`	`Literal['linear', 'log']`	Y-axis scale — `"linear"` or `"log"`.	`'linear'`
`theme`	`ThemeSpec \| None`	Visual theme. `None` uses the backend default.	`None`
`figsize`	`tuple[float, float] \| None`	Figure size `(width, height)` in inches.	`None`
`latex_labels`	`bool`	Pass label strings raw to the backend (for MathJax).	`False`

Methods:¶

PKSpectrum¶

PKSpectrum ¶

PKSpectrum(k_or_data: NDArray[Any] | list[NDArray[Any]] | PKData | list[PKData], pk: NDArray[Any] | list[NDArray[Any]] | None = None, *, redshift: float = 0.0, **kwargs: Any)

Bases: PowerSpectrumBase

Matter power spectrum P(k). Log-log axes, x in h/Mpc, y in (Mpc/h)^3.

Accepts either raw arrays or a PKData object (e.g. from ClassOutput.pk()).

Examples:

# From raw arrays
PKSpectrum(k, pk, label="z=0").show()

# Multiple redshifts on the same axes
PKSpectrum(k, [pk0, pk1], label=["z=0", "z=1"]).show()

# From ClassOutput
PKSpectrum(out.pk(z=0.0), label="z=0").show()

# Secondary top axis showing corresponding multipole ℓ ≈ k · χ
# chi is the comoving distance in the same units as k (e.g. Mpc/h)
PKSpectrum(k, pk, secondary_x_axis=multipole_axis(chi=13890)).show()

ClSpectrum¶

ClSpectrum ¶

ClSpectrum(ell_or_data: NDArray[Any] | list[NDArray[Any]] | dict[str, ClData], cl: NDArray[Any] | list[NDArray[Any]] | None = None, **kwargs: Any)

Bases: PowerSpectrumBase

CMB angular power spectrum C_ell. Linear x, log y.

Accepts either raw arrays or a dict[str, ClData] returned by ClassOutput.cl().

Examples:

# From raw arrays
ClSpectrum(ell, cl_tt, label="TT").show()

# Multiple components from raw arrays
ClSpectrum(ell, [cl_tt, cl_ee], label=["TT", "EE"]).show()

# From ClassOutput (single or multiple spectra)
ClSpectrum(out.cl(spectra=["tt", "ee"])).show()

# Secondary top axis showing corresponding wavenumber k ≈ ℓ / χ
# chi is the comoving distance in the same units as k (e.g. Mpc/h)
ClSpectrum(ell, cl_tt, secondary_x_axis=wavenumber_axis(chi=13890)).show()

PowerSpectrumBase¶

PowerSpectrumBase ¶

PowerSpectrumBase(x: NDArray[Any] | list[NDArray[Any]], y: NDArray[Any] | list[NDArray[Any]], *, label: str | list[str] = '', x_label: str = '', y_label: str = '', title: str = '', theme: ThemeSpec | None = None, figsize: tuple[float, float] | None = None, latex_labels: bool = False, secondary_x_axis: SecondaryAxisSpec | None = None)

Bases: Plot[Any], ABC

Shared rendering logic for power spectrum plots.

Subclasses fix default axis scales and labels via class variables; callers may override labels via constructor keyword arguments.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[Any] \| list[NDArray[Any]]`	X-axis data. A single array is broadcast to all traces; a list provides per-trace arrays.	required
`y`	`NDArray[Any] \| list[NDArray[Any]]`	Y-axis data. A single array produces one trace; a list produces one trace per element.	required
`label`	`str \| list[str]`	Legend label(s). A string is broadcast; a list provides per-trace labels.	`''`
`x_label`	`str`	Override the default x-axis label.	`''`
`y_label`	`str`	Override the default y-axis label.	`''`
`title`	`str`	Panel title.	`''`
`theme`	`ThemeSpec \| None`	Visual theme. `None` uses the backend default.	`None`
`figsize`	`tuple[float, float] \| None`	Figure size `(width, height)` in inches.	`None`
`latex_labels`	`bool`	Pass labels through to the backend without stripping LaTeX markup.	`False`
`secondary_x_axis`	`SecondaryAxisSpec \| None`	Optional top x-axis specification. Build one with :func:`~cplots.multipole_axis` or :func:`~cplots.wavenumber_axis`. `None` (default) disables the secondary axis.	`None`

BackgroundEvolution¶

BackgroundEvolution ¶

BackgroundEvolution(redshift_or_data: NDArray[Any] | BackgroundData, quantities: dict[str, NDArray[Any]] | None = None, *, labels: dict[str, str] | None = None, title: str = '', theme: ThemeSpec | None = None, latex_labels: bool = False)

Bases: Plot[Any]

Background cosmological quantities plotted against redshift.

Designed for quantities such as H(z), D_A(z), w(z), f(z), Omega(z), etc. Each key in quantities becomes a separate trace; labels maps keys to display strings (defaults to the key name).

Example:

>>> BackgroundEvolution(
...     z,
...     {"H": Hz, "D_A": daz},
...     labels={"H": r"$H(z)$", "D_A": r"$D_A(z)$"},
...     latex_labels=True,
... ).show()

Create a BackgroundEvolution plot.

Parameters:

Name	Type	Description	Default
`redshift_or_data`	`NDArray[Any] \| BackgroundData`	Either a 1-D redshift array (x-axis) or a `BackgroundData` object returned by e.g. `ClassOutput.background()`. When a `BackgroundData` is given, `quantities` and `labels` are taken from it (keyword overrides are ignored).	required
`quantities`	`dict[str, NDArray[Any]] \| None`	Mapping of quantity name to value array when `redshift_or_data` is a plain array. Each entry becomes one trace.	`None`
`labels`	`dict[str, str] \| None`	Optional display labels keyed by quantity name. Falls back to the quantity name when a key is absent.	`None`
`title`	`str`	Plot title.	`''`
`theme`	`ThemeSpec \| None`	Visual theme.	`None`
`latex_labels`	`bool`	Pass label strings raw to the backend (for MathJax).	`False`

Methods:¶

TrianglePlot¶

TrianglePlot ¶

TrianglePlot(samples: NDArray[Any], parameter_names: list[str], *, weights: NDArray[Any] | None = None, truths: dict[str, float] | None = None, title: str = '', theme: ThemeSpec | None = None, latex_labels: bool = False, engine: str = 'getdist')

Bases: Plot[Any]

MCMC posterior triangle (corner) plot from sample chains.

Rendering is delegated to a pluggable engine= that wraps a third-party triangle plot library. Three engines are built in:

"getdist" (default) — wraps the getdist library; install with pip install cplots[getdist].
"chainconsumer" — wraps ChainConsumer via narwhals; install with pip install cplots[chainconsumer].
"anesthetic" — wraps anesthetic; install with pip install cplots[anesthetic].

Backends that implement TrianglePlot support must handle the special style keys on the single trace: parameter_names, samples, weights, truths, and engine.

Example::

# Default engine (getdist)
TrianglePlot(
    samples,  # shape (N, D)
    parameter_names=[r"$\Omega_m$", r"$\sigma_8$"],
    truths={"$\Omega_m$": 0.3},
    latex_labels=True,
).show()

# Explicit alternative engine
TrianglePlot(samples, parameter_names=[...], engine="anesthetic").show()

Create a TrianglePlot.

Parameters:

Name	Type	Description	Default
`samples`	`NDArray[Any]`	MCMC sample array of shape `(N, D)` where `N` is the number of samples and `D` is the number of parameters.	required
`parameter_names`	`list[str]`	Display names for each of the `D` parameters. Supports LaTeX when `latex_labels=True`.	required
`weights`	`NDArray[Any] \| None`	Optional importance weights of shape `(N,)`.	`None`
`truths`	`dict[str, float] \| None`	Optional mapping from parameter name to fiducial value. Fiducial lines are drawn on matching parameters.	`None`
`title`	`str`	Plot title.	`''`
`theme`	`ThemeSpec \| None`	Visual theme.	`None`
`latex_labels`	`bool`	Pass label strings raw to the backend (for MathJax).	`False`
`engine`	`str`	Triangle rendering engine name. Built-in values are `"getdist"` (default), `"chainconsumer"`, and `"anesthetic"`. Third-party engines can be registered via :func:`~cplots.plots.engines.register_engine`.	`'getdist'`

Methods:¶

XYZColored¶

XYZColored ¶

XYZColored(x: NDArray[Any] | list[NDArray[Any]], y: list[NDArray[Any]], z: list[float], *, labels: str | list[str] = '', x_label: str = '', y_label: str = '', z_label: str = '', title: str = '', x_scale: Literal['linear', 'log'] = 'linear', y_scale: Literal['linear', 'log'] = 'linear', colormap: str = 'viridis', colorbar: bool = True, colorbar_pad: float | None = None, colorbar_scale: float = 1.175, theme: ThemeSpec | None = None, figsize: tuple[float, float] | None = None, latex_labels: bool = False)

Bases: Plot[Any]

XY plot where each curve is color-coded by a scalar Z value.

Useful for sweeping a parameter (redshift, mass, etc.) and visualizing how curves change continuously across it.

Examples:

# Shared x, one z value per curve
XYZColored(x, [y0, y1, y2], z=[0.0, 0.5, 1.0], z_label="redshift")

# Per-curve x arrays
XYZColored([x0, x1], [y0, y1], z=[0.3, 1.5], colormap="plasma")

Create an XYZColored plot.

Parameters:

Name	Type	Description	Default
`x`	`NDArray[Any] \| list[NDArray[Any]]`	X-axis data. A single array is broadcast to all traces; a list provides per-trace arrays.	required
`y`	`list[NDArray[Any]]`	List of y-axis arrays, one per trace.	required
`z`	`list[float]`	Scalar color values, one per trace. Controls the colormap mapping (e.g. redshift values for a redshift sweep).	required
`labels`	`str \| list[str]`	Legend label(s). A single string is reused for all traces.	`''`
`x_label`	`str`	X-axis label.	`''`
`y_label`	`str`	Y-axis label.	`''`
`z_label`	`str`	Colorbar label.	`''`
`title`	`str`	Plot title.	`''`
`x_scale`	`Literal['linear', 'log']`	X-axis scale — `"linear"` or `"log"`.	`'linear'`
`y_scale`	`Literal['linear', 'log']`	Y-axis scale — `"linear"` or `"log"`.	`'linear'`
`colormap`	`str`	Named colormap (e.g. `"viridis"`, `"plasma"`).	`'viridis'`
`colorbar`	`bool`	Whether to draw a colorbar.	`True`
`theme`	`ThemeSpec \| None`	Visual theme.	`None`
`figsize`	`tuple[float, float] \| None`	Figure size `(width, height)` in inches.	`None`
`latex_labels`	`bool`	Pass label strings raw to the backend (for MathJax).	`False`

Raises:

Type	Description
`ValueError`	If `len(z) != len(y)`.

Methods:¶

XYZColoredGrid¶

XYZColoredGrid ¶

XYZColoredGrid(panels: list[XYZColored], *, nrows: int | None = None, ncols: int | None = None, shared_colorbar: bool = False, z_label: str = '', colormap: str | None = None, colorbar_pad: float | None = None, colorbar_scale: float = 1.175, figsize: tuple[float, float] | None = None, theme: ThemeSpec | None = None, latex_labels: bool = False, hspace: float | None = None, wspace: float | None = None)

Grid of XYZColored plots with optional shared colorbar.

Parameters¶

panels: List of XYZColored plot objects — one per grid cell. nrows, ncols: Grid dimensions. If omitted, auto-layout to a roughly square grid. shared_colorbar: When True, suppress per-panel colorbars and render one shared colorbar spanning the whole figure, normalised globally across all Z values. When False (default), each panel retains its own colorbar. z_label: Colorbar label used when shared_colorbar=True. Falls back to the first panel's z_label when omitted. colormap: Colormap name for the shared colorbar. Falls back to the first panel's colormap when omitted. Only used when shared_colorbar=True. colorbar_pad, colorbar_scale: Fine-tuning for the shared colorbar. Passed through to the backend. figsize: Overall figure size (width, height) in inches. theme: Visual theme applied to all panels. latex_labels: Propagate raw LaTeX strings to all panels.

Examples¶

panels = [
    XYZColored(k, [pk_z0, pk_z1, pk_z2], z, y_label="P(k)",  x_scale="log", y_scale="log"),
    XYZColored(k, [dk_z0, dk_z1, dk_z2], z, y_label="D(k)",  x_scale="log", y_scale="log"),
]

# Per-panel colorbars (default)
XYZColoredGrid(panels, figsize=(12, 4)).show()

# Single shared colorbar
XYZColoredGrid(panels, shared_colorbar=True, z_label="redshift").show()

Methods:¶

show ¶

show(backend: str | None = None, **kwargs: Any) -> None

Render the grid and display it.

save ¶

save(path: str | PathLike[str], backend: str | None = None, **kwargs: Any) -> None

Render the grid and save it to path.

render ¶

render(backend: str | None = None) -> Any

Render the grid and return the native figure object.

ResidualFigure¶

ResidualFigure ¶

ResidualFigure(plot: Plot[Any], reference: int | str | NDArray[Any] = 0, *, reference_x: NDArray[Any] | None = None, mode: Literal['absolute', 'relative', 'ratio'] = 'relative', height_ratio: tuple[float, float] = (3, 1), include_reference: bool = False, hspace: float | None = None)

Two-panel figure: main observable on top, residuals below on a shared x-axis.

Produced by :meth:~cplots.core.base.Plot.with_residuals. Use :meth:show, :meth:save, or :meth:render to display the result with any registered backend.

Parameters:

Name	Type	Description	Default
`plot`	`Plot[Any]`	The source plot object.	required
`reference`	`int \| str \| NDArray[Any]`	Reference for residual computation. An `int` selects a trace by index, a `str` selects by label, and a numpy array provides external y-values (same x-grid assumed unless reference_x is also given).	`0`
`reference_x`	`NDArray[Any] \| None`	X-grid of an external reference array. Only used when reference is a numpy array and its x-grid differs from the traces in plot.	`None`
`mode`	`Literal['absolute', 'relative', 'ratio']`	Residual type. `"relative"` → (y − y_ref) / y_ref, `"absolute"` → y − y_ref, `"ratio"` → y / y_ref.	`'relative'`
`height_ratio`	`tuple[float, float]`	Relative heights `(main, residuals)` of the two panels. Default `(3, 1)` makes the main panel three times taller.	`(3, 1)`
`include_reference`	`bool`	When True and the reference is an existing trace, include it in the residuals panel (appears as a flat line at 0 for relative/absolute or 1 for ratio).	`False`

Methods:¶

show ¶

show(backend: str | None = None, **kwargs: Any) -> None

Render the two-panel figure and display it interactively.

Parameters:

Name	Type	Description	Default
`backend`	`str \| None`	Backend name (`"matplotlib"`, `"plotly"`, `"altair"`). Defaults to the active context/global backend.	`None`
`**kwargs`	`Any`	Forwarded to the backend's `show()` method.	`{}`

save ¶

save(path: str | PathLike[str], backend: str | None = None, **kwargs: Any) -> None

Render the two-panel figure and save it to a file.

Parameters:

Name	Type	Description	Default
`path`	`str \| PathLike[str]`	Destination file path. The format is inferred from the extension (e.g. `.png`, `.pdf`, `.svg`).	required
`backend`	`str \| None`	Backend name. Defaults to the active context/global backend.	`None`
`**kwargs`	`Any`	Forwarded to the backend's `save()` method.	`{}`

render ¶

render(backend: str | None = None) -> Any

Render the two-panel figure and return the native figure object.

Parameters:

Name	Type	Description	Default
`backend`	`str \| None`	Backend name. Defaults to the active context/global backend.	`None`

Returns:

Type	Description
`Any`	The native figure object (e.g. `matplotlib.figure.Figure`,
`Any`	`plotly.graph_objects.Figure`, or `altair.Chart`).