scistackplot 0.1.26__tar.gz → 0.1.28__tar.gz

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

@@ -20,6 +20,10 @@ __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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.26
+Version: 0.1.28
 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.28}/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.28}/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.28}/src/scistackplot/capability.py

@@ -402,9 +402,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.28}/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.26 → scistackplot-0.1.28}/src/scistackplot/reduce.py

@@ -504,8 +504,53 @@ def _fanout_notes(spec: PlotSpec, table: LongTable) -> list[str]:
 # ---------------------------------------------------------------------------
 
 
+def _location_mask(frame: pd.DataFrame, spec: PlotSpec) -> "pd.Series | None":
+    """Rows matching any prefix in ``spec.location_filter``, or None if inert.
+
+    One prefix constrains only the keys it names **that the frame actually
+    has**. A key the frame lacks is simply not constrained — the graceful answer
+    for a shallower variable (a subject-level Mass has one value for "subject 02
+    trial 3", and that is the value that contributes).
+
+    Each prefix carries its own keys, so a non-contiguous location
+    (``subject`` + ``speed``, ``timepoint`` NULL) matches the keys it names
+    rather than whatever sits at that position in the schema — see
+    :class:`~scistackplot.spec.LocationFilter`.
+
+    Written as one vectorised comparison per (prefix, key) rather than a row-wise
+    tuple match, because :func:`scistackplot.codegen` has to emit the *same*
+    rule as readable pandas and the two must not be able to disagree. That makes
+    the cost O(prefixes x depth) column comparisons; a single-select is one
+    prefix, and a ticked subtree collapses to its own short prefix, so the
+    common cases are small by construction.
+    """
+    prefixes = spec.location_filter.prefixes()
+    if not prefixes:
+        return None  # inert: clicking into a picker is not a statement
+
+    named = {key for prefix in prefixes for key, _value in prefix}
+    known = [key for key in named if key in frame.columns]
+    if not known:
+        Log.warn(
+            "location filter names none of this table's columns (%s) — ignored",
+            ", ".join(sorted(named)),
+            layer=LAYER,
+        )
+        return None
+
+    as_text = {key: frame[key].astype(str) for key in known}
+    mask = pd.Series(False, index=frame.index)
+    for prefix in prefixes:
+        matched = pd.Series(True, index=frame.index)
+        for key, value in prefix:
+            if key in as_text:
+                matched &= as_text[key] == str(value)
+        mask |= matched
+    return mask
+
+
 def apply_filters(frame: pd.DataFrame, spec: PlotSpec) -> pd.DataFrame:
-    """Rows surviving ``spec.filters``.
+    """Rows surviving ``spec.filters`` and ``spec.location_filter``.
 
     Public because the GUI's pickers report "3 of 12 selected" and that readout
     has to be measured with exactly the rule the figure uses — the same reason
@@ -517,9 +562,19 @@ def apply_filters(frame: pd.DataFrame, spec: PlotSpec) -> pd.DataFrame:
     or ``1`` (int) depending on the source, and a silently empty figure is the
     worst possible answer to a picker the user just clicked.
     """
-    if not spec.filters:
+    location = _location_mask(frame, spec)
+    if not spec.filters and location is None:
         return frame
     mask = pd.Series(True, index=frame.index)
+    if location is not None:
+        mask &= location
+        Log.debug(
+            "location filter: %d -> %d row(s) over %d prefix(es)",
+            len(frame),
+            int(mask.sum()),
+            len(spec.location_filter.prefixes()),
+            layer=LAYER,
+        )
     for flt in spec.filters:
         if flt.column not in frame.columns:
             # A spec outlives the table it was written against — a filter naming

{scistackplot-0.1.26 → scistackplot-0.1.28}/src/scistackplot/spec.py

@@ -187,6 +187,90 @@ class Filter:
     maximum: float | None = None
 
 
+@dataclass(frozen=True)
+class LocationFilter:
+    """Which schema locations to draw, as a set of hierarchy **prefixes**.
+
+    The difference from :class:`Filter` is the whole reason this exists.
+    ``Filter`` holds one include-list per column, so a set of them can only ever
+    express a **Cartesian product**: ``subject ∈ {01,02} × trial ∈ {3,7}``. That
+    is the right shape for "narrow this factor", and the wrong shape for a
+    hierarchical location picker, where the user ticks boxes on a tree and means
+    something ragged — *all* of subject 01, plus only trials 1–3 of subject 02.
+    Real datasets are ragged (subject 01 ran eight trials, subject 02 ran five),
+    so the Cartesian form is not merely less expressive, it names combinations
+    that never existed.
+
+    Worse, in a tree UI the per-column form is actively misleading: unticking
+    ``S01 / trial 3`` would silently drop trial 3 from *every* subject, because
+    there is only one ``trial`` include-list to edit.
+
+    ``include`` is a list of prefixes, each a list of ``[key, value]`` pairs
+    outermost first: ``[["subject", "01"]]`` is all of subject 01,
+    ``[["subject", "02"], ["trial", "3"]]`` is one trial. Storing the **minimal
+    covering set** (collapse a fully-ticked parent to its own short prefix) is
+    what keeps a later-added trial inside an already-selected subject instead of
+    silently outside it.
+
+    **A prefix names its keys rather than relying on position**, and that is not
+    verbosity. A dataset schema is a linear hierarchy but a *saved location* need
+    not fill it: a cross-cutting result saved at ``subject`` + ``speed`` with
+    ``timepoint`` NULL is a supported, documented shape
+    (docs/claude/schema-hierarchy-contiguity.md), and its location is
+    ``[["subject","01"], ["speed","SSV"]]``. Read positionally against the
+    schema, that second value would be matched against ``timepoint`` — selecting
+    nothing, in silence. Naming the key makes the hole impossible to
+    misinterpret, and it means the picker sends a node's own path back verbatim
+    with no translation step to get wrong.
+
+    An empty ``include`` is **inert**: it constrains nothing, matching the rule
+    an unfilled variant row follows (docs/claude/plot-variant-rows.md §3).
+    Clicking into a picker is not a statement about the data.
+
+    Values are compared as text, like every other selection that crosses JSON.
+    """
+
+    #: Schema keys, outermost first. Display order only — matching reads the
+    #: keys named inside each prefix, never this list's positions.
+    keys: list[str] = field(default_factory=list)
+    #: Prefixes to keep. Lists rather than tuples so JSON and TOML round-trip
+    #: with no conversion; :meth:`prefixes` is the tuple view for matching.
+    include: list[list[list[str]]] = field(default_factory=list)
+
+    def prefixes(self) -> list[tuple[tuple[str, str], ...]]:
+        """``include`` as tuples of ``(key, value)`` text pairs, empties dropped."""
+        out = []
+        for entry in self.include:
+            prefix = tuple(
+                (str(pair[0]), str(pair[1])) for pair in entry if len(pair) == 2
+            )
+            if prefix:
+                out.append(prefix)
+        return out
+
+    def is_empty(self) -> bool:
+        return not self.prefixes()
+
+    def to_dict(self) -> dict:
+        return {
+            "keys": list(self.keys),
+            "include": [
+                [[str(pair[0]), str(pair[1])] for pair in entry if len(pair) == 2]
+                for entry in self.include
+            ],
+        }
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "LocationFilter":
+        return cls(
+            keys=list(raw.get("keys") or []),
+            include=[
+                [[str(pair[0]), str(pair[1])] for pair in entry if len(pair) == 2]
+                for entry in (raw.get("include") or [])
+            ],
+        )
+
+
 @dataclass(frozen=True)
 class LevelGroup:
     """A factor derived by bucketing another factor's levels.
@@ -468,6 +552,10 @@ class PlotSpec:
     y_axis: YAxis = field(default_factory=YAxis)
     style: StyleOptions = field(default_factory=StyleOptions)
     filters: list[Filter] = field(default_factory=list)
+    #: Which schema locations to draw. Written by the schema location picker,
+    #: which REPLACED the flat per-key pickers — see :class:`LocationFilter` for
+    #: why a set of ``Filter``s cannot express the same selection.
+    location_filter: LocationFilter = field(default_factory=LocationFilter)
     #: Variables joined in as FACTORS rather than plotted — a subject-level
     #: ``Condition`` holding stim/sham, say. They classify as CATEGORICAL and so
     #: are rightly refused as measures; as factors they take a role like any
@@ -569,6 +657,7 @@ class PlotSpec:
             "cols": [_matcher_to_dict(m) for m in self.facet.cols],
         }
         raw["y_axis"] = self.y_axis.to_dict()
+        raw["location_filter"] = self.location_filter.to_dict()
         raw["variant_sets"] = [s.to_dict() for s in self.variant_sets]
         raw["level_groups"] = [g.to_dict() for g in self.level_groups]
         raw["x_layers"] = list(self.x_layers)
@@ -593,6 +682,7 @@ class PlotSpec:
             y_axis=YAxis.from_dict(raw.get("y_axis") or {}),
             style=StyleOptions(**(raw.get("style") or {})),
             filters=[Filter(**f) for f in (raw.get("filters") or [])],
+            location_filter=LocationFilter.from_dict(raw.get("location_filter") or {}),
             factor_variables=list(raw.get("factor_variables") or []),
             level_groups=[
                 LevelGroup.from_dict(g) for g in (raw.get("level_groups") or [])