scistackplot 0.1.36__tar.gz → 0.1.38__tar.gz

{scistackplot-0.1.36 → scistackplot-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.36
+Version: 0.1.38
 Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
 Author: SciStack Contributors
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.21
 Requires-Dist: pandas>=1.5
-Requires-Dist: scistacklog==0.1.36
+Requires-Dist: scistacklog==0.1.38
 Provides-Extra: dev
 Requires-Dist: matplotlib>=3.6; extra == 'dev'
 Requires-Dist: plotly>=5.0; extra == 'dev'

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/aliases.py

@@ -156,11 +156,21 @@ class DisplayText:
         """A panel's facet values, the way ``Panel.title`` joins them."""
         return " · ".join(self.level(factor, value) for factor, value in key.items())
 
-    def figure_title(self, key: dict[str, Any]) -> str:
-        """An ITERATE figure's ``name=value`` title."""
+    def figure_title(self, key: dict[str, Any], table: "LongTable | None" = None) -> str:
+        """An ITERATE figure's ``name=value`` title.
+
+        **A variant factor with ONE level is left out** (user, 2026-10-15):
+        one series needs no name in the title, and the legend/Variants row
+        already says which variant it is — ``Variant=CosmedData · load_cbrace
+        v2`` over a figure that could not be anything else is noise. Only the
+        TITLE: ``figure_key`` keeps the entry, because save-all file names and
+        the endpoint's ``for_each`` keys are built from it. A single-level
+        schema key (``subject=03``) stays — it says which figure this is.
+        """
         return ", ".join(
             f"{self.name(factor, factor)}={self.level(factor, value)}"
             for factor, value in key.items()
+            if not _lone_variant(table, factor)
         )
 
     def x_plan(self, plan):
@@ -208,6 +218,15 @@ def _raw(value: Any) -> str:
 # ---------------------------------------------------------------------------
 
 
+def _lone_variant(table: LongTable | None, factor: str) -> bool:
+    """A variant factor (``Variant``, ``Code:*``) holding a single level —
+    the rule :meth:`DisplayText.figure_title` leaves out of a title."""
+    if table is None or not table.has_factor(factor):
+        return False
+    info = table.factor(factor)
+    return bool(info.is_variant) and len(info.levels) == 1
+
+
 def display_text(spec: PlotSpec, table: LongTable) -> DisplayText:
     """The plot's aliases over the project's, for ``table``'s factors.
 

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/capability.py

@@ -717,8 +717,10 @@ def variant_summary(spec: PlotSpec, table: LongTable) -> dict:
     import pandas as pd
 
     from .variants import (
+        VariantSet,
         auto_label,
         defined_sets,
+        effective_selection,
         is_stated,
         label_variable,
         resolve_selection,
@@ -731,9 +733,14 @@ def variant_summary(spec: PlotSpec, table: LongTable) -> dict:
     names = [f.name for f in table.variant_factors if f.name in frame.columns]
 
     sets = []
-    # With nothing selected — no rows, or none filled in yet — every row is on
-    # screen, which is what the figure is showing too.
-    kept_mask = pd.Series(not defined_sets(spec.variant_sets), index=frame.index)
+    # With nothing selected — no rows, or none filled in yet — the figure draws
+    # what an EMPTY row selects (the source default: current code), so that is
+    # what is "on screen" here too. Measured by the same owner, `row_mask`.
+    kept_mask = (
+        row_mask(table, spec, VariantSet())
+        if not defined_sets(spec.variant_sets)
+        else pd.Series(False, index=frame.index)
+    )
     claimed = pd.Series(False, index=frame.index)
     for index, variant in enumerate(spec.variant_sets):
         # "Says something", which row 0 always does — it is the figure's
@@ -743,9 +750,7 @@ def variant_summary(spec: PlotSpec, table: LongTable) -> dict:
         # and folds to nothing, because one series needs no factor.
         defined = is_stated(variant, index)
         if defined:
-            mask = row_mask(
-                frame, spec, variant, latest_column=table.latest_column
-            )
+            mask = row_mask(table, spec, variant)
             # First-match-wins, mirroring apply_variant_sets: the count shown
             # must be the number of rows this variant contributes to the figure,
             # not the number it would match on its own.
@@ -772,8 +777,13 @@ def variant_summary(spec: PlotSpec, table: LongTable) -> dict:
                     index=index,
                     variable=label_variable(variant, index, spec.y_measure),
                     latest_column=table.latest_column,
+                    frozen=None if variant.follow_latest else variant.frozen,
                 ),
                 "explicit_name": variant.name,
+                # A reopened saved plot's versions, and whether the row follows
+                # latest instead (docs/claude/variant-row-selection.md).
+                "frozen": {c: list(v) for c, v in variant.frozen.items()},
+                "follow_latest": variant.follow_latest,
                 "selection": dict(variant.selection),
                 # None means the primary measure; the GUI shows that as the
                 # dropdown's default rather than inventing a name for it.
@@ -784,7 +794,9 @@ def variant_summary(spec: PlotSpec, table: LongTable) -> dict:
                 # per row because that is where the fix is (pin a version, or
                 # split the row), and because the column itself is no longer
                 # offered as a factor.
-                "spans": spanned_code_axes(frame[fresh], variant.selection, table)
+                "spans": spanned_code_axes(
+                    frame[fresh], effective_selection(variant, table), table
+                )
                 if defined
                 else {},
                 # What this selection actually resolved to, and — when it
@@ -803,7 +815,9 @@ def variant_summary(spec: PlotSpec, table: LongTable) -> dict:
                 # I get" is nothing.
                 "resolved": _jsonable_selection(
                     resolve_selection(
-                        frame, variant.selection, latest_column=table.latest_column
+                        frame,
+                        effective_selection(variant, table),
+                        latest_column=table.latest_column,
                     )
                 )
                 if defined

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/codegen.py

@@ -2855,7 +2855,20 @@ def _script_inputs(spec: PlotSpec) -> tuple[str, list[str]]:
             )
         else:
             lines.append(f"{param} = df")
-        for column, value in variant.selection.items():
+        selection = dict(variant.selection)
+        if variant.frozen and not variant.follow_latest:
+            # A reopened saved plot's versions (variants.frozen_mask). The
+            # frozen columns replace the row's own keys for them; several
+            # ordinals export as "any of" — the per-location "highest of"
+            # needs provenance a flat table does not carry.
+            selection.update(
+                {
+                    column: levels[0] if len(levels) == 1 else list(levels)
+                    for column, levels in variant.frozen.items()
+                    if levels
+                }
+            )
+        for column, value in selection.items():
             if isinstance(value, str) and value == LATEST:
                 lines.append(
                     f"# NOTE: {column!r} asked for the latest version, which "

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/reduce.py

@@ -2776,7 +2776,7 @@ def _labels_for(
 
     title = style.title
     if title is None and figure_key:
-        title = text.figure_title(figure_key)
+        title = text.figure_title(figure_key, table)
 
     def named(factor: str) -> str:
         return text.name(factor, table.factor(factor).display)

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/render/mpl.py

@@ -9,6 +9,9 @@ expected to reproduce.
 
 from __future__ import annotations
 
+import threading
+import time
+from contextlib import contextmanager
 from dataclasses import dataclass, field, replace
 from typing import Any
 
@@ -72,9 +75,48 @@ from .base import (
 
 LAYER = "scistackplot"
 
+#: One matplotlib figure at a time, process-wide. The GUI answers every RPC
+#: on its own thread, and a render sets text sizes through ``rc_context`` —
+#: GLOBAL rcParams, saved on entry and restored on exit — so two renders
+#: overlapping (a pane resize while the previous resolve still lays out;
+#: scidb.log 2026-10-15 12:23:50, three at once) read each other's sizes and
+#: the last to exit can leave the wrong ones behind. Re-entrant: a layout
+#: decision settles the auto text size, whose trials render.
+_MPL_LOCK = threading.RLock()
+
+#: A wait for the lock longer than this is logged (INFO): a slow figure is
+#: then told apart from a figure queued behind another one.
+_LOCK_WAIT_LOG_S = 0.25
+
+
+@contextmanager
+def _one_figure_at_a_time(what: str):
+    t0 = time.perf_counter()
+    with _MPL_LOCK:
+        waited = time.perf_counter() - t0
+        if waited > _LOCK_WAIT_LOG_S:
+            Log.info(
+                "%s waited %.2fs for another figure's matplotlib layout to finish "
+                "(matplotlib lays out one figure at a time)",
+                what,
+                waited,
+                layer=LAYER,
+            )
+        yield
+
+
+def _artist_count(fig) -> int:
+    """Every artist a layout pass walks: each axes' children, the figure's own."""
+    return len(fig.get_children()) + sum(len(ax.get_children()) for ax in fig.axes)
+
 
 def render(resolved: ResolvedPlot):
     """Draw ``resolved`` and return the Figure (caller owns closing it)."""
+    with _one_figure_at_a_time(f"render_mpl({resolved.kind})"):
+        return _render(resolved)
+
+
+def _render(resolved: ResolvedPlot):
     import matplotlib
 
     if matplotlib.get_backend().lower() not in ("agg", "template"):
@@ -88,7 +130,18 @@ def render(resolved: ResolvedPlot):
     # An auto text size is chosen before anything is drawn (autosize owns
     # it; a trial layout arrives here already settled, so this never recurses).
     resolved = settle(resolved)
-    with Log.timer("render_mpl", layer=LAYER, extra=str(resolved.kind)):
+    with Log.timer("render_mpl", layer=LAYER, extra=str(resolved.kind)) as timer:
+        # Consecutive laps rather than nested phases: the body is one long
+        # sequence, and which pass of it is slow is the question a slow
+        # figure asks (scidb.log 2026-10-15: 6.6 s with no breakdown).
+        mark = time.perf_counter()
+
+        def lap(name: str) -> None:
+            nonlocal mark
+            now = time.perf_counter()
+            timer.phases.append((name, now - mark))
+            mark = now
+
         style = resolved.spec.style
         # rc_context, not rcParams: text reads the size at CREATION, so this
         # has to be open while every label, tick and legend entry is made —
@@ -129,7 +182,12 @@ def render(resolved: ResolvedPlot):
                 # panel was drawn last.
                 sharey=shares_y_axis(resolved),
             )
+            lap("subplots")
 
+            # Marks and overlay alternate per panel: summed apart, so the
+            # overlay's share is its own phase.
+            marks_s = sample_s = 0.0
+            sample_runs_drawn = sample_artists = 0
             used: set[tuple[int, int]] = set()
             # (row, col) -> panel, so the cosmetics pass can ask a CELL for its
             # panel's limits. It walks the grid rather than the panel list (blank
@@ -160,16 +218,25 @@ def render(resolved: ResolvedPlot):
                 used.add((row, col))
                 at_cell[(row, col)] = panel
                 panel_axes[index] = ax
+                t0 = time.perf_counter()
                 if resolved.custom is not None:
                     # The user's plot_ function draws this panel's marks; the
                     # layout around them is this renderer's (custom.py).
                     resolved.custom.draw_panel(ax, panel, resolved)
                 else:
                     _draw_panel(ax, panel.frame, resolved)
-                _draw_sample(ax, panel, resolved)
+                t1 = time.perf_counter()
+                runs, drawn = _draw_sample(ax, panel, resolved)
+                sample_runs_drawn += runs
+                sample_artists += drawn
+                marks_s += t1 - t0
+                sample_s += time.perf_counter() - t1
                 # No subplot caption: a faceted panel is named by its y-axis title
                 # instead (base.panel_y_title), which buys back the row of vertical
                 # space a title costs in every row of the grid.
+            timer.phases.append(("marks", marks_s))
+            timer.phases.append(("sample_overlay", sample_s))
+            mark = time.perf_counter()
 
             # Blank out grid cells no panel landed in (a wrapped grid's remainder).
             for row in range(n_rows):
@@ -178,6 +245,21 @@ def render(resolved: ResolvedPlot):
                         axes[row][col].set_visible(False)
 
             _apply_axes_cosmetics(fig, axes, resolved, n_rows, n_cols, at_cell)
+            lap("cosmetics")
+            # What every layout pass below walks. Thousands here is the cause
+            # of a slow figure, whatever the row count says (the overlay drew
+            # one artist per run until 2026-10-15).
+            Log.info(
+                "drew %d artist(s) over %d panel(s)%s",
+                _artist_count(fig),
+                len(resolved.panels),
+                (
+                    f"; sample overlay {sample_runs_drawn} run(s) as {sample_artists} artist(s)"
+                    if sample_runs_drawn
+                    else ""
+                ),
+                layer=LAYER,
+            )
 
             if resolved.labels.title:
                 fig.suptitle(resolved.labels.title)
@@ -204,13 +286,16 @@ def render(resolved: ResolvedPlot):
                     rect = _arrange(fig, labelled, resolved, legend)
                     fig.tight_layout(rect=rect)
             setattr(fig, LEGEND_ATTR, legend.describe() if legend is not None else None)
+            lap("legend_and_layout")
             # After a layout pass: the room each label has is the laid-out
             # panel width (spec/images/graph1.png, graph2.png).
             _fit_x_labels(fig, [ax for _, _, ax in labelled], resolved, rect)
+            lap("x_labels")
             # Difference bars need the laid-out panel heights (their sizes are
             # points), so they come after every other layout pass, and before
             # the reach is measured (a raised top can widen the tick numbers).
             _draw_difference_bars(fig, panel_axes, resolved, rect)
+            lap("difference_bars")
             # Last, on the final layout: what the preview sizes its margins
             # and cell gaps from. Hidden y titles are named next to it, so a
             # gap that did not shrink can be explained from scidb.log (the
@@ -223,7 +308,9 @@ def render(resolved: ResolvedPlot):
             if hidden:
                 Log.debug("y titles hidden: %s", "; ".join(hidden), layer=LAYER)
             setattr(fig, GRID_REACH_ATTR, _grid_reach(fig, axes, n_rows, n_cols))
+            lap("grid_reach")
             setattr(fig, AXIS_TEXT_ATTR, _axis_text(fig, axes, n_rows, n_cols, resolved))
+            lap("axis_text")
             return fig
 
 
@@ -491,7 +578,7 @@ def _draw_distribution(ax, frame, resolved, *, violin: bool) -> None:
     ax.set_xticklabels([resolved.text.x_tick(v) for v in order])
 
 
-def _draw_sample(ax, panel, resolved: ResolvedPlot) -> None:
+def _draw_sample(ax, panel, resolved: ResolvedPlot) -> tuple[int, int]:
     """The "Show sample" overlay: one point per row of ``panel.sample`` inside
     the mark it belongs to, joined into a line per identity when
     ``ResolvedPlot.sample_join`` says so.
@@ -503,18 +590,36 @@ def _draw_sample(ax, panel, resolved: ResolvedPlot) -> None:
     (``ResolvedPlot.sample_color``, the legend lists the levels —
     ``_sample_legend_handles``), or each point its mark's, with a line that
     crosses mark colours drawn neutral under points painted one by one.
-    Drawn after the marks, on top.
+    Drawn after the marks, on top. Joined runs are one line each; lone
+    points are one scatter per colour per panel. Returns ``(runs, artists)``
+    for the render's log line.
     """
     sample = getattr(panel, "sample", None)
     if sample is None or sample.empty or sample_dropped_reason(panel, resolved):
-        return
+        return 0, 0
     weight = sample_weight(resolved.spec.style)
-    for run in sample_runs(sample, resolved):
+    runs = sample_runs(sample, resolved)
+    # Lone points (a points-only overlay, or a one-point run of a joined
+    # one) gathered per colour and drawn as ONE scatter each, after the
+    # lines: one artist per run made a figure whose innermost tick is a
+    # between-subject factor (group) draw ~1400 scatters, and every layout
+    # pass walks every artist — 6.6 s per render, 46 s with the auto text
+    # size's trials (scidb.log 2026-10-15 12:21). Same points, same paint.
+    lone: dict[str, tuple[list[float], list[float]]] = {}
+    artists = 0
+    for run in runs:
         positions = sample_positions(run.rows, resolved, run.identity)
         order = np.argsort(positions, kind="stable")
         values = run.rows[resolved.encoding.y].to_numpy(dtype=float)[order]
         joined = resolved.sample_join and len(run.rows) > 1
-        if joined and run.uniform:
+        if not joined:
+            for x, y, i in zip(positions[order], values, order):
+                xs, ys = lone.setdefault(run.point_colors[i], ([], []))
+                xs.append(float(x))
+                ys.append(float(y))
+            continue
+        artists += 2 if not run.uniform else 1
+        if run.uniform:
             ax.plot(
                 positions[order],
                 values,
@@ -528,18 +633,17 @@ def _draw_sample(ax, panel, resolved: ResolvedPlot) -> None:
                 zorder=3,
             )
             continue
-        if joined:
-            # The points sit on marks of different colours: the line (the
-            # run, zorder 3) in the neutral colour, the points on top of it
-            # each in its own mark's colour (gid: part of the line's run).
-            ax.plot(
-                positions[order],
-                values,
-                color=run.line_color,
-                alpha=SAMPLE_ALPHA,
-                linewidth=weight.line_pt,
-                zorder=3,
-            )
+        # The points sit on marks of different colours: the line (the
+        # run, zorder 3) in the neutral colour, the points on top of it
+        # each in its own mark's colour (gid: part of the line's run).
+        ax.plot(
+            positions[order],
+            values,
+            color=run.line_color,
+            alpha=SAMPLE_ALPHA,
+            linewidth=weight.line_pt,
+            zorder=3,
+        )
         ax.scatter(
             positions[order],
             values,
@@ -548,10 +652,23 @@ def _draw_sample(ax, panel, resolved: ResolvedPlot) -> None:
             alpha=SAMPLE_ALPHA,
             edgecolors=SAMPLE_EDGE_COLOR,
             linewidths=0.5,
-            zorder=3.1 if joined else 3,
-            gid=SAMPLE_LINE_POINTS_GID if joined else None,
+            zorder=3.1,
+            gid=SAMPLE_LINE_POINTS_GID,
         )
+    for color, (xs, ys) in lone.items():
+        ax.scatter(
+            xs,
+            ys,
+            s=weight.marker_area,
+            color=color,
+            alpha=SAMPLE_ALPHA,
+            edgecolors=SAMPLE_EDGE_COLOR,
+            linewidths=0.5,
+            zorder=3,
+        )
+    artists += len(lone)
     _sample_legend_handles(ax, resolved)
+    return len(runs), artists
 
 
 def _sample_legend_handles(ax, resolved: ResolvedPlot) -> None:
@@ -1791,7 +1908,9 @@ def layout_decisions(
     style = resolved.spec.style
     width = float(width_in or style.width)
     height = float(height_in or style.height)
-    with Log.timer("layout_decisions", layer=LAYER, extra=f"{width:.2f}x{height:.2f}in"):
+    with _one_figure_at_a_time("layout_decisions"), Log.timer(
+        "layout_decisions", layer=LAYER, extra=f"{width:.2f}x{height:.2f}in"
+    ):
         # Auto text is chosen at the size being decided (the pane's, in Fit
         # pane), keyed on the caller's object so the preview's later
         # render_plotly and a Save of the same resolve reuse it.
@@ -1830,6 +1949,11 @@ def layout_report(resolved: ResolvedPlot):
     measurements the auto text size judges a reference by. Renders, reads
     what the export already records on the figure, measures the drawn tick
     labels and y titles, closes it."""
+    with _one_figure_at_a_time("layout_report"):
+        return _layout_report(resolved)
+
+
+def _layout_report(resolved: ResolvedPlot):
     import matplotlib.pyplot as plt
 
     from ..autosize import LayoutReport

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/render/plotly_.py

@@ -698,7 +698,14 @@ def _sample_traces(
     listed = overlay_in_legend(resolved.spec, resolved.sample_color)
     weight = sample_weight(resolved.spec.style)
     traces: list[dict] = []
-    for run in sample_runs(sample, resolved):
+    # Lone points (not joined: a points-only overlay, or a one-point run)
+    # of one legend group and colour share ONE markers trace — one trace per
+    # run was ~1400 traces when the innermost tick is a between-subject
+    # factor (scidb.log 2026-10-15), each one an SVG group in the browser.
+    # Same points, same legend group (hiding a level still hides them).
+    lone: dict[tuple[str, str], dict] = {}
+    runs = sample_runs(sample, resolved)
+    for run in runs:
         level, rows, identity = run.level, run.rows, run.identity
         # The overlay's own colour key when it has one, else the mark's
         # colour — none when the run crosses the marks' colours.
@@ -714,22 +721,36 @@ def _sample_traces(
         levels = [
             str(v).replace(LEAF_SEPARATOR, " · ") for v in rows[resolved.encoding.x].to_numpy()
         ]
+        xs = [None if np.isnan(v) else float(v) for v in positions[order]]
+        ys = _values(rows[resolved.encoding.y].iloc[order])
+        custom = [f"{levels[i]}<br>{hover[i]}" if hover[i] else levels[i] for i in order]
+        name = label if own_color else (str(identity) if identity is not None else label)
+        joined_run = resolved.sample_join and len(rows) > 1
+        batch = lone.get((legend_group, run.line_color)) if not joined_run and run.uniform else None
+        if batch is not None:
+            batch["x"].extend(xs)
+            batch["y"].extend(ys)
+            batch["customdata"].extend(custom)
+            if batch["name"] != name:
+                # Several identities in one trace: name the trace by its level.
+                batch["name"] = label
+            continue
         show_legend = listed and legend_on and legend_group not in seen
         if show_legend:
             seen.add(legend_group)
         traces.append(
             {
                 "type": "scatter",
-                "mode": "lines+markers" if resolved.sample_join and len(rows) > 1 else "markers",
-                "name": label if own_color else (str(identity) if identity is not None else label),
+                "mode": "lines+markers" if joined_run else "markers",
+                "name": name,
                 "legendgroup": legend_group,
                 "showlegend": show_legend,
                 # After every mark entry whatever panel first drew it.
                 "legendrank": 2000,
                 "xaxis": x_axis,
                 "yaxis": y_axis,
-                "x": [None if np.isnan(v) else float(v) for v in positions[order]],
-                "y": _values(rows[resolved.encoding.y].iloc[order]),
+                "x": xs,
+                "y": ys,
                 "marker": {
                     # One colour, or each point its own mark's when the
                     # run crosses the marks' colours (base.sample_runs).
@@ -742,23 +763,24 @@ def _sample_traces(
                 "line": {"color": run.line_color, "width": weight.line_pt},
                 "opacity": SAMPLE_ALPHA,
                 # Hover-only (see `_level_hover` on why not `text`).
-                "customdata": [
-                    f"{levels[i]}<br>{hover[i]}" if hover[i] else levels[i] for i in order
-                ],
+                "customdata": custom,
                 "hovertemplate": "%{customdata}<br>%{y}<extra>" + label + "</extra>",
             }
         )
+        if not joined_run and run.uniform:
+            lone[(legend_group, run.line_color)] = traces[-1]
     # The one line that tells "no lines" apart: joined runs vs one-point runs
     # (a run is one identity inside one bracket — base.sample_runs — never
     # split by the marks' colour), and what decided the join.
     joined = sum(1 for t in traces if t["mode"] == "lines+markers")
     Log.debug(
-        "sample overlay panel %s: %d run(s), %d joined, %d single-point; "
+        "sample overlay panel %s: %d run(s) as %d trace(s), %d joined, %d single-point; "
         "join=%s (%s), own colour=%r, mark colour=%r",
         panel.title or "unfaceted",
+        len(runs),
         len(traces),
         joined,
-        sum(1 for t in traces if len(t["x"]) == 1),
+        sum(1 for run in runs if len(run.rows) == 1),
         resolved.sample_join,
         resolved.sample_join_reason,
         resolved.sample_color,

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/spec.py

@@ -776,13 +776,36 @@ class VariantSet:
     #: would claim every ``Force`` row too, drawing it once per variant. Naming
     #: the variable makes "not applicable here" and "stale" distinguishable.
     variable: str | None = None
+    #: Code versions this row is FROZEN to: ``{"Code:fn": ["v1", ...]}``. Per
+    #: schema location the row keeps the highest of these ordinals, so a save
+    #: spanning v1/v2 across locations reopens exactly as drawn.
+    #:
+    #: Filled in by ``scistackplotdb.saved`` when a saved plot is reopened,
+    #: translated from the function HASHES stored at save time (ordinals
+    #: renumber after a real delete; hashes do not). Plain data so this
+    #: package stays scidb-free. A frozen column overrides the row's own
+    #: selection key for that column and its latest flag — "current" AND
+    #: "v1" would select nothing. See docs/claude/variant-row-selection.md.
+    frozen: dict[str, list[str]] = field(default_factory=dict)
+    #: True: this row always draws the current code and a saved plot never
+    #: freezes it. Set by answering "switch to latest" when a saved plot finds
+    #: newer data (``scistackplotdb.saved.follow_latest_saved_plot``).
+    follow_latest: bool = False
 
     def to_dict(self) -> dict:
-        return {
+        out = {
             "name": self.name,
             "selection": dict(self.selection),
             "variable": self.variable,
         }
+        # Written only when set, so the common row (and every generated
+        # docstring, plan-cache diff and stored spec that holds one) reads
+        # exactly as it did before these existed.
+        if self.frozen:
+            out["frozen"] = {column: list(levels) for column, levels in self.frozen.items()}
+        if self.follow_latest:
+            out["follow_latest"] = True
+        return out
 
     @classmethod
     def from_dict(cls, raw: dict) -> "VariantSet":
@@ -790,6 +813,11 @@ class VariantSet:
             name=raw.get("name"),
             selection=dict(raw.get("selection") or {}),
             variable=raw.get("variable"),
+            frozen={
+                str(column): [str(level) for level in (levels or [])]
+                for column, levels in (raw.get("frozen") or {}).items()
+            },
+            follow_latest=bool(raw.get("follow_latest", False)),
         )
 
 

{scistackplot-0.1.36 → scistackplot-0.1.38}/src/scistackplot/variants.py

@@ -289,22 +289,208 @@ def variant_set_mask(
     return mask
 
 
-def row_mask(
+#: Where a row's effective selection came from — the third field of every
+#: ``log_effective_selections`` entry, so a log reader can tell "the user said
+#: this" from "nothing was said, so the source's current records".
+SOURCE_STATED = "stated"
+SOURCE_DEFAULT = "source default"
+SOURCE_FROZEN = "frozen"
+
+
+def _names_function_choice(selection: dict[str, Any], latest_column: str | None) -> bool:
+    """Whether a selection already says which CODE to draw: a code/run axis,
+    or the source's latest flag."""
+    return any(
+        is_function_axis(key) or (latest_column is not None and key == latest_column)
+        for key in selection
+    )
+
+
+def active_frozen(variant: VariantSet, table: LongTable) -> dict[str, list[str]]:
+    """The row's frozen columns that this table can apply.
+
+    ``follow_latest`` wins over a freeze: the user asked for current code.
+    A frozen column the frame does not carry (the function is back to one
+    version, so there is no axis) is ignored — there is nothing to choose
+    between, and ``scistackplotdb.saved`` only writes columns that exist.
+    """
+    if variant.follow_latest or not variant.frozen:
+        return {}
+    columns = table.frame.columns
+    return {
+        column: list(levels)
+        for column, levels in variant.frozen.items()
+        if column in columns and levels
+    }
+
+
+def effective_selection_with_source(
+    variant: VariantSet, table: LongTable
+) -> tuple[dict[str, Any], str]:
+    """``(selection, source)`` — what this row's selection really is.
+
+    The single answer to "which code does a row draw?", consumed by
+    :func:`row_mask` (and so by the figure AND the row counts/banner),
+    :func:`_answered`, and the no-rows path. Until 2026-10-15 an empty row 0
+    meant "the source default" to the figure and "everything" to the banner,
+    which reported pooling the figure never did. See
+    ``docs/claude/variant-row-selection.md``.
+
+    * **frozen** — a reopened saved plot's code versions. The frozen columns
+      and the latest flag leave the selection (``frozen_mask`` answers them;
+      "current" AND "v1" would select nothing).
+    * **stated** — the selection already names a code/run axis or the latest
+      flag, or the source has no default: used as written. Pooling versions
+      is reachable only this way, by naming them.
+    * **source default** — the selection says nothing about code, so the
+      source's ``default_pin`` (the per-location latest flag) is added. A row
+      that only says ``low_hz=20``, or nothing at all, draws current code —
+      never every version at once.
+    """
+    return _effective(
+        variant.selection,
+        active_frozen(variant, table),
+        latest_column=table.latest_column,
+        default_pin=table.default_pin,
+    )
+
+
+def _effective(
+    raw: dict[str, Any],
+    frozen: dict[str, list[str]],
+    *,
+    latest_column: str | None,
+    default_pin: dict[str, Any] | None,
+) -> tuple[dict[str, Any], str]:
+    """The rule itself, with the table's facts passed in — shared by the
+    table-bound reader above and by :func:`export_selection`, which has no
+    table, so the preview and the exported code cannot apply two rules."""
+    selection = dict(raw)
+    if frozen:
+        for column in frozen:
+            selection.pop(column, None)
+        if latest_column:
+            selection.pop(latest_column, None)
+        return selection, SOURCE_FROZEN
+    pin = dict(default_pin or {})
+    if not pin or _names_function_choice(selection, latest_column):
+        return selection, SOURCE_STATED
+    return {**pin, **selection}, SOURCE_DEFAULT
+
+
+def export_selection(
+    variant: VariantSet,
+    *,
+    latest_column: str | None,
+    default_pin: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """The selection exported code loads one row through — what the preview
+    applies, spelled for a ``Variant(...)`` wrapper.
+
+    ``latest_column`` and ``default_pin`` are the TABLE's (the same facts
+    :func:`effective_selection_with_source` reads), so the export adds the
+    latest flag exactly when the preview does. A table with no default — a
+    single-generation variable, a CSV — exports the row as written, as the preview draws it. A freeze comes back as the frozen
+    ordinal(s) on their ``Code:`` columns.
+
+    Known limit: a freeze of SEVERAL ordinals is "per location, the highest of
+    these" in the preview (:func:`frozen_mask`); a ``Variant`` list is "any
+    of". The WARN below says so in the log whenever that happens.
+    """
+    frozen = (
+        {}
+        if variant.follow_latest
+        else {column: list(levels) for column, levels in variant.frozen.items() if levels}
+    )
+    selection, _source = _effective(
+        variant.selection,
+        frozen,
+        latest_column=latest_column,
+        default_pin=default_pin,
+    )
+    for column, levels in frozen.items():
+        selection[column] = levels[0] if len(levels) == 1 else list(levels)
+        if len(levels) > 1:
+            Log.warn(
+                "export: %s is frozen to %s — the preview keeps the highest of "
+                "these per schema location, the exported Variant(...) keeps any "
+                "of them; re-save the plot on one version for an exact export",
+                column,
+                levels,
+                layer=LAYER,
+            )
+    return selection
+
+
+def effective_selection(variant: VariantSet, table: LongTable) -> dict[str, Any]:
+    """The selection half of :func:`effective_selection_with_source`."""
+    return effective_selection_with_source(variant, table)[0]
+
+
+def _ordinal_rank(value: str) -> int:
+    match = _ORDINAL.match(value)
+    return int(match.group(1)) if match else 0
+
+
+def frozen_mask(
     frame: pd.DataFrame,
+    frozen: dict[str, list[str]],
+    table: LongTable,
+    *,
+    within: pd.Series | None = None,
+) -> pd.Series:
+    """Rows a freeze keeps: per frozen column, only the frozen ordinals, and
+    within each schema location only the HIGHEST of them present.
+
+    That is "latest as of the save" reproduced from ordinals alone: a save
+    made while subject 01 was on v2 and subject 02 still on v1 froze
+    ``[v1, v2]``; reopened after a v3 run, 01 draws v2 and 02 draws v1 — not
+    both at 01, which a plain "any of" would pool.
+
+    ``within`` restricts which rows compete (the row's selection and variable
+    have already narrowed them), so the per-location best is picked among
+    rows the row could draw at all. Locations are the table's schema levels
+    plus the stacked ``Variable`` column, so two variables never compete.
+    """
+    within = within if within is not None else pd.Series(True, index=frame.index)
+    mask = pd.Series(True, index=frame.index)
+    keys = [key for key in table.schema_levels if key in frame.columns]
+    if VARIABLE_COLUMN in frame.columns:
+        keys.append(VARIABLE_COLUMN)
+    for column, ordinals in frozen.items():
+        if column not in frame.columns:
+            continue
+        values = frame[column].astype(str)
+        allowed = values.isin({str(level) for level in ordinals})
+        rank = values.map(_ordinal_rank).where(allowed & within & mask, -1)
+        if keys:
+            best = rank.groupby(
+                [frame[key].astype(str) for key in keys], sort=False
+            ).transform("max")
+        else:
+            best = pd.Series(rank.max(), index=frame.index)
+        mask &= allowed & (rank == best)
+    return mask
+
+
+def row_mask(
+    table: LongTable,
     spec: PlotSpec,
     variant: VariantSet,
-    *,
-    latest_column: str | None = None,
 ) -> pd.Series:
-    """Rows one variant ROW claims: its selection, within its own variable.
+    """Rows one variant ROW claims: its effective selection, its freeze, within
+    its own variable.
 
     The single definition, called by :func:`apply_variant_sets` (which builds
     the figure) and by ``capability.variant_summary`` (which reports how many
-    rows each variant matched). Those two disagreeing would put a number on
-    screen the figure contradicts — the same reason
-    :func:`variant_set_mask` is public.
+    rows each variant matched, and whether it spans versions). Those two
+    disagreeing put a "mixes v1 | v2" banner above a figure drawing v2 only
+    (2026-10-15) — the same reason :func:`variant_set_mask` is public.
     """
-    mask = variant_set_mask(frame, variant.selection, latest_column=latest_column)
+    frame = table.frame
+    mask = variant_set_mask(
+        frame, effective_selection(variant, table), latest_column=table.latest_column
+    )
     if VARIABLE_COLUMN in frame.columns:
         # A row claims only its own variable's rows. Without this, a row
         # pinning `Code:filterEMG=v1` names nothing about a second variable —
@@ -314,6 +500,9 @@ def row_mask(
         mask &= frame[VARIABLE_COLUMN].astype(str) == (
             variant.variable or spec.y_measure
         )
+    frozen = active_frozen(variant, table)
+    if frozen:
+        mask &= frozen_mask(frame, frozen, table, within=mask)
     return mask
 
 
@@ -323,6 +512,7 @@ def auto_label(
     index: int = 0,
     variable: str | None = None,
     latest_column: str | None = None,
+    frozen: dict[str, list[str]] | None = None,
 ) -> str:
     """The name a variant gets until the user types over it.
 
@@ -342,9 +532,17 @@ def auto_label(
     An empty selection with no variable is ``(not set)``, not "all variants":
     an unfilled row is inert (:func:`defined_sets`), so a label promising every
     variant would describe a row that contributes nothing.
+
+    ``frozen`` (a reopened saved plot's versions) is spelled ``load_cbrace v1
+    (saved)``, and replaces the latest flag and the frozen columns' own
+    selection keys, exactly as :func:`effective_selection_with_source` does —
+    "current · load_cbrace v1" would describe something the row does not draw.
     """
     parts: list[str] = []
+    frozen = {column: levels for column, levels in (frozen or {}).items() if levels}
     for column, value in selection.items():
+        if frozen and (column in frozen or (latest_column and column == latest_column)):
+            continue
         text = _level_text(value)
         if latest_column and column == latest_column:
             # A False flag is "not the current code", which is a real thing to
@@ -357,6 +555,8 @@ def auto_label(
             # function is usually obvious from context in a legend, the
             # parameter never is.
             parts.append(f"{column.rsplit('.', 1)[-1]}={text}")
+    for column, levels in frozen.items():
+        parts.append(f"{function_of_axis(column)} {_level_text(levels)} (saved)")
 
     if variable:
         return f"{variable} · {' · '.join(parts)}" if parts else variable
@@ -392,11 +592,18 @@ def label_variable(
     """
     if variant_set.variable:
         return variant_set.variable
-    if variant_set.selection or index == 0:
+    if variant_set.selection or variant_set.frozen or index == 0:
         return primary
     return None
 
 
+def says_something(variant_set: VariantSet) -> bool:
+    """A selection, a variable, or a frozen pin — any of them is a statement
+    about the data. A freeze especially: a reopened saved plot's empty row 0
+    with ``frozen={"Code:f": ["v1"]}`` must not fall back to "current"."""
+    return bool(variant_set.selection or variant_set.variable or variant_set.frozen)
+
+
 def is_stated(variant_set: VariantSet, index: int) -> bool:
     """Whether this row says anything — what the panel's "not set" tag reads.
 
@@ -407,7 +614,7 @@ def is_stated(variant_set: VariantSet, index: int) -> bool:
     empty row 0 states "the primary measure" and needs no ``Variant`` factor to
     express, so it is stated but not a defined set.
     """
-    return index == 0 or bool(variant_set.selection) or bool(variant_set.variable)
+    return index == 0 or says_something(variant_set)
 
 
 def set_name(
@@ -429,6 +636,7 @@ def set_name(
         index=index,
         variable=label_variable(variant_set, index, primary),
         latest_column=latest_column,
+        frozen=None if variant_set.follow_latest else variant_set.frozen,
     )
 
 
@@ -462,7 +670,7 @@ def defined_sets(sets: list[VariantSet]) -> list[VariantSet]:
     With no concrete row anywhere there is nothing to fold: one unnarrowed
     series needs no ``Variant`` factor to express.
     """
-    if not any(variant.selection or variant.variable for variant in sets):
+    if not any(says_something(variant) for variant in sets):
         return []
     return [
         variant for index, variant in enumerate(sets) if is_stated(variant, index)
@@ -529,12 +737,17 @@ def _answered(table: LongTable, sets: list[VariantSet]) -> set[str]:
     # WITHIN a variable and never across.
     per_variant: list[set[str]] = []
     for variant in sets:
+        # The EFFECTIVE selection (and the freeze), not the raw one: what a row
+        # answers is what it draws, by the same owner `row_mask` uses.
         per_variant.append(
             set(
                 resolve_selection(
-                    frame, variant.selection, latest_column=table.latest_column
+                    frame,
+                    effective_selection(variant, table),
+                    latest_column=table.latest_column,
                 )
             )
+            | set(active_frozen(variant, table))
         )
     return answered | set.intersection(*per_variant)
 
@@ -744,10 +957,20 @@ def _apply_default_pin(table: LongTable) -> LongTable:
     record and its superseded whole-table record together, 17 rows where there
     should be one. An unnamed plot now reads what an unnamed load reads.
 
+    The selection comes from :func:`effective_selection_with_source` for an
+    empty row — the SAME owner a stated row goes through, so the figure and
+    the row counts/banner (``capability.variant_summary``) cannot disagree
+    about what an empty row draws again (2026-10-15).
+
+    The function axes the pin answered **leave the factor list**, as they do
+    for any defined row (:func:`_answered`). Left in, a ``Code:fn`` column
+    whose rows were already filtered to one version got no role, defaulted to
+    ITERATE, and titled the figure ``Code:fn=v2``.
+
     No pin (one generation, a CSV source) leaves the table untouched, so a
     project with nothing superseded behaves exactly as before.
     """
-    pin = dict(table.default_pin or {})
+    pin, _source = effective_selection_with_source(VariantSet(), table)
     frame = table.frame
     if not pin:
         Log.info(
@@ -758,18 +981,23 @@ def _apply_default_pin(table: LongTable) -> LongTable:
         return table
     mask = variant_set_mask(frame, pin, latest_column=table.latest_column)
     kept = int(mask.sum())
+    answered = [
+        factor.name for factor in table.factors if is_function_axis(factor.name)
+    ]
     Log.info(
         "variant selection: no variant rows — the source default %s keeps %d of "
-        "%d row(s)%s",
+        "%d row(s)%s; answers %s",
         pin,
         kept,
         len(frame),
         "" if kept == len(frame) else f" ({len(frame) - kept} superseded row(s) dropped)",
+        answered or "no function axis",
         layer=LAYER,
     )
-    if kept == len(frame):
+    factors = [f for f in table.factors if f.name not in answered]
+    if kept == len(frame) and not answered:
         return table
-    return replace(table, frame=frame[mask].copy())
+    return replace(table, frame=frame[mask].copy(), factors=factors)
 
 
 def apply_variant_sets(spec: PlotSpec, table: LongTable) -> LongTable:
@@ -805,7 +1033,7 @@ def apply_variant_sets(spec: PlotSpec, table: LongTable) -> LongTable:
     counts: list[int] = []
 
     for name, variant in zip(names, sets, strict=True):
-        mask = row_mask(frame, spec, variant, latest_column=table.latest_column)
+        mask = row_mask(table, spec, variant)
         fresh = mask & assigned.isna()
         counts.append(int(fresh.sum()))
         assigned[fresh] = name
@@ -813,7 +1041,9 @@ def apply_variant_sets(spec: PlotSpec, table: LongTable) -> LongTable:
         # Code axes leave the factor list unconditionally, so a variant that
         # quietly straddles two versions has to say so here — this is the log
         # half of what the GUI shows on the row.
-        spans = spanned_code_axes(frame[fresh], variant.selection, table)
+        spans = spanned_code_axes(
+            frame[fresh], effective_selection(variant, table), table
+        )
         if spans:
             Log.warn(
                 "variant %r was built by MORE THAN ONE version of the code — "
@@ -858,5 +1088,36 @@ def apply_variant_sets(spec: PlotSpec, table: LongTable) -> LongTable:
         dict(zip(names, counts, strict=True)),
         layer=LAYER,
     )
+    log_effective_selections(names, sets, counts, table)
 
     return replace(table, frame=kept, factors=factors)
+
+
+def log_effective_selections(
+    names: list[str],
+    sets: list[VariantSet],
+    counts: list[int],
+    table: LongTable,
+) -> None:
+    """One INFO naming, per row, what it REALLY selected and why.
+
+    ``name: stated|source default|frozen <selection> [frozen <cols>] -> N
+    row(s)``. The diagnostic for the 2026-10-15 class of bug: if a banner or
+    a count ever disagrees with the figure again, this line shows which
+    selection the figure applied, beside whatever the other reader claims.
+    """
+    parts = []
+    for name, variant, count in zip(names, sets, counts, strict=True):
+        selection, source = effective_selection_with_source(variant, table)
+        frozen = active_frozen(variant, table)
+        parts.append(
+            f"{name!r}: {source} {selection}"
+            + (f" frozen {frozen}" if frozen else "")
+            + (" (follow latest)" if variant.follow_latest else "")
+            + f" -> {count} row(s)"
+        )
+    Log.info(
+        "variant rows' effective selections: %s",
+        "; ".join(parts),
+        layer=LAYER,
+    )