quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/figure_statplots.py

@@ -0,0 +1,167 @@
+"""Publication rendering for statistical plots: box / violin / Q-Q / histogram.
+
+ORIGIN_GAP_PLAN #16 (export half). Pure layer: grouped/1-D data in -> image
+bytes out. matplotlib's ``boxplot`` / ``violinplot`` compute the same stats as
+``calc.statplots`` (linear-interp quartiles + Tukey whiskers; gaussian_kde
+violins), and the Q-Q reference line + histogram binning come straight from
+``calc.statplots``, so the exported figure and the interactive stage show
+identical statistics. Shares ``render_figure``'s style presets and formats.
+"""
+
+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 numpy.typing import ArrayLike  # noqa: E402
+
+from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
+from quantized.calc.figure_styles import figure_style  # noqa: E402
+from quantized.calc.statplots import histogram as _histogram  # noqa: E402
+from quantized.calc.statplots import qq_plot as _qq_plot  # noqa: E402
+
+__all__ = ["STATPLOT_KINDS", "render_statplot_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+STATPLOT_KINDS = ("box", "violin", "qq", "probability", "histogram")
+_GROUPED = ("box", "violin")
+
+
+def _clean_groups(groups: list[ArrayLike]) -> list[np.ndarray]:
+    out = []
+    for g in groups:
+        v = np.asarray(g, dtype=float).ravel()
+        v = v[np.isfinite(v)]
+        if v.size == 0:
+            raise ValueError("every group must have at least one finite value")
+        out.append(v)
+    return out
+
+
+def render_statplot_figure(
+    kind: str,
+    data: list[ArrayLike] | ArrayLike,
+    *,
+    labels: list[str] | None = None,
+    title: str = "",
+    x_label: str = "",
+    y_label: str = "",
+    fmt: str = "pdf",
+    style: str = "default",
+    dist: str = "norm",
+    bins: str | int = "fd",
+    fit: str | None = None,
+    width_in: float | None = None,
+    height_in: float | None = None,
+    dpi: int | None = None,
+) -> bytes:
+    """Render a statistical plot to image bytes.
+
+    - ``box`` / ``violin`` — ``data`` is a list of groups; ``labels`` names them.
+    - ``qq`` / ``probability`` — ``data`` is one sample vs ``dist`` quantiles
+      with a least-squares reference line.
+    - ``histogram`` — one sample with a numpy bin rule (``bins``) and an
+      optional distribution-fit overlay (``fit``, e.g. ``"norm"``).
+
+    ``dpi`` defaults to the style preset's calibrated resolution when not
+    given (``None``), same as ``calc.figure``'s ``resolved_dpi`` convention;
+    the preset's box-tick convention (``xtick.top``/``ytick.right`` mirrored
+    when the preset draws a closed box) is honored too.
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    if kind not in STATPLOT_KINDS:
+        raise ValueError(f"kind must be one of {STATPLOT_KINDS}")
+    # 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)
+    labels = [safe_mathtext_label(str(g)) for g in labels] if labels else labels
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+    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,
+        # Mirror ticks onto the top/right spines whenever the preset draws a
+        # closed box (matches calc.figure's convention; matplotlib's default
+        # leaves top/right bare even with the full rectangular border).
+        "xtick.top": st.box_on,
+        "ytick.right": st.box_on,
+    }
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, ax = plt.subplots(figsize=figsize)
+        try:
+            _draw_statplot(ax, kind, data, labels, dist, bins, fit, st)
+            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)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def _draw_statplot(
+    ax: Any,
+    kind: str,
+    data: list[ArrayLike] | ArrayLike,
+    labels: list[str] | None,
+    dist: str,
+    bins: str | int,
+    fit: str | None,
+    st: Any,
+) -> None:
+    if kind in _GROUPED:
+        if not isinstance(data, list) or not data:
+            raise ValueError(f"{kind} needs a non-empty list of groups")
+        groups = _clean_groups(data)
+        ticks = list(range(1, len(groups) + 1))
+        if kind == "box":
+            ax.boxplot(groups, tick_labels=labels, showmeans=True)
+        else:
+            parts = ax.violinplot(groups, positions=ticks, showmeans=True, showextrema=True)
+            if labels:
+                ax.set_xticks(ticks)
+                ax.set_xticklabels(labels)
+            del parts
+        return
+
+    sample = np.asarray(data, dtype=float).ravel()
+    if kind in ("qq", "probability"):
+        q = _qq_plot(sample, dist=dist)
+        theo = np.asarray(q["theoretical_quantiles"])
+        obs = np.asarray(q["sample_quantiles"])
+        ax.scatter(theo, obs, s=12, color=st.accent if hasattr(st, "accent") else None)
+        line = q["slope"] * theo + q["intercept"]
+        ax.plot(theo, line, color="0.4", linewidth=st.line_width)
+        ax.set_xlabel(ax.get_xlabel() or f"Theoretical quantiles ({dist})")
+        ax.set_ylabel(ax.get_ylabel() or "Sample quantiles")
+        return
+
+    # histogram
+    h = _histogram(sample, bins=bins, density=fit is not None, fit=fit)
+    edges = np.asarray(h["edges"])
+    ax.hist(sample, bins=edges, density=fit is not None,
+            color="0.6", edgecolor="white", linewidth=0.5)
+    if fit is not None and "fit" in h:
+        ax.plot(h["fit"]["x"], h["fit"]["pdf"], color="0.1", linewidth=st.line_width)

quantized/calc/figure_styles.py

@@ -0,0 +1,131 @@
+"""Publication figure-style presets (ported from ``+styles/template.m``).
+
+Pure data layer: a named-template table whose parameters (font, sizes, line
+width, figure geometry, grid/box/legend) are transcribed verbatim from the
+MATLAB ``styles.template`` reference so exported figures match journal specs
+(APS, Nature, thesis, report, web, …). ``render_figure`` consumes a resolved
+``FigureStyle``; no matplotlib/fastapi imports here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["FigureStyle", "FIGURE_STYLES", "figure_style", "style_names"]
+
+_CM_PER_IN = 2.54
+
+
+@dataclass(frozen=True, slots=True)
+class FigureStyle:
+    """One named figure style. Sizes are in points (fonts/line) or cm (figure)."""
+
+    name: str
+    font_name: str
+    font_size: float  # axis tick / label size (pt)
+    title_font_size: float
+    legend_font_size: float
+    line_width: float
+    line_width_thin: float
+    marker_size: float
+    fig_width_cm: float
+    fig_height_cm: float
+    dpi: int
+    grid_alpha: float  # 0 = no grid
+    legend_box: bool
+    box_on: bool = True
+    tick_dir: str = "in"
+    legend_location: str = "best"
+
+    @property
+    def fig_width_in(self) -> float:
+        return self.fig_width_cm / _CM_PER_IN
+
+    @property
+    def fig_height_in(self) -> float:
+        return self.fig_height_cm / _CM_PER_IN
+
+    @property
+    def font_generic(self) -> str:
+        """Generic family so matplotlib falls back silently if the named font
+        (Helvetica/Arial/Times) is absent on the host."""
+        return "serif" if "times" in self.font_name.lower() else "sans-serif"
+
+
+def _t(
+    name: str,
+    font: str,
+    fs: float,
+    title_fs: float,
+    legend_fs: float,
+    lw: float,
+    lw_thin: float,
+    marker: float,
+    w_cm: float,
+    h_cm: float,
+    dpi: int,
+    *,
+    grid_alpha: float,
+    legend_box: bool,
+    box_on: bool = True,
+) -> FigureStyle:
+    return FigureStyle(
+        name=name,
+        font_name=font,
+        font_size=fs,
+        title_font_size=title_fs,
+        legend_font_size=legend_fs,
+        line_width=lw,
+        line_width_thin=lw_thin,
+        marker_size=marker,
+        fig_width_cm=w_cm,
+        fig_height_cm=h_cm,
+        dpi=dpi,
+        grid_alpha=grid_alpha,
+        legend_box=legend_box,
+        box_on=box_on,
+    )
+
+
+# Values transcribed verbatim from quantized_matlab/+styles/template.m — do not
+# "fix" them; they are calibrated journal/context specs.
+FIGURE_STYLES: dict[str, FigureStyle] = {
+    # Our interactive baseline (matches the legacy render_figure look): the
+    # renderer default when no style is requested.
+    "default": _t("default", "DejaVu Sans", 10, 11, 9, 1.2, 0.7, 5, 15.24, 10.16, 200,
+                   grid_alpha=0.25, legend_box=False),
+    "aps": _t("aps", "Helvetica", 9, 10, 8, 1.25, 0.75, 4, 8.6, 6.5, 600,
+              grid_alpha=0.0, legend_box=False),
+    "aps_double": _t("aps_double", "Helvetica", 9, 10, 8, 1.25, 0.75, 4, 17.8, 6.5, 600,
+                     grid_alpha=0.0, legend_box=False),
+    "nature": _t("nature", "Arial", 7, 8, 6, 1.0, 0.5, 3, 8.9, 6.0, 600,
+                 grid_alpha=0.0, legend_box=False),
+    "nature_double": _t("nature_double", "Arial", 7, 8, 6, 1.0, 0.5, 3, 18.3, 6.0, 600,
+                        grid_alpha=0.0, legend_box=False),
+    "thesis": _t("thesis", "Times New Roman", 11, 12, 10, 1.5, 0.75, 5, 15.0, 10.0, 300,
+                 grid_alpha=0.15, legend_box=True),
+    "presentation": _t("presentation", "Arial", 18, 20, 14, 2.5, 1.5, 8, 25.0, 18.0, 150,
+                       grid_alpha=0.2, legend_box=False),
+    "poster": _t("poster", "Arial", 24, 28, 18, 3.0, 2.0, 10, 30.0, 22.0, 150,
+                 grid_alpha=0.15, legend_box=False),
+    "report": _t("report", "Times New Roman", 10, 11, 9, 1.4, 0.7, 5, 12.0, 8.5, 300,
+                 grid_alpha=0.0, legend_box=True),
+    "web": _t("web", "Arial", 13, 15, 11, 2.0, 0.9, 6, 16.0, 10.0, 150,
+              grid_alpha=0.12, legend_box=False),
+}
+
+
+def style_names() -> list[str]:
+    """Sorted list of available style names (``default`` first)."""
+    rest = sorted(n for n in FIGURE_STYLES if n != "default")
+    return ["default", *rest]
+
+
+def figure_style(name: str) -> FigureStyle:
+    """Resolve a style by name; raises ``ValueError`` on an unknown name."""
+    try:
+        return FIGURE_STYLES[name]
+    except KeyError as exc:
+        raise ValueError(
+            f"unknown style {name!r}; available: {', '.join(style_names())}"
+        ) from exc

quantized/calc/figure_ternary.py

@@ -0,0 +1,239 @@
+"""Publication rendering for ternary diagrams (3-component compositions).
+
+ORIGIN_GAP_PLAN #23 / GAP_TIER3_PLAN item 4. Pure layer: a 2-D array of
+three-component rows (a, b, c) in fractional or percentage form -> ternary
+scatter plot in image bytes. Hand-rolled barycentric transform (no
+python-ternary dependency) on plain matplotlib axes for fast export.
+
+Rows are normalized to sum to 1 (or all three components treated as fractions):
+if rows don't sum to ~1, each is divided by its row sum; a warning is issued.
+Non-positive rows (any component < 0 after normalization, or all-zero rows)
+raise ValueError.
+
+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.
+"""
+
+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 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_ternary_figure"]
+
+_FORMATS = ("pdf", "svg", "png", "tiff")
+_FIGURE_SIZE_IN = (8, 7)  # inches: ternary is roughly square + colorbar
+
+
+def render_ternary_figure(
+    data: ArrayLike,
+    *,
+    labels: tuple[str, str, str] = ("A", "B", "C"),
+    values: ArrayLike | None = None,
+    fmt: str = "pdf",
+    style: str = "default",
+    dpi: int | None = None,
+    marker_size: float | None = None,
+    title: str = "",
+) -> bytes:
+    """Render a ternary diagram (3-component scatter plot).
+
+    ``data`` is an (n, 3) array of compositions (a, b, c) for n samples.
+    Each row is normalized so a+b+c=1 (or treated as fractions if already
+    summing to ~1). Non-positive components raise ValueError; rows not
+    summing to ~1 issue a warning and are divided by their row sum.
+
+    ``labels`` names the three corners (default: A, B, C, positioned at the
+    top, bottom-left, and bottom-right respectively). ``values`` (length n)
+    colors the scatter points by an optional fourth dimension (e.g. an
+    experimental result); if None, all points are the same color.
+
+    Ternary gridlines are drawn at 10% intervals. ``fmt``, ``style``, and
+    ``dpi`` follow ``render_figure``'s conventions: ``dpi`` defaults to the
+    preset's calibrated resolution when not given.
+
+    ``marker_size`` (default None) scales the scatter point size; None uses
+    the preset's default. ``title`` is an optional figure title.
+
+    Returns image bytes in the requested ``fmt``. Raises ``ValueError`` on
+    malformed input (wrong shape, non-positive components, bad format).
+    """
+    if fmt not in _FORMATS:
+        raise ValueError(f"fmt must be one of {_FORMATS}")
+    # Rich-text labels (GOTO #5): de-math INVALID $...$ so savefig never raises.
+    title = safe_mathtext_label(title)
+    labels = (
+        safe_mathtext_label(str(labels[0])),
+        safe_mathtext_label(str(labels[1])),
+        safe_mathtext_label(str(labels[2])),
+    )
+
+    arr = np.asarray(data, dtype=float)
+    if arr.ndim != 2 or arr.shape[1] != 3:
+        raise ValueError(
+            f"data must be an (n, 3) array of 3-component compositions, "
+            f"got shape {arr.shape}"
+        )
+    n = arr.shape[0]
+    if n < 1:
+        raise ValueError("need at least one composition row")
+
+    # Normalize: divide each row by its sum, warn if far from 1.
+    row_sums = np.sum(arr, axis=1, keepdims=True)
+    if not np.all(np.isfinite(row_sums)) or np.any(row_sums == 0):
+        raise ValueError("compositions must have finite, non-zero row sums")
+
+    # Warn if rows don't sum to ~1 (tolerance: 0.001)
+    if not np.allclose(row_sums, 1.0, rtol=0.01, atol=1e-3):
+        print("Warning: input compositions don't sum to 1.0; normalizing each row.")
+
+    normalized = arr / row_sums
+
+    # Check for any non-positive components after normalization.
+    if np.any(normalized < 0):
+        raise ValueError(
+            "all composition components must be non-negative after normalization"
+        )
+
+    if values is not None:
+        vals = np.asarray(values, dtype=float)
+        if vals.shape[0] != n:
+            raise ValueError(
+                f"values has {vals.shape[0]} entries, data has {n} rows"
+            )
+    else:
+        vals = None
+
+    st = figure_style(style)
+    resolved_dpi = int(dpi) if dpi is not None else int(st.dpi)
+    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,
+        "xtick.labelsize": st.font_size - 1,
+        "ytick.labelsize": st.font_size - 1,
+        "xtick.direction": st.tick_dir,
+        "ytick.direction": st.tick_dir,
+    }
+
+    with matplotlib.rc_context(rc):  # type: ignore[arg-type]
+        fig, ax = plt.subplots(figsize=_FIGURE_SIZE_IN)
+        try:
+            _draw_ternary_scatter(
+                ax, normalized, labels=labels, values=vals,
+                marker_size=marker_size, style=st,
+            )
+            if title:
+                fig.suptitle(title, fontsize=st.title_font_size)
+            fig.tight_layout()
+            buf = BytesIO()
+            fig.savefig(buf, format=fmt, dpi=resolved_dpi)
+            return buf.getvalue()
+        finally:
+            plt.close(fig)
+
+
+def _barycentric_to_cartesian(a: float, b: float, c: float) -> tuple[float, float]:
+    """Convert barycentric coordinates (a, b, c) summing to 1 to Cartesian (x, y).
+
+    Triangle vertices: A (top) at (0.5, √3/2), B (bottom-left) at (0, 0),
+    C (bottom-right) at (1, 0). The transformation is:
+    x = c + 0.5*a
+    y = (√3/2)*a
+    """
+    sqrt3_2 = np.sqrt(3) / 2
+    x = c + 0.5 * a
+    y = sqrt3_2 * a
+    return x, y
+
+
+def _draw_ternary_scatter(
+    ax: Any,
+    normalized: NDArray[np.float64],
+    labels: tuple[str, str, str],
+    values: NDArray[np.float64] | None,
+    marker_size: float | None,
+    style: Any,
+) -> None:
+    """Draw ternary triangle, gridlines, labels, and scatter points."""
+    # Triangle vertices: (a, b, c) = (1, 0, 0), (0, 1, 0), (0, 0, 1)
+    # Cartesian positions: A (top), B (bottom-left), C (bottom-right)
+    ax_cart, ay_cart = _barycentric_to_cartesian(1.0, 0.0, 0.0)
+    bx_cart, by_cart = _barycentric_to_cartesian(0.0, 1.0, 0.0)
+    cx_cart, cy_cart = _barycentric_to_cartesian(0.0, 0.0, 1.0)
+
+    # Draw triangle boundary
+    triangle_x = [ax_cart, bx_cart, cx_cart, ax_cart]
+    triangle_y = [ay_cart, by_cart, cy_cart, ay_cart]
+    ax.plot(triangle_x, triangle_y, "k-", linewidth=1.5)
+
+    # Draw gridlines at 10% intervals (0.1, 0.2, ..., 0.9)
+    sqrt3_2 = np.sqrt(3) / 2
+    for i in range(1, 10):
+        frac = i / 10.0
+        # Line of constant a (parallel to B-C edge, bottom)
+        a_const_x = [_barycentric_to_cartesian(frac, 1.0 - frac, 0.0)[0],
+                     _barycentric_to_cartesian(frac, 0.0, 1.0 - frac)[0]]
+        a_const_y = [_barycentric_to_cartesian(frac, 1.0 - frac, 0.0)[1],
+                     _barycentric_to_cartesian(frac, 0.0, 1.0 - frac)[1]]
+        ax.plot(a_const_x, a_const_y, "gray", linewidth=0.5, alpha=0.5)
+
+        # Line of constant b (parallel to A-C edge, right side)
+        b_const_x = [_barycentric_to_cartesian(1.0 - frac, frac, 0.0)[0],
+                     _barycentric_to_cartesian(0.0, frac, 1.0 - frac)[0]]
+        b_const_y = [_barycentric_to_cartesian(1.0 - frac, frac, 0.0)[1],
+                     _barycentric_to_cartesian(0.0, frac, 1.0 - frac)[1]]
+        ax.plot(b_const_x, b_const_y, "gray", linewidth=0.5, alpha=0.5)
+
+        # Line of constant c (parallel to A-B edge, left side)
+        c_const_x = [_barycentric_to_cartesian(1.0 - frac, 0.0, frac)[0],
+                     _barycentric_to_cartesian(0.0, 1.0 - frac, frac)[0]]
+        c_const_y = [_barycentric_to_cartesian(1.0 - frac, 0.0, frac)[1],
+                     _barycentric_to_cartesian(0.0, 1.0 - frac, frac)[1]]
+        ax.plot(c_const_x, c_const_y, "gray", linewidth=0.5, alpha=0.5)
+
+    # Plot compositions as scatter points
+    coords = [_barycentric_to_cartesian(row[0], row[1], row[2]) for row in normalized]
+    x_pts_list, y_pts_list = zip(*coords, strict=True)
+    x_pts = np.asarray(x_pts_list, dtype=float)
+    y_pts = np.asarray(y_pts_list, dtype=float)
+
+    ms = marker_size if marker_size is not None else 50
+    if values is not None:
+        scatter = ax.scatter(x_pts, y_pts, c=values, s=ms, alpha=0.7,
+                             edgecolors="black", linewidth=0.5, cmap="viridis")
+        fig = ax.get_figure()
+        fig.colorbar(scatter, ax=ax, label="Value")
+    else:
+        ax.scatter(x_pts, y_pts, s=ms, alpha=0.7, c="C0",
+                   edgecolors="black", linewidth=0.5)
+
+    # Corner labels and tick positioning
+    offset = 0.05
+    ax.text(ax_cart, ay_cart + offset, labels[0], ha="center", va="bottom",
+            fontsize=style.font_size + 2, fontweight="bold")
+    ax.text(bx_cart - offset, by_cart - offset, labels[1], ha="right", va="top",
+            fontsize=style.font_size + 2, fontweight="bold")
+    ax.text(cx_cart + offset, cy_cart - offset, labels[2], ha="left", va="top",
+            fontsize=style.font_size + 2, fontweight="bold")
+
+    # Clean up axes: no ticks, equal aspect, proper limits
+    ax.set_xlim(-0.15, 1.15)
+    ax.set_ylim(-0.15, sqrt3_2 + 0.15)
+    ax.set_aspect("equal")
+    ax.axis("off")