cplots 0.0.1__py3-none-any.whl

cplots/__init__.py

@@ -0,0 +1,85 @@
+"""cplots: a backend-agnostic cosmological plotting library.
+
+Three-layer architecture:
+  PlotData (immutable input) → PlotSpec IR → Backend (renders native figure)
+
+Backends (matplotlib, plotly, altair) are selected per call, via context
+manager, or globally. Third-party backends register via entry points.
+
+Example:
+    >>> import numpy as np
+    >>> import cplots
+    >>> k = np.logspace(-3, 0, 200)
+    >>> pk = k ** -1.5
+    >>> cplots.PKSpectrum(k, pk, label="P(k)").show()
+"""
+
+# Trigger backend registration by importing the backends package.
+import cplots.backends  # noqa: E402, F401
+from cplots.config import backend, resolve_backend, set_backend
+from cplots.core.base import Plot
+from cplots.core.data import (
+    BackgroundData,
+    ClData,
+    PKData,
+    PlotData,
+    TriangleData,
+    XYData,
+    XYZData,
+)
+from cplots.core.incremental import (
+    build_incrementally,
+    incremental,
+    labeled_prefixes,
+    sequence_prefixes,
+)
+from cplots.core.protocols import BackendProtocol
+from cplots.core.registry import get_backend, register_backend
+from cplots.core.spec import FigureSpec, PanelSpec, PlotSpec, Trace
+from cplots.core.theme import DARK, PUBLICATION, ThemeSpec
+from cplots.data.adapters import to_plot_data
+from cplots.figure import Figure
+from cplots.plots.background import BackgroundEvolution
+from cplots.plots.power_spectrum import ClSpectrum, PKSpectrum, PowerSpectrumBase
+from cplots.plots.triangle import TrianglePlot
+from cplots.plots.xy import XYPlot
+from cplots.plots.xyz_colored import XYZColored
+from cplots.plots.xyz_colored_grid import XYZColoredGrid
+
+__all__ = [
+    "DARK",
+    "Figure",
+    "FigureSpec",
+    "PanelSpec",
+    "PUBLICATION",
+    "BackendProtocol",
+    "BackgroundData",
+    "BackgroundEvolution",
+    "ClData",
+    "ClSpectrum",
+    "PKData",
+    "PKSpectrum",
+    "Plot",
+    "PlotData",
+    "PlotSpec",
+    "PowerSpectrumBase",
+    "ThemeSpec",
+    "Trace",
+    "TriangleData",
+    "TrianglePlot",
+    "XYData",
+    "XYPlot",
+    "XYZColored",
+    "XYZColoredGrid",
+    "XYZData",
+    "backend",
+    "build_incrementally",
+    "get_backend",
+    "incremental",
+    "labeled_prefixes",
+    "register_backend",
+    "resolve_backend",
+    "sequence_prefixes",
+    "set_backend",
+    "to_plot_data",
+]

cplots/backends/__init__.py

@@ -0,0 +1,4 @@
+from cplots.backends._base import BaseBackend
+from cplots.backends.matplotlib import MatplotlibBackend
+
+__all__ = ["BaseBackend", "MatplotlibBackend"]

cplots/backends/_base.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class BaseBackend:
+    """Optional base class for backends that want automatic registration.
+
+    Subclass with the ``name`` keyword to self-register on class creation::
+
+        class MyBackend(BaseBackend, name="mybackend"):
+            def render(self, spec): ...
+            ...
+
+    The ``name`` keyword triggers :func:`~cplots.core.registry.register_backend`
+    at class-definition time so no manual registration call is required.
+    """
+
+    def __init_subclass__(cls, name: str | None = None, **kw: Any) -> None:
+        super().__init_subclass__(**kw)
+        if name is not None:
+            from cplots.core.registry import register_backend
+
+            register_backend(name, cls())
+
+    def render_figure(self, spec: Any) -> Any:
+        """Render a multi-panel FigureSpec.
+
+        Raises:
+            NotImplementedError: Subclasses that support multi-panel layouts
+                must override this method.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} does not implement render_figure(). "
+            "Multi-panel layouts require a backend that supports FigureSpec."
+        )

cplots/backends/altair.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from cplots.backends._base import BaseBackend
+from cplots.core.labels import strip_latex
+from cplots.core.spec import FigureSpec, PlotSpec
+from cplots.core.theme import ThemeSpec
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+def _css_color(color: str) -> str:
+    """Normalise matplotlib's 'none' to a CSS-compatible transparent value."""
+    return "transparent" if color == "none" else color
+
+
+class AltairBackend(BaseBackend, name="altair"):
+    """Altair (Vega-Lite) backend for cplots.
+
+    Produces ``altair.Chart`` objects. Registered automatically under the name
+    ``"altair"``.
+
+    Note:
+        Rowspan > 1 in multi-panel layouts is not supported; use the matplotlib
+        or plotly backend for spanning layouts.
+
+    Requires: ``pip install cplots[altair]``
+    """
+
+    @staticmethod
+    def _fmt(text: str, spec: PlotSpec) -> str:
+        return text if spec.latex_labels else strip_latex(text)
+
+    def __init__(self) -> None:
+        try:
+            import altair  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "The altair backend requires altair. "
+                "Install it with: pip install cplots[altair]"
+            ) from exc
+
+    def render(self, spec: PlotSpec, *, interactive: bool = True) -> alt.Chart:
+        """Render a single PlotSpec to an Altair Chart.
+
+        Args:
+            spec: Backend-agnostic plot specification.
+            interactive: Whether to call ``.interactive()`` on the chart,
+                enabling pan and zoom in Jupyter notebooks.
+
+        Returns:
+            An ``altair.Chart`` (or layered chart for multi-trace plots).
+        """
+        import altair as alt
+        import pandas as pd
+
+        x_label = self._fmt(spec.x_label, spec)
+        y_label = self._fmt(spec.y_label, spec)
+        title = self._fmt(spec.title, spec)
+
+        if spec.colormap is not None:
+            chart = self._render_colormap(spec, x_label, y_label)
+        else:
+            layers = []
+            colors = spec.theme.palette if spec.theme else None
+            for i, trace in enumerate(spec.traces):
+                df = pd.DataFrame({"x": trace.x, "y": trace.y})
+                color = colors[i % len(colors)] if colors else alt.Undefined
+                label = self._fmt(trace.label, spec) if trace.label else None
+                layer = (
+                    alt.Chart(df)
+                    .mark_line()
+                    .encode(
+                        x=alt.X("x", scale=alt.Scale(type=spec.x_scale), title=x_label),
+                        y=alt.Y("y", scale=alt.Scale(type=spec.y_scale), title=y_label),
+                        color=alt.value(color) if isinstance(color, str) else alt.Undefined,
+                        tooltip=["x", "y"],
+                    )
+                )
+                if label:
+                    layer = layer.properties(title=label)
+                layers.append(layer)
+            chart = alt.layer(*layers)
+
+        props: dict[str, Any] = {}
+        if title:
+            props["title"] = title
+        if spec.figsize:
+            props["width"] = int(spec.figsize[0] * 96)
+            props["height"] = int(spec.figsize[1] * 96)
+        if props:
+            chart = chart.properties(**props)
+        if interactive:
+            chart = chart.interactive()
+        return chart
+
+    def _render_colormap(
+        self,
+        spec: PlotSpec,
+        x_label: str,
+        y_label: str,
+        *,
+        color_domain: list[float] | None = None,
+        show_legend: bool = True,
+        gradient_length: int | None = None,
+    ) -> Any:
+        import altair as alt
+        import pandas as pd
+
+        frames = []
+        for trace in spec.traces:
+            df = pd.DataFrame({
+                "x": trace.x,
+                "y": trace.y,
+                "z": trace.color_value,
+                "label": self._fmt(trace.label, spec) if trace.label else "",
+            })
+            frames.append(df)
+        data = pd.concat(frames, ignore_index=True)
+
+        chart_height = gradient_length or (int(spec.figsize[1] * 96) if spec.figsize else 300)
+        legend = alt.Legend(
+            title=self._fmt(spec.z_label, spec) if spec.z_label else None,
+            gradientLength=chart_height,
+            titleOrient="bottom",
+        )
+        scale_kwargs: dict[str, Any] = {"scheme": spec.colormap}
+        if color_domain is not None:
+            scale_kwargs["domain"] = color_domain
+        color_enc = alt.Color(
+            "z:Q",
+            scale=alt.Scale(**scale_kwargs),
+            legend=legend if (spec.colorbar and show_legend) else None,
+        )
+        return (
+            alt.Chart(data)
+            .mark_line()
+            .encode(
+                x=alt.X("x:Q", scale=alt.Scale(type=spec.x_scale), title=x_label),
+                y=alt.Y("y:Q", scale=alt.Scale(type=spec.y_scale), title=y_label),
+                color=color_enc,
+                detail="label:N",
+                tooltip=["x:Q", "y:Q", "z:Q"],
+            )
+        )
+
+    def _render_panel(
+        self,
+        spec: PlotSpec,
+        *,
+        interactive: bool = True,
+        panel_width: int | None = None,
+        panel_height: int | None = None,
+    ) -> Any:
+        """Render a single PlotSpec as an Altair chart.
+
+        ``panel_width`` / ``panel_height`` override the chart size when the
+        caller (e.g. ``render_figure``) wants to distribute a shared figsize
+        across panels.  Size must be set on each individual chart rather than
+        on the combined ``hconcat``/``vconcat`` container, which does not
+        accept ``width``/``height`` properties.
+        """
+        chart = self.render(spec, interactive=interactive)
+        props: dict[str, Any] = {}
+        if panel_width is not None:
+            props["width"] = panel_width
+        if panel_height is not None:
+            props["height"] = panel_height
+        if props:
+            chart = chart.properties(**props)
+        return chart
+
+    def render_figure(self, spec: FigureSpec) -> Any:
+        """Render a multi-panel FigureSpec as an Altair hconcat/vconcat chart.
+
+        Args:
+            spec: Backend-agnostic multi-panel figure specification.
+
+        Returns:
+            An ``altair.Chart``, ``altair.HConcatChart``, or
+            ``altair.VConcatChart`` depending on layout.
+
+        Raises:
+            NotImplementedError: If any panel has ``rowspan > 1``.
+        """
+        import altair as alt
+
+        if spec.theme is not None:
+            self.apply_theme(spec.theme)
+
+        for panel in spec.panels:
+            if panel.rowspan > 1:
+                raise NotImplementedError(
+                    "The Altair backend does not support rowspan > 1. "
+                    "Use the matplotlib or plotly backend for spanning layouts."
+                )
+
+        # Distribute figsize across panels; size is set per-chart because
+        # HConcatChart / VConcatChart do not accept width/height properties.
+        panel_w = int(spec.figsize[0] * 96 / spec.ncols) if spec.figsize else None
+        panel_h = int(spec.figsize[1] * 96 / spec.nrows) if spec.figsize else None
+
+        if spec.colormap is not None:
+            z_vals = [
+                t.color_value
+                for p in spec.panels
+                for t in p.plot.traces
+                if t.color_value is not None
+            ]
+            vmin, vmax = min(z_vals), max(z_vals)
+            domain = [vmin, vmax]
+            n_panels = len(spec.panels)
+            panel_counter = 0
+
+            rows: list[Any] = []
+            for r in range(spec.nrows):
+                row_panels = sorted(
+                    [p for p in spec.panels if p.row == r], key=lambda p: p.col
+                )
+                charts: list[Any] = []
+                for panel in row_panels:
+                    p_spec = panel.plot
+                    x_label = self._fmt(p_spec.x_label, p_spec)
+                    y_label = self._fmt(p_spec.y_label, p_spec)
+                    is_last = panel_counter == n_panels - 1
+                    chart = self._render_colormap(
+                        p_spec,
+                        x_label,
+                        y_label,
+                        color_domain=domain,
+                        show_legend=is_last and spec.colorbar,
+                        gradient_length=panel_h,
+                    )
+                    props: dict[str, Any] = {}
+                    if panel_w is not None:
+                        props["width"] = panel_w
+                    if panel_h is not None:
+                        props["height"] = panel_h
+                    if props:
+                        chart = chart.properties(**props)
+                    charts.append(chart)
+                    panel_counter += 1
+                rows.append(charts[0] if len(charts) == 1 else alt.hconcat(*charts))
+
+            return rows[0] if len(rows) == 1 else alt.vconcat(*rows)
+
+        rows_plain: list[Any] = []
+        for r in range(spec.nrows):
+            row_panels = sorted(
+                [p for p in spec.panels if p.row == r], key=lambda p: p.col
+            )
+            charts_plain = [
+                self._render_panel(p.plot, panel_width=panel_w, panel_height=panel_h)
+                for p in row_panels
+            ]
+            rows_plain.append(
+                charts_plain[0] if len(charts_plain) == 1 else alt.hconcat(*charts_plain)
+            )
+
+        return rows_plain[0] if len(rows_plain) == 1 else alt.vconcat(*rows_plain)
+
+    def show(self, fig: alt.Chart, **kwargs: Any) -> None:
+        fig.show(**kwargs)
+
+    def save(
+        self,
+        fig: alt.Chart,
+        path: str | os.PathLike[str],
+        **kwargs: Any,
+    ) -> None:
+        fig.save(str(path), **kwargs)
+
+    def apply_theme(self, theme: ThemeSpec) -> None:
+        """Register and enable a custom Vega-Lite theme from a ThemeSpec.
+
+        Args:
+            theme: Theme to apply. Sets background color, font family, and
+                axis label font sizes via the Vega-Lite theme config.
+        """
+        import altair as alt
+
+        alt.themes.register(
+            "cplots_custom",
+            lambda: {
+                "config": {
+                    "background": _css_color(theme.background_color),
+                    "font": theme.font_family,
+                    "axisX": {"labelFontSize": theme.font_size},
+                    "axisY": {"labelFontSize": theme.font_size},
+                }
+            },
+        )
+        alt.themes.enable("cplots_custom")

cplots/backends/matplotlib.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from cplots.backends._base import BaseBackend
+from cplots.core.spec import FigureSpec, PlotSpec
+from cplots.core.theme import ThemeSpec
+
+if TYPE_CHECKING:
+    import matplotlib.axes
+    import matplotlib.figure
+
+
+class MatplotlibBackend(BaseBackend, name="matplotlib"):
+    """Matplotlib backend for cplots.
+
+    Produces ``matplotlib.figure.Figure`` objects. Registered automatically
+    under the name ``"matplotlib"``.
+
+    Requires: ``pip install cplots[matplotlib]``
+    """
+
+    def __init__(self) -> None:
+        try:
+            import matplotlib as mpl  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "The matplotlib backend requires matplotlib. "
+                "Install it with: pip install cplots[matplotlib]"
+            ) from exc
+
+    def _draw_panel(
+        self,
+        fig: matplotlib.figure.Figure,
+        ax: matplotlib.axes.Axes,
+        spec: PlotSpec,
+        theme: ThemeSpec | None,
+    ) -> None:
+        """Draw a single PlotSpec onto an existing Axes (palette and colormap paths)."""
+        bg = theme.background_color if theme else "white"
+        ax.set_facecolor(bg)
+        if spec.colormap is not None:
+            self._render_colormap(fig, ax, spec)
+        else:
+            colors = theme.palette if theme else None
+            for i, trace in enumerate(spec.traces):
+                color = colors[i % len(colors)] if colors else None
+                ax.plot(trace.x, trace.y, label=trace.label or None, color=color, **trace.style)
+            if any(t.label for t in spec.traces):
+                ax.legend()
+        ax.set_xscale(spec.x_scale)
+        ax.set_yscale(spec.y_scale)
+        if spec.x_label:
+            ax.set_xlabel(spec.x_label)
+        if spec.y_label:
+            ax.set_ylabel(spec.y_label)
+        if spec.title:
+            ax.set_title(spec.title)
+
+    def _draw_colormap_lines(
+        self,
+        ax: matplotlib.axes.Axes,
+        spec: PlotSpec,
+        norm: Any,
+        cmap: Any,
+    ) -> None:
+        """Draw colormap traces using pre-computed global norm/cmap (no colorbar)."""
+        for trace in spec.traces:
+            color = cmap(norm(trace.color_value)) if trace.color_value is not None else None
+            ax.plot(trace.x, trace.y, label=trace.label or None, color=color, **trace.style)
+        ax.set_xscale(spec.x_scale)
+        ax.set_yscale(spec.y_scale)
+        if spec.x_label:
+            ax.set_xlabel(spec.x_label)
+        if spec.y_label:
+            ax.set_ylabel(spec.y_label)
+        if spec.title:
+            ax.set_title(spec.title)
+
+    def render(self, spec: PlotSpec) -> matplotlib.figure.Figure:
+        """Render a single PlotSpec to a matplotlib Figure.
+
+        Args:
+            spec: Backend-agnostic plot specification.
+
+        Returns:
+            A closed ``matplotlib.figure.Figure`` (call ``show()`` to display).
+        """
+        import matplotlib.pyplot as plt
+
+        # Apply theme to rcParams before creating the figure so that newly
+        # created Text/Tick/Axis objects inherit the right defaults.
+        if spec.theme is not None:
+            self.apply_theme(spec.theme)
+
+        fig, ax = plt.subplots(figsize=spec.figsize)
+
+        # Set backgrounds directly on the objects — rcParams alone won't
+        # retroactively update a figure that has already been created.
+        bg = spec.theme.background_color if spec.theme else "white"
+        fig.patch.set_facecolor(bg)
+        self._draw_panel(fig, ax, spec, spec.theme)
+
+        plt.close(fig)
+        return fig
+
+    def _render_colormap(self, fig: Any, ax: Any, spec: PlotSpec) -> None:
+        import matplotlib.cm as cm
+        import matplotlib.colors as mcolors
+        import matplotlib.pyplot as plt
+
+        z_values = [t.color_value for t in spec.traces if t.color_value is not None]
+        vmin, vmax = min(z_values), max(z_values)
+        norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
+        cmap = plt.get_cmap(spec.colormap)
+
+        for trace in spec.traces:
+            color = cmap(norm(trace.color_value)) if trace.color_value is not None else None
+            ax.plot(trace.x, trace.y, label=trace.label or None, color=color, **trace.style)
+
+        if spec.colorbar:
+            sm = cm.ScalarMappable(norm=norm, cmap=cmap)
+            sm.set_array([])
+            pad = spec.colorbar_pad if spec.colorbar_pad is not None else 0.02
+            fig.colorbar(sm, ax=ax, label=spec.z_label or None, pad=pad)
+
+    def render_figure(self, spec: FigureSpec) -> matplotlib.figure.Figure:
+        """Render a multi-panel FigureSpec to a matplotlib Figure.
+
+        Args:
+            spec: Backend-agnostic multi-panel figure specification.
+
+        Returns:
+            A closed ``matplotlib.figure.Figure``.
+        """
+        import matplotlib.gridspec as mgridspec
+        import matplotlib.pyplot as plt
+
+        if spec.theme is not None:
+            self.apply_theme(spec.theme)
+
+        bg = spec.theme.background_color if spec.theme else "white"
+        fig = plt.figure(figsize=spec.figsize)
+        fig.patch.set_facecolor(bg)
+
+        gs = mgridspec.GridSpec(
+            spec.nrows,
+            spec.ncols,
+            width_ratios=spec.width_ratios,
+            height_ratios=spec.height_ratios,
+            figure=fig,
+        )
+
+        # Pre-compute global colormap normalization for the shared colorbar path.
+        shared_norm: Any = None
+        shared_cmap: Any = None
+        if spec.colormap is not None:
+            import matplotlib.colors as mcolors
+
+            z_vals = [
+                t.color_value
+                for p in spec.panels
+                for t in p.plot.traces
+                if t.color_value is not None
+            ]
+            vmin, vmax = min(z_vals), max(z_vals)
+            shared_norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
+            shared_cmap = plt.get_cmap(spec.colormap)
+
+        col_x_master: dict[int, matplotlib.axes.Axes] = {}
+        row_y_master: dict[int, matplotlib.axes.Axes] = {}
+        all_axes: list[matplotlib.axes.Axes] = []
+
+        for panel in spec.panels:
+            r, c, rs, cs = panel.row, panel.col, panel.rowspan, panel.colspan
+            share_x = col_x_master.get(c) if spec.sharex else None
+            share_y = row_y_master.get(r) if spec.sharey else None
+            ax = fig.add_subplot(gs[r : r + rs, c : c + cs], sharex=share_x, sharey=share_y)
+            col_x_master.setdefault(c, ax)
+            row_y_master.setdefault(r, ax)
+            ax.set_facecolor(bg)
+            all_axes.append(ax)
+
+            if shared_norm is not None:
+                self._draw_colormap_lines(ax, panel.plot, shared_norm, shared_cmap)
+            else:
+                self._draw_panel(fig, ax, panel.plot, spec.theme)
+
+        if shared_norm is not None and spec.colorbar:
+            import matplotlib.cm as cm
+
+            sm = cm.ScalarMappable(norm=shared_norm, cmap=shared_cmap)
+            sm.set_array([])
+            pad = spec.colorbar_pad if spec.colorbar_pad is not None else 0.02
+            fig.colorbar(sm, ax=all_axes, label=spec.z_label or None, pad=pad)
+
+        plt.close(fig)
+        return fig
+
+    def show(self, fig: matplotlib.figure.Figure, **kwargs: Any) -> None:
+        import matplotlib.pyplot as plt
+
+        plt.figure(fig.number)
+        plt.show(**kwargs)
+
+    def save(
+        self,
+        fig: matplotlib.figure.Figure,
+        path: str | os.PathLike[str],
+        **kwargs: Any,
+    ) -> None:
+        fig.savefig(path, **kwargs)
+
+    def apply_theme(self, theme: ThemeSpec) -> None:
+        """Apply a ThemeSpec to matplotlib's global rcParams.
+
+        Args:
+            theme: Theme to apply. ``theme.extra`` keys are applied directly
+                to ``mpl.rcParams``.  rcParams are reset to defaults first so
+                previous theme settings do not bleed into the current render.
+        """
+        import matplotlib as mpl
+
+        # Reset to defaults first so that keys set by a previous theme
+        # (e.g. DARK's white tick/label colors) don't bleed into this render.
+        mpl.rcdefaults()
+        mpl.rcParams["font.family"] = theme.font_family
+        mpl.rcParams["font.size"] = theme.font_size
+        mpl.rcParams["figure.facecolor"] = theme.background_color
+        mpl.rcParams["axes.facecolor"] = theme.background_color
+        for key, value in theme.extra.items():
+            mpl.rcParams[key] = value