quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/figure_break.py

@@ -0,0 +1,152 @@
+"""Publication rendering for a manually-broken x-axis (ORIGIN_GAP_PLAN #21).
+
+Split out of ``calc.figure`` purely to stay under the 500-line god-module
+ceiling (`_render_impl` calls ``render_breaks_impl`` when its ``overrides``
+carry ``x_breaks``); the behavioural contract is still
+``calc.figure``'s — see ``_validate_overrides``'s ``x_breaks`` checks and
+``_render_impl``'s dispatch. Pure layer: data in -> image bytes out.
+
+Renders one matplotlib panel per contiguous x-range between the (sorted,
+validated) break pairs, sharing the y scale (``sharey``), with a diagonal
+break glyph at each seam and the touching inner spines hidden — the paneled
+representation the plan's RESOLVED decision calls for (never a
+discontinuous-tick trick that lies about slope). Each panel plots the FULL
+series and clips its own view via ``set_xlim``, so no data slicing is needed.
+
+Scoped deliberately smaller than ``_render_impl``'s single-axes path: the
+full ``_apply_overrides`` sweep (legend/spines/limits/margins) targets ONE
+axes and a broken figure has several, so breaks combine with the plot itself
++ title/labels/basic legend/grid only — not the rest of gap #11's property
+panel. Also not compatible with the figure-hitmap collector (`collect_map`),
+which harvests pixel boxes off a single axes. Same scope limit for MAIN
+#13/#14: a `series_styles` entry's `fill`/`color_by` keys are silently
+ignored here (each panel draws a plain line) -- fill-under/-between and
+colour-mapped scatter are single-axes features, like the rest of gap #11.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+from numpy.typing import ArrayLike, NDArray  # noqa: E402
+
+from quantized.calc.figure import _plot_kwargs  # noqa: E402
+from quantized.calc.figure_scale import apply_axis_scale, resolve_axis_scale  # noqa: E402
+from quantized.calc.figure_ticks import apply_tick_formats  # noqa: E402
+
+__all__ = ["render_breaks_impl"]
+
+
+def render_breaks_impl(
+    x: NDArray[np.float64],
+    series: Sequence[tuple[str, ArrayLike]],
+    *,
+    breaks: list[tuple[float, float]],
+    x_log: bool,
+    y_log: bool,
+    x_scale: str | None = None,
+    y_scale: str | None = None,
+    title: str,
+    x_label: str,
+    y_label: str,
+    fmt: str,
+    st: Any,
+    ov: Mapping[str, Any],
+    dpi: int,
+    figsize: tuple[float, float],
+    series_styles: Sequence[Mapping[str, Any] | None] | None,
+    x_fmt: Mapping[str, Any] | None = None,
+    y_fmt: Mapping[str, Any] | None = None,
+) -> bytes:
+    """Render ``series`` against ``x`` with the x-axis elided over each
+    ``[lo, hi]`` pair in ``breaks`` (already sorted/validated non-overlapping
+    by ``calc.figure._validate_overrides``). ``x_fmt``/``y_fmt`` (MAIN #24)
+    are applied to EVERY panel's axes (see ``figure_ticks.apply_tick_formats``);
+    a shared y-axis (``sharey``) still draws tick labels only on panel 0
+    (matplotlib's own ``sharey`` + this module's ``tick_params(left=False)``
+    on the rest), so ``y_fmt`` only visibly affects that panel, but is
+    applied uniformly for simplicity/consistency."""
+    finite = x[np.isfinite(x)]
+    xlo = float(finite.min()) if finite.size else 0.0
+    xhi = float(finite.max()) if finite.size else 1.0
+    bounds: list[tuple[float, float]] = []
+    lo = xlo
+    for b0, b1 in breaks:
+        bounds.append((lo, b0))
+        lo = b1
+    bounds.append((lo, xhi))
+    n = len(bounds)
+    widths = [max(hi - lo, 1e-9) for lo, hi in bounds]
+
+    fig, axes_obj = plt.subplots(
+        1, n, sharey=True, figsize=figsize, gridspec_kw={"width_ratios": widths, "wspace": 0.06}
+    )
+    axes = [axes_obj] if n == 1 else list(axes_obj)
+    try:
+        handles: list[Any] = []
+        labels_out: list[str] = []
+        for i, ax in enumerate(axes):
+            for si, (label, y) in enumerate(series):
+                spec = series_styles[si] if series_styles and si < len(series_styles) else None
+                kw = _plot_kwargs(st.line_width, st.marker_size, spec)
+                ax.plot(x, np.asarray(y, dtype=float), label=label, **kw)
+            lo, hi = bounds[i]
+            ax.set_xlim(lo, hi)
+            apply_axis_scale(ax, "x", resolve_axis_scale(x_scale, x_log))
+            apply_axis_scale(ax, "y", resolve_axis_scale(y_scale, y_log))
+            apply_tick_formats(ax, x_fmt, y_fmt)
+            if i == 0:
+                handles, labels_out = ax.get_legend_handles_labels()
+            if i > 0:
+                ax.spines["left"].set_visible(False)
+                ax.tick_params(left=False)
+            if i < n - 1:
+                ax.spines["right"].set_visible(False)
+            if not st.box_on:
+                ax.spines["top"].set_visible(False)
+            if st.grid_alpha > 0:
+                ax.grid(True, alpha=st.grid_alpha)
+
+        # Diagonal break glyphs (matplotlib's standard broken-axis recipe):
+        # short strokes angled across each seam, on both the outgoing panel's
+        # right edge and the incoming panel's left edge.
+        d = 0.4
+        glyph_kw = {
+            "marker": [(-1, -d), (1, d)],
+            "markersize": 8,
+            "linestyle": "none",
+            "color": "k",
+            "mec": "k",
+            "mew": 1,
+            "clip_on": False,
+        }
+        for i in range(n - 1):
+            axes[i].plot([1], [0], transform=axes[i].transAxes, **glyph_kw)
+            axes[i].plot([1], [1], transform=axes[i].transAxes, **glyph_kw)
+            axes[i + 1].plot([0], [0], transform=axes[i + 1].transAxes, **glyph_kw)
+            axes[i + 1].plot([0], [1], transform=axes[i + 1].transAxes, **glyph_kw)
+
+        if title:
+            fig.suptitle(title)
+        if x_label:
+            fig.supxlabel(x_label)
+        if y_label:
+            axes[0].set_ylabel(y_label)
+        if len(series) > 1 and "legend" not in ov and handles:
+            axes[-1].legend(
+                handles, labels_out, frameon=st.legend_box, fontsize=st.legend_font_size,
+                loc=st.legend_location,
+            )
+        buf = BytesIO()
+        fig.savefig(buf, format=fmt, dpi=dpi)
+        return buf.getvalue()
+    finally:
+        plt.close(fig)

quantized/calc/figure_categorical.py

@@ -0,0 +1,156 @@
+"""Publication rendering for grouped/stacked bar (categorical) plots.
+
+ORIGIN_GAP_PLAN #20 (export half). Pure layer: a category x series matrix in
+-> image bytes out — the SAME matrix shape the interactive stat stage's "bar"
+mode computes locally (frontend `lib/barlayout.buildBarMatrix`: mean per
+category/series, SEM for the error bar), so the exported figure matches the
+on-screen bars. Shares ``render_figure``'s style presets and formats
+(``figure_styles.figure_style``), matching ``figure_statplots.py``'s template.
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+
+__all__ = ["render_categorical_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+
+
+def _to_matrix(
+    values: list[list[float]], n_groups: int, n_series: int, name: str
+) -> np.ndarray:
+    arr = np.asarray(values, dtype=float)
+    if arr.shape != (n_groups, n_series):
+        raise ValueError(f"{name} must have shape ({n_groups}, {n_series}), got {arr.shape}")
+    return arr
+
+
+def _to_error_matrix(
+    errors: list[list[float | None]] | None, n_groups: int, n_series: int
+) -> np.ndarray | None:
+    if errors is None:
+        return None
+    if len(errors) != n_groups:
+        raise ValueError(f"errors must have {n_groups} rows, got {len(errors)}")
+    out = np.full((n_groups, n_series), np.nan)
+    for gi, row in enumerate(errors):
+        if len(row) != n_series:
+            raise ValueError(f"errors row {gi} must have {n_series} entries, got {len(row)}")
+        for si, e in enumerate(row):
+            if e is not None:
+                out[gi, si] = float(e)
+    return out
+
+
+def render_categorical_figure(
+    groups: list[str],
+    series: list[str],
+    values: list[list[float]],
+    errors: list[list[float | None]] | None = None,
+    *,
+    stacked: bool = False,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int = 200,
+) -> bytes:
+    """Render a grouped or stacked bar chart to image bytes.
+
+    ``values[g][s]`` is the bar height (mean) for category ``groups[g]``,
+    series ``series[s]``; ``errors[g][s]`` (optional, ``None`` entries allowed
+    = no whisker for that bar) is its SEM. ``stacked=False`` clusters series
+    side by side within each category; ``stacked=True`` draws one bar per
+    category with series stacked bottom-to-top (only the topmost segment's
+    error bar is drawn, matching the interactive stat stage's convention —
+    a stacked bar's lower segments' own spread isn't visually meaningful once
+    summed).
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if not groups:
+        raise ValueError("groups must be non-empty")
+    if not series:
+        raise ValueError("series must be non-empty")
+    # Rich-text labels (GOTO #5): de-math INVALID $...$ so savefig never raises.
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+    groups = [safe_mathtext_label(str(g)) for g in groups]
+    series = [safe_mathtext_label(str(s)) for s in series]
+    n_groups, n_series = len(groups), len(series)
+    vals = _to_matrix(values, n_groups, n_series, "values")
+    errs = _to_error_matrix(errors, n_groups, n_series)
+
+    st = figure_style(style)
+    figsize = (width_in or st.fig_width_in, height_in or st.fig_height_in)
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.title_font_size,
+    }
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, ax = plt.subplots(figsize=figsize)
+        try:
+            x = np.arange(n_groups, dtype=float)
+            if stacked:
+                bottom = np.zeros(n_groups)
+                for si in range(n_series):
+                    yerr = errs[:, si] if errs is not None and si == n_series - 1 else None
+                    ax.bar(
+                        x, vals[:, si], 0.68, bottom=bottom, yerr=yerr, capsize=3,
+                        label=series[si],
+                    )
+                    bottom = bottom + np.nan_to_num(vals[:, si])
+            else:
+                width = 0.8 / n_series
+                for si in range(n_series):
+                    offset = (si - (n_series - 1) / 2) * width
+                    yerr = errs[:, si] if errs is not None else None
+                    ax.bar(
+                        x + offset, vals[:, si], width * 0.85, yerr=yerr, capsize=3,
+                        label=series[si],
+                    )
+            ax.set_xticks(x)
+            ax.set_xticklabels(groups)
+            ax.axhline(0, color="0.3", linewidth=0.8)  # baseline, visible for mixed-sign data
+            if title:
+                ax.set_title(title)
+            if x_label:
+                ax.set_xlabel(x_label)
+            if y_label:
+                ax.set_ylabel(y_label)
+            if not st.box_on:
+                ax.spines["top"].set_visible(False)
+                ax.spines["right"].set_visible(False)
+            if n_series > 1:
+                ax.legend(  # type: ignore[call-overload]
+                    frameon=st.legend_box, fontsize=st.legend_font_size, loc=st.legend_location,
+                )
+            if st.grid_alpha > 0:
+                ax.grid(True, alpha=st.grid_alpha, axis="y")
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)

quantized/calc/figure_corner.py

@@ -0,0 +1,229 @@
+"""Publication rendering for MCMC/bootstrap posterior corner (pairs) plots.
+
+ORIGIN_GAP_PLAN #29 residual. Pure layer: an ``(n_samples, k)`` array of
+joint parameter draws in -> image bytes out. matplotlib only -- no
+``corner.py`` dependency, deliberately, since the whole grid is a few hundred
+lines of plain axes. Diagonal panels are 1-D marginal histograms; panels
+below the diagonal are 2-D density histograms of each parameter pair; the
+upper triangle is left blank -- the conventional "corner plot" layout (see
+Foreman-Mackey's ``corner`` package for the reference look this mirrors).
+Shares ``calc.figure_styles`` presets and ``calc.figure``'s resolved-dpi
+convention (an explicit ``dpi`` overrides the preset; otherwise the preset's
+calibrated dpi is used), so corner exports match the rest of the publication
+export pipeline.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+from matplotlib.ticker import MaxNLocator  # noqa: E402
+from numpy.typing import ArrayLike, NDArray  # noqa: E402
+
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+
+__all__ = ["render_corner_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+_PANEL_IN = 2.1  # per-parameter panel edge length (inches) at the default size
+_MAX_TICKS = 4
+_TRUTH_COLOR = "firebrick"
+
+
+def render_corner_figure(
+    samples: ArrayLike,
+    param_names: Sequence[str],
+    *,
+    truths: Sequence[float] | None = None,
+    title: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    dpi: int | None = None,
+    bins: str | int = "fd",
+    width_in: float | None = None,
+    height_in: float | None = None,
+) -> bytes:
+    """Render a pairwise posterior/bootstrap corner (pairs) plot.
+
+    ``samples`` is ``(n_samples, k)`` joint parameter draws -- e.g. the
+    ``samples`` array from :func:`calc.fit_bootstrap.fit_posterior` or
+    ``bootstrap_fit(..., return_samples=True)``'s ``boot_samples``.
+    ``param_names`` names the ``k`` columns (must match ``samples.shape[1]``).
+
+    Diagonal panels are 1-D marginal histograms (``bins`` -- a count or a
+    numpy binning rule, e.g. ``"fd"``); panels below the diagonal are 2-D
+    density histograms of each parameter pair; the upper triangle is left
+    blank. ``truths`` (length ``k``), when given, draws a reference dashed
+    line (diagonal panels) / crosshair (off-diagonal panels) at each
+    parameter's fitted value.
+
+    ``fmt`` / ``style`` / ``width_in`` / ``height_in`` match ``render_figure``
+    (default panel geometry scales with ``k`` -- corner grids need more
+    canvas than a single-series plot -- unless explicit sizes are given).
+    ``dpi`` defaults to the preset's calibrated resolution when not given
+    (``None``), same as ``calc.figure``'s ``resolved_dpi``.
+
+    Raises ``ValueError`` on shape mismatches (``param_names``/``truths``
+    length vs. the sample columns) or too few finite joint samples.
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+
+    arr = np.asarray(samples, dtype=float)
+    if arr.ndim != 2:
+        raise ValueError(
+            f"samples must be a 2-D (n_samples, n_params) array, got ndim={arr.ndim}"
+        )
+    _n_samples, k = arr.shape
+    if k < 1:
+        raise ValueError("samples needs at least one parameter column")
+    names = [safe_mathtext_label(str(nm)) for nm in param_names]
+    # (Rich-text labels, GOTO #5: de-math INVALID $...$ so savefig never raises.)
+    if len(names) != k:
+        raise ValueError(f"param_names has {len(names)} entries, samples has {k} columns")
+    if truths is not None and len(truths) != k:
+        raise ValueError(f"truths has {len(truths)} entries, samples has {k} columns")
+
+    finite = arr[np.all(np.isfinite(arr), axis=1)]
+    if finite.shape[0] < 2:
+        raise ValueError("need at least 2 finite joint samples to render a corner plot")
+    tr = np.asarray(truths, dtype=float) if truths is not None else None
+
+    title = safe_mathtext_label(title)
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+    figsize = (width_in or _PANEL_IN * k, height_in or _PANEL_IN * k)
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    # Shrink tick labels a touch as the grid grows so k up to ~6 stays readable.
+    tick_fs = max(st.font_size - max(k - 2, 0), 6.0)
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": tick_fs,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.title_font_size,
+        "xtick.labelsize": tick_fs,
+        "ytick.labelsize": tick_fs,
+        "xtick.direction": st.tick_dir,
+        "ytick.direction": st.tick_dir,
+    }
+    ranges = [_pad_range(finite[:, i]) for i in range(k)]
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, axes = plt.subplots(k, k, figsize=figsize, squeeze=False)
+        try:
+            for row in range(k):
+                for col in range(k):
+                    ax = axes[row][col]
+                    if col > row:
+                        ax.axis("off")
+                        continue
+                    truth_col = float(tr[col]) if tr is not None else None
+                    if col == row:
+                        _draw_marginal(ax, finite[:, col], bins, ranges[col], truth_col)
+                    else:
+                        truth_row = float(tr[row]) if tr is not None else None
+                        _draw_pair(
+                            ax, finite[:, col], finite[:, row], bins,
+                            ranges[col], ranges[row], truth_col, truth_row,
+                        )
+                    _style_panel(ax, row, col, k, names, st)
+            if title:
+                fig.suptitle(title, fontsize=st.title_font_size)
+                fig.tight_layout(rect=(0.0, 0.0, 1.0, 0.96))
+            else:
+                fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def _pad_range(v: NDArray[np.float64]) -> tuple[float, float]:
+    """Axis limits for one parameter: data range + 5% pad (a small fixed
+    window around a degenerate, all-equal column)."""
+    lo, hi = float(np.min(v)), float(np.max(v))
+    if hi <= lo:
+        pad = abs(lo) * 0.05 or 0.5
+        return lo - pad, hi + pad
+    pad = 0.05 * (hi - lo)
+    return lo - pad, hi + pad
+
+
+def _bin_edges(v: NDArray[np.float64], bins: str | int) -> NDArray[np.float64]:
+    """Bin edges from a count or a numpy binning rule, clipped to a readable
+    panel range (too few bins looks sparse, too many looks noisy at panel
+    size)."""
+    edges = np.asarray(np.histogram_bin_edges(v, bins=bins), dtype=float)
+    n_bins = edges.size - 1
+    if n_bins < 4:
+        edges = np.asarray(np.histogram_bin_edges(v, bins=4), dtype=float)
+    elif n_bins > 60:
+        edges = np.asarray(np.histogram_bin_edges(v, bins=60), dtype=float)
+    return edges
+
+
+def _draw_marginal(
+    ax: Any,
+    v: NDArray[np.float64],
+    bins: str | int,
+    rng: tuple[float, float],
+    truth: float | None,
+) -> None:
+    edges = _bin_edges(v, bins)
+    ax.hist(v, bins=edges, density=True, color="0.6", edgecolor="white", linewidth=0.5)
+    if truth is not None and np.isfinite(truth):
+        ax.axvline(truth, color=_TRUTH_COLOR, linestyle="--", linewidth=1.2)
+    ax.set_xlim(rng)
+    ax.set_yticks([])
+
+
+def _draw_pair(
+    ax: Any,
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    bins: str | int,
+    x_rng: tuple[float, float],
+    y_rng: tuple[float, float],
+    truth_x: float | None,
+    truth_y: float | None,
+) -> None:
+    x_edges = _bin_edges(xv, bins)
+    y_edges = _bin_edges(yv, bins)
+    ax.hist2d(xv, yv, bins=[x_edges, y_edges], cmap="Greys")
+    if truth_x is not None and np.isfinite(truth_x):
+        ax.axvline(truth_x, color=_TRUTH_COLOR, linestyle="--", linewidth=1.2)
+    if truth_y is not None and np.isfinite(truth_y):
+        ax.axhline(truth_y, color=_TRUTH_COLOR, linestyle="--", linewidth=1.2)
+    ax.set_xlim(x_rng)
+    ax.set_ylim(y_rng)
+
+
+def _style_panel(ax: Any, row: int, col: int, k: int, names: list[str], st: Any) -> None:
+    """Shared axis cosmetics: labels only on the outer edges, thinned tick
+    counts, and the preset's box-on spine treatment."""
+    ax.xaxis.set_major_locator(MaxNLocator(nbins=_MAX_TICKS, prune="both"))
+    if col != row:
+        ax.yaxis.set_major_locator(MaxNLocator(nbins=_MAX_TICKS, prune="both"))
+    if row == k - 1:
+        ax.set_xlabel(names[col])
+        plt.setp(ax.get_xticklabels(), rotation=45, ha="right")
+    else:
+        ax.tick_params(labelbottom=False)
+    if col == 0 and row > 0:
+        ax.set_ylabel(names[row])
+    elif col != 0:
+        ax.tick_params(labelleft=False)
+    if not st.box_on:
+        ax.spines["top"].set_visible(False)
+        ax.spines["right"].set_visible(False)

quantized/calc/figure_facets.py

@@ -0,0 +1,127 @@
+"""Publication rendering for faceted (small-multiples) plots.
+
+ORIGIN_GAP_PLAN #21 (export half, faceting). Pure layer: N independently
+pre-split panels sharing scales/labels -> image bytes out. Mirrors the
+interactive facet splitter (frontend ``lib/facet.facetPayloads``): each panel
+is already the (label, x, series) data for one categorical level — this
+module only lays them out and draws them, matching ``calc.figure``'s style
+presets (``figure_styles.figure_style``) and per-series line kwargs
+(``calc.figure._plot_kwargs``).
+"""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+import matplotlib
+
+matplotlib.use("Agg")  # headless
+
+import matplotlib.pyplot as plt  # noqa: E402
+import numpy as np  # noqa: E402
+
+from quantized.calc.figure import _plot_kwargs  # noqa: E402
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+
+__all__ = ["render_facets_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+
+
+def render_facets_figure(
+    panels: list[dict[str, Any]],
+    *,
+    x_log: bool = False,
+    y_log: bool = False,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int = 200,
+) -> bytes:
+    """Render one small-multiples panel per facet level.
+
+    Each ``panels[i]`` is ``{"label": str, "x": [...], "series": [{"label":
+    str, "y": [...]}]}`` — a pre-split slice of data for one categorical
+    level (see the frontend's ``lib/facet.facetPayloads``). Panels tile into
+    as-square-as-possible rows/columns and share x/y scales (``sharex`` /
+    ``sharey``) so magnitudes stay comparable across levels; each panel
+    carries its own facet-level title, and unused trailing grid cells (when
+    the panel count isn't a perfect rows*cols rectangle) are hidden.
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if not panels:
+        raise ValueError("panels must be non-empty")
+    # Rich-text labels (GOTO #5): de-math INVALID $...$ so savefig never raises.
+    title = safe_mathtext_label(title)
+    x_label = safe_mathtext_label(x_label)
+    y_label = safe_mathtext_label(y_label)
+
+    st = figure_style(style)
+    n = len(panels)
+    cols = int(np.ceil(np.sqrt(n)))
+    rows = int(np.ceil(n / cols))
+    figsize = (
+        width_in or st.fig_width_in * cols * 0.8,
+        height_in or st.fig_height_in * rows * 0.8,
+    )
+    fallback = "DejaVu Serif" if st.font_generic == "serif" else "DejaVu Sans"
+    rc: dict[str, Any] = {
+        "font.family": st.font_generic,
+        f"font.{st.font_generic}": [st.font_name, fallback],
+        "font.size": st.font_size,
+        "axes.labelsize": st.font_size,
+        "axes.titlesize": st.font_size,
+    }
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, axes_grid = plt.subplots(
+            rows, cols, figsize=figsize, sharex=True, sharey=True, squeeze=False,
+        )
+        try:
+            flat = [ax for row in axes_grid for ax in row]
+            for i, panel in enumerate(panels):
+                ax = flat[i]
+                x = np.asarray(panel.get("x", []), dtype=float)
+                series = panel.get("series", [])
+                for si, s in enumerate(series):
+                    kw = _plot_kwargs(st.line_width, st.marker_size, None)
+                    ax.plot(
+                        x, np.asarray(s.get("y", []), dtype=float),
+                        label=safe_mathtext_label(str(s.get("label", f"s{si}"))), **kw,
+                    )
+                ax.set_title(
+                    safe_mathtext_label(str(panel.get("label", ""))), fontsize=st.font_size
+                )
+                if x_log:
+                    ax.set_xscale("log")
+                if y_log:
+                    ax.set_yscale("log")
+                if not st.box_on:
+                    ax.spines["top"].set_visible(False)
+                    ax.spines["right"].set_visible(False)
+                if st.grid_alpha > 0:
+                    ax.grid(True, alpha=st.grid_alpha)
+                if len(series) > 1:
+                    ax.legend(fontsize=max(6.0, st.legend_font_size - 2), frameon=st.legend_box)
+            for j in range(n, len(flat)):
+                flat[j].set_visible(False)
+
+            if title:
+                fig.suptitle(title)
+            if x_label:
+                fig.supxlabel(x_label)
+            if y_label:
+                fig.supylabel(y_label)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)