Backends

cplots ships three backends. Each translates a PlotSpec into a native figure object without knowing anything about the plot type that produced it.

Selecting a backend

Backend selection follows a three-level priority:

Priority	Method	Example
1 (highest)	Per-call kwarg	plot.render(backend="plotly")
2	Context manager	with cplots.backend("altair"): ...
3 (lowest)	Global default	cplots.set_backend("matplotlib")

The default global backend is "matplotlib".

matplotlib

Produces matplotlib.figure.Figure objects.

pip install cplots[matplotlib]

fig = plot.render(backend="matplotlib")  # returns matplotlib.figure.Figure
fig.savefig("figure.pdf", dpi=300, bbox_inches="tight")

Best for: publication-quality static figures (PDF, EPS, PNG).

plotly

Produces plotly.graph_objects.Figure objects.

pip install cplots[plotly]

fig = plot.render(backend="plotly")
fig.write_html("figure.html")   # interactive HTML with MathJax
fig.write_image("figure.png")   # static raster (requires kaleido)

Best for: interactive HTML figures and dashboards.

LaTeX in plotly

Set latex_labels=True to pass raw LaTeX strings to plotly. MathJax will render them in the browser.

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,
).render(backend="plotly")

altair

Produces altair.Chart objects (Vega-Lite).

pip install cplots[altair]

chart = plot.render(backend="altair")
chart.save("figure.html")  # self-contained Vega-Lite HTML

Best for: interactive web visualizations and Jupyter notebooks.

Limitation

The Altair backend does not support rowspan > 1 in multi-panel layouts. Use matplotlib or plotly for spanning grid cells.

Registering a third-party backend

Any class satisfying BackendProtocol can be registered:

cplots.register_backend("mybackend", MyBackend())

Or via pyproject.toml entry points for automatic discovery:

[project.entry-points."cplots.backends"]
mybackend = "mypkg.backend:MyBackend"