fluxplot 0.1.0__py3-none-any.whl

fluxplot/autotag.py

@@ -0,0 +1,164 @@
+"""Save-time promotion of labeled ordinary matplotlib artists (plan §3).
+
+A conventional labeled plot — ``ax.plot(t, y, label="Control")`` plus only ``fp.save`` — should
+yield a named series with exact data, not an anonymous ``extra.*``. This module promotes raw
+artists to series marks under strict rules:
+
+- **Identity comes only from a public artist label** the user authored (non-empty, not
+  ``_``-private). Never from color, draw order, geometry shape, linestyle or legend position.
+- **Data comes only from the artist's own exact public state** (``get_data()``,
+  ``get_offsets()``, bar patch geometry). Nothing is reconstructed or guessed.
+- **Ambiguity declines**: duplicate labels, or a label colliding with an explicitly tagged
+  series, leave every candidate in the honest ``extra.*`` fallback with one actionable warning.
+- **Explicit helpers/tags always win** — an artist already in the registry is never touched.
+
+Runs inside :func:`fluxplot.save` before gid assignment; the orphan sweep in ``tagger.py``
+still rescues whatever this module (deliberately) does not claim.
+"""
+from __future__ import annotations
+
+import warnings as _warnings
+
+import numpy as np
+
+from . import ids as _ids
+from .descriptors import Mark
+
+#: Additive manifest provenance for auto-promoted series: how identity and data were captured.
+AUTO_CAPTURE = {"identity": "artist-label", "data": "artist"}
+
+
+def is_colorbar_axes(ax) -> bool:
+    """True if this Axes is a colorbar (added by fig.colorbar), not a plot area."""
+    return getattr(ax, "_colorbar", None) is not None or ax.get_label() == "<colorbar>"
+
+
+def _public_label(artist) -> str | None:
+    """The artist's label iff it is public identity (non-empty, not ``_child0``/``_nolegend_``)."""
+    lab = artist.get_label()
+    if not isinstance(lab, str):
+        return None
+    if not lab.strip() or lab.startswith("_"):
+        return None
+    return lab
+
+
+def _finite_offsets(coll):
+    """Exact Nx2 finite offsets, or None (masked/non-finite would shift per-point indices)."""
+    off = coll.get_offsets()
+    if np.ma.isMaskedArray(off) and np.ma.is_masked(off):
+        return None
+    arr = np.asarray(off, dtype=float)
+    if arr.ndim != 2 or arr.shape[-1] != 2 or arr.size == 0 or not np.isfinite(arr).all():
+        return None
+    return arr
+
+
+def extract_xy(artist):
+    from .data import artist_xy
+    return artist_xy(artist)
+
+
+def promote_labeled(fig, reg) -> list[str]:
+    """Promote safe labeled raw artists on ``fig`` into ``reg``. Returns warning strings."""
+    from matplotlib.collections import PathCollection, PolyCollection
+    from matplotlib.container import BarContainer
+    from matplotlib.lines import Line2D
+
+    notes: list[str] = []
+    already = {id(a) for m in reg.marks for a in m.artists}
+
+    # candidates in deterministic order: per axes → lines, collections, bar containers
+    candidates: list[tuple[str, str, object]] = []  # (label, adapter, artist/container)
+    for ax in fig.axes:
+        if is_colorbar_axes(ax):
+            continue
+        for ln in ax.lines:
+            if id(ln) in already or not isinstance(ln, Line2D):
+                continue
+            lab = _public_label(ln)
+            if lab is not None:
+                candidates.append((lab, "line", ln))
+        for coll in ax.collections:
+            if id(coll) in already:
+                continue
+            lab = _public_label(coll)
+            if lab is None:
+                continue
+            if isinstance(coll, PolyCollection):
+                candidates.append((lab, "area", coll))
+            elif isinstance(coll, PathCollection):
+                candidates.append((lab, "point", coll))
+        for cont in getattr(ax, "containers", []):
+            if not isinstance(cont, BarContainer) or not cont.patches:
+                continue
+            if any(id(p) in already for p in cont.patches):
+                continue
+            lab = _public_label(cont)
+            if lab is not None:
+                candidates.append((lab, "bar", cont))
+
+    # ambiguity: duplicate candidate labels, or a label whose slug collides with an
+    # explicitly tagged series → decline ALL involved candidates (extra.* keeps them honest)
+    explicit_slugs = {_ids.series_root(m.series) for m in reg.marks if m.series is not None}
+    slug_counts: dict[str, int] = {}
+    for lab, _, _ in candidates:
+        slug = _ids.series_root(lab)
+        slug_counts[slug] = slug_counts.get(slug, 0) + 1
+    dropped = sorted(
+        {
+            lab
+            for lab, _, _ in candidates
+            if slug_counts[_ids.series_root(lab)] > 1 or _ids.series_root(lab) in explicit_slugs
+        }
+    )
+    if dropped:
+        msg = (
+            f"fluxplot: not auto-promoting artist label(s) {dropped}: each duplicates another "
+            "artist's label or an explicitly tagged series, so identity is ambiguous. The "
+            "artists stay addressable as extra.*; give them distinct labels, or use the fp.* "
+            "helpers / fp.tag(series=...) for explicit identity."
+        )
+        _warnings.warn(msg, UserWarning, stacklevel=3)
+        notes.append(msg)
+    skip = {_ids.series_root(lab) for lab in dropped}
+
+    for lab, adapter, art in candidates:
+        if _ids.series_root(lab) in skip:
+            continue
+        capture = {"capture": dict(AUTO_CAPTURE)}
+        if adapter == "line":
+            fx, fy = extract_xy(art)
+            reg.add(
+                Mark(role="line", series=lab, kind="line", x=fx, y=fy, label=lab,
+                     artists=[art], live_data=True, data=capture)
+            )
+        elif adapter == "point":
+            arr = _finite_offsets(art)
+            if arr is None:
+                msg = (
+                    f"fluxplot: not auto-promoting scatter {lab!r}: offsets are masked or "
+                    "non-finite, so per-point indices would not match the drawn points. It "
+                    "stays addressable as extra.*; use fp.scatter for explicit tagging."
+                )
+                _warnings.warn(msg, UserWarning, stacklevel=3)
+                notes.append(msg)
+                continue
+            reg.add(
+                Mark(role="point", series=lab, kind="scatter",
+                     x=[float(v) for v in arr[:, 0]], y=[float(v) for v in arr[:, 1]],
+                     label=lab, artists=[art], indexed=True, live_data=True, data=capture)
+            )
+        elif adapter == "area":
+            # exact fill geometry lives in the SVG; the original y1/y2 vectors are not
+            # recoverable from the artist, and we do not invent them
+            reg.add(Mark(role="area", series=lab, kind="area", label=lab, artists=[art], live_data=True, data=capture))
+        elif adapter == "bar":
+            from .data import bar_data
+            cx, cy, bar = bar_data(art.patches, getattr(art, "orientation", "vertical"))
+            capture["bar"] = bar
+            reg.add(
+                Mark(role="bar", series=lab, kind="bar", x=cx, y=cy, label=lab,
+                     artists=list(art.patches), indexed=True, live_data=True, data=capture)
+            )
+    return notes

fluxplot/brackets.py

@@ -0,0 +1,242 @@
+"""``fp.brackets``: significance brackets drawn from ``fp.stats`` rows, auto-stacked, with the test
+behind every star recorded in the manifest.
+
+>>> rows = fp.stats.pairwise(fp.stats.welch_hedges, {"ctl": ctl, "drug": drug, "sham": sham})
+>>> gb = fp.glowbar(data=df, x="group", y="value", ax=ax)
+>>> gb.brackets(rows)                      # or fp.brackets(ax, rows, positions=gb.positions)
+
+Each post-hoc row names its pair in ``groups``; ``positions`` maps a group name to its x. Brackets
+are placed shortest first, each one step above the data it spans and above every bracket it
+overlaps in x, so no bracket ever crosses another or sits on the points. The manifest overlay of
+each bracket carries ``stats`` — test, statistic, raw and corrected p, correction, effect size and
+its CI, sizes — so the figure states exactly which test each star came from.
+"""
+from __future__ import annotations
+
+import math
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+__all__ = ["brackets", "stars", "format_p", "THRESHOLDS"]
+
+#: the default star thresholds: ``p < 0.001`` → ``***``, ``p < 0.01`` → ``**``, ``p < 0.05`` → ``*``
+THRESHOLDS = ((0.001, "***"), (0.01, "**"), (0.05, "*"))
+
+_CORRECTION_OF = {"p_corrected_holm": "holm", "p_corrected_bh": "bh", "p-value": "none"}
+
+
+def stars(p: float, thresholds: Sequence[Tuple[float, str]] = THRESHOLDS, ns: str = "ns") -> str:
+    """The star label of a p-value: the first threshold it falls under, else ``ns``."""
+    if p is None or not math.isfinite(p):
+        return ns
+    for cut, label in sorted(thresholds, key=lambda t: t[0]):
+        if p < cut:
+            return label
+    return ns
+
+
+def format_p(p: float, floor: float = 0.001) -> str:
+    """``p < 0.001`` below ``floor``, else ``p = 0.003`` (three decimals)."""
+    if p is None or not math.isfinite(p):
+        return "p = n/a"
+    if p < floor:
+        return f"p < {floor:g}"
+    return f"p = {p:.3f}"
+
+
+def _positions_from_ticks(ax) -> Dict[str, float]:
+    return {lbl.get_text(): float(tick) for tick, lbl in zip(ax.get_xticks(), ax.get_xticklabels())
+            if lbl.get_text()}
+
+
+def _data_top(ax, x_lo: float, x_hi: float) -> Optional[float]:
+    """The highest data y drawn between ``x_lo`` and ``x_hi`` (inclusive) on ``ax``, from lines,
+    collections (offsets or path vertices) and patches — the things a bracket must clear."""
+    from matplotlib.collections import Collection
+    from matplotlib.patches import Patch
+    top = -np.inf
+
+    def take(x, y):
+        nonlocal top
+        x, y = np.asarray(x, dtype=float).ravel(), np.asarray(y, dtype=float).ravel()
+        keep = np.isfinite(x) & np.isfinite(y) & (x >= x_lo) & (x <= x_hi)
+        if keep.any():
+            top = max(top, float(y[keep].max()))
+
+    for ln in ax.lines:
+        if ln.get_transform() is ax.transData or ln.get_transform().contains_branch(ax.transData):
+            take(ln.get_xdata(orig=False), ln.get_ydata(orig=False))
+    for coll in ax.collections:
+        if not isinstance(coll, Collection):
+            continue
+        offsets = coll.get_offsets()
+        if offsets is not None and len(offsets) and coll.get_offset_transform() is ax.transData:
+            off = np.ma.filled(np.ma.asarray(offsets, dtype=float), np.nan)
+            take(off[:, 0], off[:, 1])
+        elif coll.get_transform() is ax.transData or coll.get_transform().contains_branch(ax.transData):
+            for path in coll.get_paths():
+                v = path.vertices
+                take(v[:, 0], v[:, 1])
+    for patch in ax.patches:
+        if not isinstance(patch, Patch):
+            continue
+        try:
+            v = patch.get_path().transformed(patch.get_patch_transform()).vertices
+        except Exception:  # a patch with no data-space geometry
+            continue
+        take(v[:, 0], v[:, 1])
+    return None if not np.isfinite(top) else top
+
+
+def _stats_payload(row: dict, p_column: str) -> dict:
+    lo, hi = row.get("effect_size_ci_low"), row.get("effect_size_ci_high")
+    if lo is None and isinstance(row.get("effect_size_95_CI"), str):
+        try:
+            lo, hi = (float(v) for v in row["effect_size_95_CI"].strip("[]").split(","))
+        except ValueError:
+            lo = hi = None
+    n = [row.get("n_a"), row.get("n_b")] if row.get("n_a") is not None else row.get("n_total")
+    out = {
+        "test": row.get("sig_test_used"),
+        "statistic": row.get("test_statistic_value"),
+        "p": row.get("p-value"),
+        "pCorrected": row.get(p_column),
+        "correction": _CORRECTION_OF.get(p_column, p_column),
+        "effectSizeMethod": row.get("effect_size_method"),
+        "effectSize": row.get("effect_size_value"),
+        "ciLow": lo,
+        "ciHigh": hi,
+        "n": n,
+    }
+    if row.get("dof") is not None:
+        out["dof"] = row["dof"]
+    if row.get("alternative"):
+        out["alternative"] = row["alternative"]
+    return {k: v for k, v in out.items() if v is not None}
+
+
+def brackets(ax, rows: Iterable[dict], *, positions: Optional[Dict[Any, float]] = None,
+             pairs: Optional[Iterable[Tuple[Any, Any]]] = None,
+             label: Union[str, Callable[[dict], str]] = "stars", p_column: str = "p_corrected_holm",
+             thresholds: Sequence[Tuple[float, str]] = THRESHOLDS, ns: bool = True,
+             top: Optional[float] = None, step: float = 0.06, tip: float = 0.02, **line_kw) -> list:
+    """Draw one significance bracket per ``fp.stats`` row, stacked so none overlap.
+
+    Parameters
+    ----------
+    ax
+        The axes the compared groups are plotted on.
+    rows
+        Reporting rows whose ``groups`` is the pair ``[a, b]`` (``fp.stats.pairwise``,
+        ``tukey_hsd``, ``games_howell``, ``dunn``; or any two-group row given ``names=``).
+    positions
+        ``{group name: x}``. Default: the axes' x tick labels (a glowbar / fluxbox / categorical
+        axis), which must name every group; ``GlowbarResult.positions`` and
+        ``FluxboxResult.positions`` give it directly.
+    pairs
+        Draw only these ``(a, b)`` pairs (either order), in this order of priority when several
+        rows name the same pair. Default: every row.
+    label
+        ``"stars"`` (``***``/``**``/``*``/``ns`` by ``thresholds``), ``"p"`` (``p = 0.003`` /
+        ``p < 0.001``), ``"both"`` (stars over the p), or a callable ``row -> str``.
+    p_column
+        The row column the label and the stacking read: ``"p_corrected_holm"`` (default),
+        ``"p_corrected_bh"`` or ``"p-value"``.
+    thresholds
+        ``((p, stars), …)``: the first threshold ``p`` falls under gives its label.
+    ns
+        Draw a bracket labelled ``ns`` for non-significant pairs (default). ``False`` omits them.
+    top
+        Start the stack at this y instead of above the data each bracket spans.
+    step, tip
+        Vertical step between brackets and the tip height, as fractions of the y range (on a log
+        axis, of the range in decades).
+    **line_kw
+        Passed to :func:`fluxplot.significance_bracket` (``color``, ``linewidth``, ``text_kw``, …).
+
+    Returns
+    -------
+    list
+        The bracket line artists, in drawing order (shortest span first). Each carries the
+        manifest ``stats`` payload of its row.
+    """
+    from .api import significance_bracket
+    rows = list(rows)
+    from_ticks = positions is None
+    if from_ticks:
+        positions = _positions_from_ticks(ax)
+    pos = {str(k): float(v) for k, v in positions.items()}
+    wanted = None if pairs is None else [(str(a), str(b)) for a, b in pairs]
+
+    items = []
+    for row in rows:
+        groups = row.get("groups")
+        if not groups or len(groups) != 2:
+            raise ValueError("brackets: every row needs groups=[a, b]; run the test with names=(a, b) or use fp.stats.pairwise")
+        a, b = (str(g) for g in groups)
+        if wanted is not None and (a, b) not in wanted and (b, a) not in wanted:
+            continue
+        for g in (a, b):
+            if g not in pos:
+                if from_ticks:
+                    raise ValueError(f"brackets: positions= is needed — the x tick labels do not name group {g!r}")
+                raise KeyError(f"brackets: group {g!r} has no position; positions has {sorted(pos)}")
+        if p_column not in row:
+            raise KeyError(f"brackets: rows have no {p_column!r} column (have {sorted(row)})")
+        p = row[p_column]
+        significant = p is not None and math.isfinite(p) and p < max(t for t, _ in thresholds)
+        if not significant and not ns:
+            continue
+        items.append((a, b, row, p))
+    if wanted is not None:
+        order = {pair: i for i, pair in enumerate(wanted)}
+        items.sort(key=lambda it: min(order.get((it[0], it[1]), len(order)), order.get((it[1], it[0]), len(order))))
+    # shortest span first: a long bracket then rises above the short ones it covers
+    items.sort(key=lambda it: abs(pos[it[0]] - pos[it[1]]))
+
+    log = ax.get_yscale() == "log"
+    y0, y1 = ax.get_ylim()
+    if log:
+        span = abs(math.log10(y1) - math.log10(y0)) or 1.0
+        rise = lambda y, frac: y * 10 ** (frac * span)  # noqa: E731
+    else:
+        span = abs(y1 - y0) or 1.0
+        rise = lambda y, frac: y + frac * span  # noqa: E731
+    xs = sorted(set(pos.values()))
+    half = (min(np.diff(xs)) / 2.0) if len(xs) > 1 else 0.5
+
+    placed: List[Tuple[float, float, float]] = []  # (x_lo, x_hi, y of the bracket base)
+    out = []
+    for a, b, row, p in items:
+        x_lo, x_hi = sorted((pos[a], pos[b]))
+        if top is not None:
+            base = float(top)
+        else:
+            data_top = _data_top(ax, x_lo - half, x_hi + half)
+            base = rise(data_top if data_top is not None else y0, step)
+        for px_lo, px_hi, py in placed:
+            if x_lo <= px_hi and px_lo <= x_hi:  # x-spans overlap (a shared category counts)
+                base = max(base, rise(py, step))
+        if callable(label):
+            text = str(label(row))
+        elif label == "stars":
+            text = stars(p, thresholds)
+        elif label == "p":
+            text = format_p(p)
+        elif label == "both":
+            text = f"{stars(p, thresholds)}\n{format_p(p)}"
+        else:
+            raise ValueError(f"brackets: label must be 'stars', 'p', 'both' or a callable, got {label!r}")
+        height = rise(base, tip) - base
+        br = significance_bracket(ax, x0=pos[a], x1=pos[b], y=base, label=text, between=(a, b), p=p,
+                                  name=f"{a}-{b}", height=height, stats=_stats_payload(row, p_column),
+                                  **line_kw)
+        placed.append((x_lo, x_hi, base))
+        out.append(br)
+    if out:  # make room: the top bracket must lie inside the axes
+        highest = max(rise(py, tip) for _, _, py in placed)
+        top_tip = rise(highest, step / 2)
+        if top_tip > y1:
+            ax.set_ylim(y0, top_tip)
+    return out

fluxplot/canonical_json.py

@@ -0,0 +1,23 @@
+"""Deterministic standards-compliant JSON, preserving scientific float precision.
+
+Missing observations are encoded by the data adapters, never by the serializer.
+"""
+from __future__ import annotations
+import json
+
+
+def _native(obj):
+    if isinstance(obj, dict):
+        return {str(k): _native(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_native(v) for v in obj]
+    if hasattr(obj, 'tolist'):
+        return _native(obj.tolist())
+    if isinstance(obj, float) and obj == 0:
+        return 0.0
+    return obj
+
+
+def dumps(obj) -> str:
+    return json.dumps(_native(obj), ensure_ascii=False, allow_nan=False,
+                      sort_keys=True, indent=2, separators=(',', ': ')) + '\n'

fluxplot/capture.py

@@ -0,0 +1,150 @@
+"""Capture each axis's data↔SVG-pixel mapping + scale type (spec §6).
+
+Consumers must NOT have to reconstruct matplotlib's transform. We store, per axis, explicit
+``(data, svg)`` anchor pairs plus the scale type — two anchors + scale is the complete, transform-free
+contract a morph / resize / agent needs. The conversion is the dpi-proof *fraction* method verified
+in ``NOTES_matplotlib_svg.md`` §3 (exact round-trip against emitted marker positions).
+
+Call :func:`capture_axes` AFTER ``fig.canvas.draw()`` (so layout/transforms are final) and BEFORE
+the controlled render.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def svg_viewbox(fig) -> tuple[float, float]:
+    """SVG user-space size in points — always ``figsize_inches * 72`` regardless of dpi."""
+    return fig.get_figwidth() * 72.0, fig.get_figheight() * 72.0
+
+
+def data_to_svg(ax, fig, x: float, y: float) -> tuple[float, float]:
+    """Map a data point to SVG user-space coordinates (origin top-left, points)."""
+    disp = ax.transData.transform((x, y))
+    w_px, h_px = fig.bbox.width, fig.bbox.height
+    vbw, vbh = svg_viewbox(fig)
+    sx = disp[0] / w_px * vbw
+    sy = (1.0 - disp[1] / h_px) * vbh
+    return float(sx), float(sy)
+
+
+def _log_base(axis) -> float:
+    try:
+        return float(axis.get_transform().base)
+    except Exception:
+        return 10.0
+
+
+def tick_kinds(axis):
+    """Portable names for an axis' major tick locator and formatter classes: the consumer that
+    re-ticks a view (or redraws a colour key) picks the matching scheme."""
+    from matplotlib import ticker
+    loc, fmt = axis.get_major_locator(), axis.get_major_formatter()
+    if isinstance(loc, ticker.LogLocator):
+        locator = 'log'
+    elif isinstance(loc, ticker.FixedLocator):
+        locator = 'fixed'
+    elif isinstance(loc, ticker.MultipleLocator):
+        locator = 'multiple'
+    elif type(loc).__module__ == 'matplotlib.dates':
+        locator = 'date'
+    elif type(loc).__module__ == 'matplotlib.category':
+        locator = 'category'
+    else:
+        locator = 'auto'
+    if isinstance(fmt, ticker.LogFormatter):
+        formatter = 'log'
+    elif isinstance(fmt, ticker.PercentFormatter):
+        formatter = 'percent'
+    elif isinstance(fmt, ticker.ScalarFormatter):
+        formatter = 'sci' if fmt.get_offset() else 'plain'
+    elif isinstance(fmt, ticker.FixedFormatter):
+        formatter = 'fixed'
+    elif type(fmt).__module__ == 'matplotlib.dates':
+        formatter = 'date'
+    elif type(fmt).__module__ == 'matplotlib.category':
+        formatter = 'category'
+    else:
+        formatter = 'custom'
+    return locator, formatter
+
+
+def _axis_capture(ax, fig, which: str) -> dict:
+    if which == "x":
+        scale = ax.get_xscale()
+        lo, hi = ax.get_xlim()
+        label = ax.get_xlabel()
+        y_ref = ax.get_ylim()[0]
+        endpoints = [(lo, y_ref), (hi, y_ref)]
+        mpl_axis = ax.xaxis
+    else:
+        scale = ax.get_yscale()
+        lo, hi = ax.get_ylim()
+        label = ax.get_ylabel()
+        x_ref = ax.get_xlim()[0]
+        endpoints = [(x_ref, lo), (x_ref, hi)]
+        mpl_axis = ax.yaxis
+
+    out: dict = {
+        "scale": scale,
+        "label": label,
+        "domain": [float(lo), float(hi)],
+        "anchors": [],
+    }
+    if scale == "log":
+        out["base"] = _log_base(mpl_axis)
+
+    supported = getattr(ax, "name", "rectilinear") == "rectilinear" and scale in ("linear", "log")
+    out["supported"] = supported
+    out["tickLocator"], out["tickFormatter"] = tick_kinds(mpl_axis)
+    out["ticks"] = [{"value": float(v), "label": t.get_text()}
+                    for v, t in zip(mpl_axis.get_ticklocs(), mpl_axis.get_ticklabels()) if np.isfinite(v)]
+    converter = getattr(mpl_axis, "get_converter", lambda: getattr(mpl_axis, "converter", None))()
+    module = type(converter).__module__ if converter else ""
+    if module == "matplotlib.dates":
+        from matplotlib.dates import get_epoch
+        out["units"] = {"kind": "date", "epoch": get_epoch(), "unit": "day"}
+    elif module == "matplotlib.category":
+        out["units"] = {"kind": "category"}
+    for (dx, dy), data_val in zip(endpoints, (lo, hi)):
+        if not supported:
+            break
+        sx, sy = data_to_svg(ax, fig, dx, dy)
+        out["anchors"].append({"data": float(data_val), "svg": sx if which == "x" else sy})
+    return out
+
+
+def capture_axes(ax, fig, twins=()) -> dict:
+    """Return ``{"x": {...}, "y": {...}, "pixelBox": {...}}`` for one Axes — plus ``"y2"`` /
+    ``"x2"`` for each twin axes (``[(axes, "y2" | "x2")]``) sharing its frame."""
+    # plot-area rectangle in SVG coords (convenience; the SVG clipPath stays authoritative).
+    vbw, vbh = svg_viewbox(fig)
+    box = ax.get_window_extent()
+    sx0, sx1 = box.x0 / fig.bbox.width * vbw, box.x1 / fig.bbox.width * vbw
+    sy0, sy1 = (1 - box.y1 / fig.bbox.height) * vbh, (1 - box.y0 / fig.bbox.height) * vbh
+    out = {
+        "projection": getattr(ax, "name", "rectilinear"),
+        "x": _axis_capture(ax, fig, "x"),
+        "y": _axis_capture(ax, fig, "y"),
+        "pixelBox": {
+            "x0": min(sx0, sx1),
+            "y0": min(sy0, sy1),
+            "x1": max(sx0, sx1),
+            "y1": max(sy0, sy1),
+        },
+    }
+    for twin, which in twins:
+        if which not in out:  # the first twin of each kind; a third value axis has no slot
+            out[which] = _axis_capture(twin, fig, "y" if which == "y2" else "x")
+            functions = getattr(twin, "_functions", None)
+            if functions is not None and callable(functions[0]):
+                # a secondary axis: the parent → secondary transform as samples across the parent's range
+                lo, hi = (ax.get_xlim() if which == "x2" else ax.get_ylim())
+                grid = np.linspace(lo, hi, 9)
+                try:
+                    mapped = np.asarray(functions[0](grid), dtype=float)
+                    out[which]["secondary"] = {"of": "x" if which == "x2" else "y",
+                                               "samples": [[float(a), float(b)] for a, b in zip(grid, mapped) if np.isfinite(b)]}
+                except Exception:  # a transform that rejects the grid: the axis stays, unsampled
+                    out[which]["secondary"] = {"of": "x" if which == "x2" else "y", "samples": []}
+    return out