scistackplot 0.1.28__tar.gz → 0.1.29__tar.gz

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

@@ -30,3 +30,4 @@ scistack-gui/frontend/dist/
 # per-run files, not source.
 /exports/
 *.log
+output.txt

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.28
+Version: 0.1.29
 Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
 Author: SciStack Contributors
 License-Expression: MIT

{scistackplot-0.1.28 → 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",
     },
 }
 

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