scistackplot 0.1.26__tar.gz → 0.1.29__tar.gz

{scistackplot-0.1.26 → scistackplot-0.1.29}/.gitignore

@@ -20,9 +20,14 @@ __pycache__/
 *.duckdb.wal
 *.wal
 scistack-gui/frontend/node_modules/
+# Compiled output of the frontend's React-free unit tests (npm test in
+# scistack-gui/frontend). Regenerated by `tsc -p tsconfig.test.json`; unlike
+# extension/dist/, nothing loads it at runtime.
+scistack-gui/frontend/dist/
 # mkdocs build output (regenerated by `mkdocs build`)
 /site/
 # Runtime output of code_export_service (pipeline-to-code export) — timestamped
 # per-run files, not source.
 /exports/
 *.log
+output.txt

{scistackplot-0.1.26 → scistackplot-0.1.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.26
+Version: 0.1.29
 Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
 Author: SciStack Contributors
 License-Expression: MIT
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Typing :: Typed
 Requires-Python: >=3.10

{scistackplot-0.1.26 → scistackplot-0.1.29}/pyproject.toml

@@ -32,6 +32,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Visualization",
     "Typing :: Typed",
 ]

{scistackplot-0.1.26 → scistackplot-0.1.29}/src/scistackplot/__init__.py

@@ -68,6 +68,7 @@ from .spec import (
     FacetOptions,
     Filter,
     LevelGroup,
+    LocationFilter,
     MatchOp,
     Matcher,
     PlotKind,
@@ -122,6 +123,7 @@ __all__ = [
     "StyleOptions",
     "Filter",
     "LevelGroup",
+    "LocationFilter",
     "VariantSet",
     # data
     "LongTable",

{scistackplot-0.1.26 → scistackplot-0.1.29}/src/scistackplot/capability.py

@@ -24,17 +24,18 @@ DISTRIBUTION_KINDS = (PlotKind.BOX, PlotKind.VIOLIN, PlotKind.BAR, PlotKind.BAND
 
 #: What each role is CALLED, per measure shape.
 #:
-#: The role names are the library's vocabulary; these are the user's. Two of
-#: them read as nonsense on 1-D data under the generic wording — "Average over"
-#: and "Replicates" describe what happens to a table, and what the user is
-#: looking at is a set of traces. Reported by the backend rather than hardcoded
-#: in the panel so the words and the behaviour stay together (CLAUDE.md NOTE 3).
+#: The role names are the library's vocabulary; these are the user's — and the
+#: two are kept the SAME wherever a user has to search for one (see the FREE
+#: entry in _ROLE_LABELS). What varies by shape is what a role DOES: "Average
+#: over" describes a table, and a user looking at 1-D data is looking at
+#: traces, so AGGREGATE is renamed for them. Reported by the backend rather
+#: than hardcoded in the panel so the words and the behaviour stay together
+#: (CLAUDE.md NOTE 3); the per-shape explanation is _ROLE_HINTS_BY_SHAPE.
 #:
 #: Only the entries that differ from :data:`_ROLE_LABELS` need listing.
 _ROLE_LABELS_BY_SHAPE: dict[Shape, dict[Role, str]] = {
     Shape.SERIES_1D: {
         Role.AGGREGATE: "Average into one line",
-        Role.FREE: "One line each",
     },
 }
 
@@ -67,7 +68,14 @@ _ROLE_LABELS: dict[Role, str] = {
     Role.FACET: "Facet",
     Role.ITERATE: "Separate figures",
     Role.AGGREGATE: "Average over",
-    Role.FREE: "Replicates",
+    # "Free", not "Replicates" / "One line each". The role's own name, kept the
+    # same for every shape, because a user hunting for it in the dropdown has
+    # read it in the docs, in a saved spec's TOML and in an exported `roles=`
+    # argument — and found nothing matching (user, 2026-09-13). It is also the
+    # role whose meaning a noun cannot carry on its own: what a FREE factor
+    # does depends on the plot kind (one line each, a bar's error bars, a box's
+    # distribution), which is what the HINT is for, per shape.
+    Role.FREE: "Free",
 }
 
 _ROLE_HINTS: dict[Role, str] = {
@@ -75,15 +83,33 @@ _ROLE_HINTS: dict[Role, str] = {
     Role.COLOR: "One coloured series per level",
     Role.FACET: "One subplot per level — arrange them under Layout",
     Role.ITERATE: "One whole figure per level",
-    Role.AGGREGATE: "Collapse this factor to its mean",
-    Role.FREE: "Keep as repeated observations",
+    Role.AGGREGATE: "Collapse to the mean first, so this factor does NOT "
+    "widen the error bars",
+    Role.FREE: "Keep each level as its own observation, so this factor DOES "
+    "widen the error bars",
 }
 
+#: Stated as a CONTRAST, and deliberately in the same terms on both sides.
+#:
+#: These are the two roles a user cannot tell apart from the labels alone —
+#: "Average over" and "Free" both sound like "not on an axis", and the earlier
+#: hints described each one on its own, both using the word "average" (user,
+#: 2026-09-13). The thing that actually distinguishes them is what they do to
+#: the ERROR BARS: with schema [subject, trial] and a band, trial=AGGREGATE
+#: averages each subject's trials into one trace and the band is then the
+#: spread across SUBJECTS; trial=FREE pools every subject-trial trace, so the
+#: band mixes within- and between-subject variability and a subject with more
+#: trials weighs more. Same plot kind, same data, different published numbers —
+#: which is why the plot-kind control cannot express this and both roles exist
+#: (`reduce._collapse_aggregates` runs before `_summarize`; `has_replicates`
+#: is true only when something is FREE, which is the part the kind list DOES
+#: express — collapse everything and the summary kinds disappear).
 _ROLE_HINTS_BY_SHAPE: dict[Shape, dict[Role, str]] = {
     Shape.SERIES_1D: {
-        Role.AGGREGATE: "Average these traces together, sample by sample",
-        Role.FREE: "Draw one trace per level — and what a mean ± error band "
-        "is computed from",
+        Role.AGGREGATE: "Average these traces together sample by sample "
+        "first, so this factor does NOT widen the error band",
+        Role.FREE: "One trace per level, each its own observation — so this "
+        "factor DOES widen the error band",
     },
 }
 
@@ -402,9 +428,12 @@ def factor_summary(spec: PlotSpec, derived: LongTable) -> list[dict]:
         entry["x_available"] = on_x["available"]
         entry["x_reason"] = on_x["reason"]
 
-    if not spec.filters:
+    if not spec.filters and spec.location_filter.is_empty():
         # Nothing filtered: everything is selected, and no frame scan is needed
-        # on the common path.
+        # on the common path. The location filter has to be checked here too —
+        # it narrows rows exactly as a Filter does, and a fast path that only
+        # knew about one of them would report "all 12 selected" beside a figure
+        # drawing 3, which is the precise failure this readout exists to avoid.
         for entry in factors:
             entry["selected"] = list(entry["levels"])
         return factors

{scistackplot-0.1.26 → scistackplot-0.1.29}/src/scistackplot/codegen.py

@@ -352,6 +352,14 @@ def _preamble(spec, table, roles, shape) -> list[str]:
             ]
         )
 
+    # Schema locations. Emitted as one vectorised comparison per (prefix, key),
+    # which is the SAME rule reduce._location_mask applies — a ragged selection
+    # cannot be expressed as `for_each(subject=[...], trial=[...])`, whose keys
+    # cross-product, so it has to be a mask inside the function body. The
+    # `if _k in df.columns` guard is not defensive clutter: it is how a key the
+    # frame lacks goes unconstrained, matching the interactive path exactly.
+    lines.extend(_location_lines(spec))
+
     filter_lines: list[str] = []
     for flt in spec.filters:
         if flt.include is not None:
@@ -467,6 +475,32 @@ def _preamble(spec, table, roles, shape) -> list[str]:
     return lines
 
 
+def _location_lines(spec: PlotSpec) -> list[str]:
+    """Generated pandas for ``spec.location_filter`` — empty when it is inert.
+
+    Kept beside the other preamble emitters rather than inlined so the one test
+    that matters can compare its output against
+    :func:`scistackplot.reduce._location_mask` on the same frame.
+    """
+    prefixes = spec.location_filter.prefixes()
+    if not prefixes:
+        return []
+    plural = "" if len(prefixes) == 1 else "s"
+    return [
+        f"# schema locations: {len(prefixes)} selection{plural}",
+        f"_loc_prefixes = {[[list(pair) for pair in p] for p in prefixes]!r}",
+        "_loc_mask = pd.Series(False, index=df.index)",
+        "for _p in _loc_prefixes:",
+        "    _m = pd.Series(True, index=df.index)",
+        "    for _k, _v in _p:",
+        "        if _k in df.columns:",
+        "            _m &= df[_k].astype(str) == _v",
+        "    _loc_mask |= _m",
+        "df = df[_loc_mask]",
+        "",
+    ]
+
+
 def _facet_layout_args(spec, table: LongTable, facets: list[str]) -> list[str]:
     """
     seaborn arguments that reproduce the interactive facet arrangement.
@@ -754,6 +788,7 @@ def _color_level_count(spec: PlotSpec, table: LongTable, color: str) -> int:
         levels = [str(level) for level in table.factor(color).levels]
     except KeyError:
         return 2
+    levels = _levels_after_location(spec, color, levels)
     for flt in spec.filters:
         if flt.column != color:
             continue
@@ -766,6 +801,28 @@ def _color_level_count(spec: PlotSpec, table: LongTable, color: str) -> int:
     return len(levels)
 
 
+def _levels_after_location(spec: PlotSpec, column: str, levels: list[str]) -> list[str]:
+    """``levels`` narrowed by ``spec.location_filter``, for one schema key.
+
+    The rule follows from prefixes constraining only the keys they name: a
+    prefix that never mentions this column says nothing about it, so if any
+    such prefix is selected the column keeps every level. Only when *every*
+    prefix names it do the values they give become the surviving set.
+
+    Concretely, selecting all of subject 01 plus subject 02's trial 3 leaves
+    ``trial`` with all its levels — because "all of subject 01" did not name a
+    trial — which is what the figure will actually draw.
+    """
+    prefixes = spec.location_filter.prefixes()
+    if not prefixes:
+        return levels
+    named = [dict(prefix) for prefix in prefixes]
+    if any(column not in prefix for prefix in named):
+        return levels
+    keep = {prefix[column] for prefix in named}
+    return [level for level in levels if level in keep]
+
+
 #: Column the generated code builds for a nested x axis.
 _X_NESTED = "_x"
 

scistackplot-0.1.29/src/scistackplot/dedup.py

@@ -0,0 +1,93 @@
+"""Run a keyed build ONCE even when several threads ask for it at the same time.
+
+Memoizing a build only helps the second caller if the first one has *finished*.
+The panel does not work that way: opening it fires ``plot_describe``,
+``plot_resolve``, ``plot_capabilities`` and ``plot_location_tree`` together, the
+server runs a thread per request, and every one of them asks for the same table.
+
+Measured on 2026-09-13: two requests both logged ``table cache MISS`` and both
+built the identical 5.2 GB table, concurrently — 188.8 s and 104.1 s, finishing
+within 100 ms of each other (.claude/plot-at-scale-plan.md §7.1). The memo was
+written after ``_build_table`` returned, so the second arrival saw an empty cache
+and repeated all of it. A classic cache stampede; the 2026-09-11 memoization work
+fixed sequential repeat cost and never addressed concurrent arrival.
+
+:class:`SingleFlight` closes that: the first caller for a key builds, everyone
+else waits on the same result and pays nothing.
+"""
+
+from __future__ import annotations
+
+import threading
+from concurrent.futures import Future
+from typing import Any, Callable
+
+
+class SingleFlight:
+    """Deduplicate concurrent builds by key.
+
+    One instance per cache. Keys must be hashable and must mean the same thing
+    the cache's own key means — a narrower key here would merge builds that are
+    not interchangeable.
+
+    Thread-safe. The internal lock is held only while claiming or releasing a
+    key, never while building, so two DIFFERENT keys still build in parallel.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._inflight: dict[Any, Future] = {}
+
+    def run(
+        self,
+        key: Any,
+        build: Callable[[], Any],
+        *,
+        on_wait: Callable[[], None] | None = None,
+    ) -> Any:
+        """``build()``'s result, computing it once across concurrent callers.
+
+        The first caller for ``key`` runs ``build``; any caller arriving while
+        that is in flight blocks until it finishes and gets the same object.
+
+        ``on_wait`` is called (once, by each waiter) instead of building, for
+        logging — a waiter that silently returns the right answer is
+        indistinguishable in a log from a cache hit, and those have very
+        different meanings when reading a slow request.
+
+        A failing ``build`` raises in the owner AND in every waiter: the waiters
+        asked for a value that could not be produced, and swallowing it here
+        would hand them a wrong answer or a hang. The key is released either
+        way, so a later attempt is free to retry.
+        """
+        with self._lock:
+            future = self._inflight.get(key)
+            owner = future is None
+            if owner:
+                future = Future()
+                self._inflight[key] = future
+
+        if not owner:
+            if on_wait is not None:
+                on_wait()
+            # Raises here if the owner's build failed — by design, see above.
+            return future.result()
+
+        try:
+            result = build()
+        except BaseException as exc:
+            # Release BEFORE publishing the failure so a waiter that wakes and
+            # immediately retries finds a clear slot rather than this dead one.
+            with self._lock:
+                self._inflight.pop(key, None)
+            future.set_exception(exc)
+            raise
+        with self._lock:
+            self._inflight.pop(key, None)
+        future.set_result(result)
+        return result
+
+    def in_flight(self) -> int:
+        """How many keys are building right now. For tests and diagnostics."""
+        with self._lock:
+            return len(self._inflight)

scistackplot-0.1.29/src/scistackplot/framesize.py

@@ -0,0 +1,105 @@
+"""How big is this frame, really — in cells AND in samples.
+
+A row count is the wrong unit for a table whose cells hold signals. 4190 rows of
+a 200-sample array and 4190 rows of a 250,000-sample array are the same row
+count and four orders of magnitude apart in work, and every load/reduce log line
+in this package reported only rows. On 2026-09-13 that made a plot that never
+returned indistinguishable, from the log alone, from a plot over a small table
+(.claude/plot-at-scale-plan.md §1).
+
+So one helper, used by every layer that reports frame size, so `load_variable`
+in ``scistackplotdb`` and the reduce path here cannot describe the same frame in
+different units.
+
+**Cost.** ``len()`` on a list or ndarray is O(1), so measuring is one pass over
+the cells of the measure columns — cheap enough to run unconditionally on a load
+that is already touching every one of those cells. It deliberately does NOT sum
+``nbytes`` or walk into the values: the point is to size the work, not to audit
+memory exactly.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    import pandas as pd
+
+#: Rough bytes per element for a Python ``list[float]`` cell: the float object
+#: (24 on CPython 64-bit) plus the list's pointer slot (8). Used only to turn a
+#: sample count into an order-of-magnitude memory figure in a log line, which is
+#: what distinguishes "big" from "hopeless" at a glance.
+PYLIST_BYTES_PER_SAMPLE = 32
+
+#: Bytes per element once a cell is a float64 ndarray. The gap between this and
+#: :data:`PYLIST_BYTES_PER_SAMPLE` is the prize for fetching via Arrow.
+NUMPY_BYTES_PER_SAMPLE = 8
+
+
+def cell_samples(value: Any) -> int:
+    """Number of samples in one cell: its length, or 1 for a scalar.
+
+    ``None`` and strings count as 0 — neither is a sample, and a string's length
+    would be a character count masquerading as one.
+    """
+    if value is None or isinstance(value, (str, bytes)):
+        return 0
+    try:
+        return len(value)
+    except TypeError:
+        return 1  # a scalar is one sample
+
+
+def frame_extent(frame: "pd.DataFrame", columns: list[str] | None = None) -> dict:
+    """``{rows, cells, samples, est_bytes, boxed}`` for ``frame``.
+
+    ``columns`` limits the scan to the measure columns worth measuring; omitted,
+    every column is scanned, which is only appropriate for a small frame.
+
+    ``boxed`` is True when the first sampled cell is a Python ``list``/``tuple``
+    rather than an ndarray — i.e. the payload is carried as boxed Python floats.
+    That single flag is what says whether an Arrow fetch path would help, so it
+    is worth a word in the log even though it is only a sample.
+    """
+    rows = len(frame)
+    names = [c for c in (columns or list(frame.columns)) if c in frame.columns]
+    cells = 0
+    samples = 0
+    boxed = False
+    seen_a_cell = False
+    for name in names:
+        series = frame[name]
+        for value in series.to_numpy():
+            if value is None:
+                continue
+            n = cell_samples(value)
+            if n == 0:
+                continue
+            cells += 1
+            samples += n
+            if not seen_a_cell:
+                boxed = isinstance(value, (list, tuple))
+                seen_a_cell = True
+    per_sample = PYLIST_BYTES_PER_SAMPLE if boxed else NUMPY_BYTES_PER_SAMPLE
+    return {
+        "rows": rows,
+        "cells": cells,
+        "samples": samples,
+        "est_bytes": samples * per_sample,
+        "boxed": boxed,
+    }
+
+
+def format_extent(extent: dict) -> str:
+    """One log-line fragment: ``rows=419 cells=4190 samples=1.1e+09 ~34.0GB boxed``.
+
+    Samples go in scientific notation because the interesting range spans six
+    orders of magnitude and the exact digits never matter.
+    """
+    gb = extent["est_bytes"] / 1024**3
+    size = f"~{gb:.1f}GB" if gb >= 0.1 else f"~{extent['est_bytes'] / 1024**2:.0f}MB"
+    return (
+        f"rows={extent['rows']} cells={extent['cells']} "
+        f"samples={extent['samples']:.3g} {size}"
+        + (" boxed" if extent["boxed"] else " ndarray")
+    )

scistackplot-0.1.29/src/scistackplot/numeric.py

@@ -0,0 +1,61 @@
+"""``pd.to_numeric(errors="coerce")`` that survives numpy scalars.
+
+Once a source hands a 1-D cell over as an ``np.ndarray`` rather than a list,
+``DataFrame.explode`` yields one ``np.float64`` OBJECT per sample instead of a
+Python float. pandas' ``maybe_convert_numeric`` (pandas 3.x, numpy 2.x) calls
+``len()`` on any value that has ``__len__`` — numpy scalars do, and raise
+``TypeError: len() of unsized object``. Found 2026-09-13 the moment the DuckDB
+fetch stopped boxing (``scistackplotdb`` ``test_load_fetch.py``); every
+``to_numeric`` downstream of an explode or over a cell column goes through here.
+
+The fast path is also the point: a column of numpy scalars casts to float64 in
+one C-level pass, where ``to_numeric`` was inspecting each object.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+
+def coerce_numeric(values: pd.Series) -> pd.Series:
+    """``values`` as float64, non-numeric entries NaN — never raising on a
+    numpy scalar, and never stacking a column of array cells into a matrix."""
+    if pd.api.types.is_numeric_dtype(values):
+        return values
+    raw = values.to_numpy()
+    sample = _first_present(raw)
+    if isinstance(sample, (np.generic, int, float)) and not isinstance(sample, bool):
+        # Scalars (numpy or Python): one vectorised cast. Anything that is not
+        # a number in the column raises here and falls through to the coercing
+        # path below, which is what `errors="coerce"` promised.
+        try:
+            return pd.Series(raw.astype("float64"), index=values.index)
+        except (TypeError, ValueError):
+            pass
+    return pd.to_numeric(values.map(_unboxed), errors="coerce")
+
+
+def _first_present(raw: np.ndarray) -> Any:
+    for value in raw:
+        if value is None:
+            continue
+        if isinstance(value, float) and value != value:
+            continue
+        return value
+    return None
+
+
+def _unboxed(value: Any) -> Any:
+    """A numpy scalar as its Python value; a list-like cell as None.
+
+    ``to_numeric(errors="coerce")`` turned a list cell into NaN; an ndarray
+    cell must land in the same place rather than in ``len()``.
+    """
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, (list, tuple, np.ndarray)):
+        return None
+    return value