scistackplot 0.1.26__py3-none-any.whl

scistackplot/shape.py

@@ -0,0 +1,106 @@
+"""
+Measure shape classification.
+
+The *shape* of a measure — scalar, 1-D series, 2-D matrix — is the single
+input that decides which plot kinds are even meaningful for it (see
+``capability.available_plots``). Classification is deliberately based on
+**observed values**, not on declared dtypes or SQL type-name strings: a pandas
+object column holding numpy arrays and a DuckDB LIST column both arrive here
+as "a cell that contains a sequence", and the value is the only reliable
+common ground. (The GUI's pre-existing ``_numeric_plot_kind`` in
+``scistack_gui/api/variables.py`` made the same call for the same reason.)
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+
+class Shape(str, Enum):
+    """What one cell of a measure column holds."""
+
+    SCALAR = "scalar"
+    SERIES_1D = "1d"
+    MATRIX_2D = "2d"
+    CATEGORICAL = "categorical"
+    UNKNOWN = "unknown"
+
+    def __str__(self) -> str:  # keeps f-strings and log lines readable
+        return self.value
+
+
+def _is_number(value: Any) -> bool:
+    # bool is an int subclass; a column of True/False is categorical, not scalar.
+    if isinstance(value, bool) or isinstance(value, np.bool_):
+        return False
+    return isinstance(value, (int, float, np.integer, np.floating))
+
+
+def classify_value(value: Any) -> Shape:
+    """Classify a single cell value."""
+    if value is None or (isinstance(value, float) and np.isnan(value)):
+        return Shape.UNKNOWN
+    # bool is an int subclass, so this must precede the numeric check: a
+    # True/False column groups data, it is not something to plot on an axis.
+    if isinstance(value, (bool, np.bool_)):
+        return Shape.CATEGORICAL
+    if _is_number(value):
+        return Shape.SCALAR
+    if isinstance(value, str):
+        return Shape.CATEGORICAL
+    if isinstance(value, np.ndarray):
+        if value.ndim == 1:
+            return Shape.SERIES_1D if value.size else Shape.UNKNOWN
+        if value.ndim == 2:
+            return Shape.MATRIX_2D
+        return Shape.UNKNOWN
+    if isinstance(value, (list, tuple)):
+        if not value:
+            return Shape.UNKNOWN
+        first = value[0]
+        if _is_number(first):
+            return Shape.SERIES_1D
+        if isinstance(first, (list, tuple, np.ndarray)):
+            return Shape.MATRIX_2D
+        return Shape.UNKNOWN
+    return Shape.UNKNOWN
+
+
+def classify_column(series: pd.Series) -> Shape:
+    """
+    Classify a whole measure column.
+
+    A column is uniformly typed in every source we support (a DuckDB column,
+    or a DataFrame column built from one), so the first non-null value decides.
+    We still scan a few values rather than exactly one: a column can lead with
+    nulls, and an all-null column must classify as UNKNOWN rather than crash.
+    """
+    if series is None or len(series) == 0:
+        return Shape.UNKNOWN
+
+    if pd.api.types.is_bool_dtype(series):
+        return Shape.CATEGORICAL
+    if pd.api.types.is_numeric_dtype(series):
+        return Shape.SCALAR
+    if isinstance(series.dtype, pd.CategoricalDtype):
+        return Shape.CATEGORICAL
+
+    for value in series.head(_SCAN_LIMIT):
+        shape = classify_value(value)
+        if shape is not Shape.UNKNOWN:
+            return shape
+    return Shape.UNKNOWN
+
+
+#: How many leading values to inspect before giving up on a column. Small on
+#: purpose — this runs on every measure of every table the GUI describes.
+_SCAN_LIMIT = 20
+
+
+def is_plottable(shape: Shape) -> bool:
+    """Whether any plot kind can render this shape."""
+    return shape in (Shape.SCALAR, Shape.SERIES_1D, Shape.MATRIX_2D)

scistackplot/sources/__init__.py

@@ -0,0 +1,7 @@
+"""Data sources: one protocol, many backends."""
+
+from .base import BaseSource, DataSource
+from .csv import CsvSource
+from .frame import DataFrameSource
+
+__all__ = ["DataSource", "BaseSource", "CsvSource", "DataFrameSource"]

scistackplot/sources/base.py

@@ -0,0 +1,256 @@
+"""
+The ``DataSource`` protocol — the one seam that makes this package both
+standalone and scistack-compatible.
+
+``scistackplot`` ships CSV and DataFrame implementations; ``scistackplotdb``
+ships the scidb one. The GUI talks only to this protocol and never learns which
+implementation it has, so the same application serves a lone CSV file and a
+full scidb project. Everything above this line is pure long-table logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from ..table import LongTable
+
+
+@runtime_checkable
+class DataSource(Protocol):
+    """Supplies long-format tables and the metadata needed to build controls."""
+
+    def describe(self) -> dict:
+        """
+        Factors, measures and shapes — everything the GUI needs to render its
+        controls before any data is fetched.
+        """
+        ...
+
+    def get_table(
+        self,
+        measures: list[str],
+        *,
+        x_measure: str | None = None,
+        factor_variables: list[str] | None = None,
+    ) -> LongTable:
+        """The long-format table for a plot's measures.
+
+        Several ``measures`` **stack** into one value column plus a
+        ``Variable`` column; ``x_measure`` **joins** as an x axis instead.
+        """
+        ...
+
+    def joinable_with(self, measure: str) -> list[str]:
+        """
+        Measures that can supply an x axis for ``measure``.
+
+        Trivially "all the others" for a flat CSV. For scidb it is a real
+        question — two variables can only share a plot if their schema levels
+        can be joined — and answering it honestly keeps the GUI from offering
+        combinations that cannot be built.
+        """
+        ...
+
+    def stackable_with(self, measure: str) -> list[str]:
+        """Measures that can be plotted as another series alongside ``measure``."""
+        ...
+
+    def groupable_with(self, measure: str) -> list[str]:
+        """Variables usable as a grouping FACTOR for ``measure`` — recorded at
+        or above its schema level, so each row gets exactly one value."""
+        ...
+
+
+#: How many built tables a source keeps. Small on purpose: the entries are whole
+#: frames (millions of rows for a 1-D measure), and the access pattern they serve
+#: is narrow — the panel asks for the SAME table over and over while the user
+#: moves controls, and only changes which one when a variant row names another
+#: variable. Four covers that with room to spare; a larger cache would mostly
+#: hold frames nobody is going to ask for again.
+TABLE_CACHE_ENTRIES = 4
+
+#: Placeholder the stacked value column carries during the melt, before it is
+#: renamed to the primary measure. See :meth:`BaseSource._stacked` for why the
+#: rename is unavoidable. Deliberately not a plausible column name: it only has
+#: to survive one call, and it must not collide with a real one.
+_STACK_VALUE = "__stacked_value__"
+
+
+class BaseSource:
+    """Small shared implementation for sources backed by a single table.
+
+    Also owns the built-table cache for *every* source, ``ScidbSource``
+    included — see :meth:`get_table`.
+    """
+
+    name: str = "table"
+
+    def _table(self) -> LongTable:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+    def describe(self) -> dict:
+        return self._table().describe()
+
+    def get_table(
+        self,
+        measures: list[str],
+        *,
+        x_measure: str | None = None,
+        factor_variables: list[str] | None = None,
+    ) -> LongTable:
+        """The long table for these measures, built once per distinct request.
+
+        **Why this is memoized.** Building the table is melt + stack + join, and
+        the panel asks for the same one repeatedly: ``plot_resolve`` and
+        ``plot_capabilities`` each build it on every control change, so a single
+        click paid for it twice, and four concurrent resolves paid for it eight
+        times. The 2026-09-11 log shows exactly that — ``melted 'FilteredEMG'``
+        and ``stacked [...]`` repeating in pairs on every action while
+        ``load_variable`` (the layer below, already cached) ran once.
+
+        Keyed on everything that changes the result. Note ``measures`` is
+        order-sensitive and stays a tuple rather than a set: the order decides
+        which measure is primary and what the ``Variable`` column's level order
+        is.
+
+        **Sharing a table between callers is safe** because nothing downstream
+        mutates it — ``apply_variant_sets`` copies before writing its factor,
+        and every other step (filters, explode, aggregate) builds a new frame.
+        There is no in-place write anywhere in ``scistackplot`` or
+        ``scistackplotdb``, and ``test_a_cached_table_is_not_mutated_by_use``
+        exists to keep it that way.
+
+        Staleness is the caller's business, as it already was for the frames
+        underneath: a run that writes records drops the whole source
+        (``plot_service.invalidate``), and this cache goes with it.
+        """
+        memo = self._table_cache()
+        key = (
+            tuple(measures),
+            x_measure,
+            tuple(factor_variables or ()),
+        )
+        if key in memo:
+            return memo[key]
+
+        table = self._build_table(
+            measures, x_measure=x_measure, factor_variables=factor_variables
+        )
+        memo[key] = table
+        while len(memo) > TABLE_CACHE_ENTRIES:
+            # Insertion-ordered dict: the oldest key is the first one.
+            memo.pop(next(iter(memo)))
+        return table
+
+    def _table_cache(self) -> dict:
+        """The memo, created on first use.
+
+        Lazy rather than set in ``__init__`` so every source inherits the cache
+        without having to remember to call up — including the ones that define
+        no ``__init__`` at all.
+        """
+        memo = getattr(self, "_built_tables", None)
+        if memo is None:
+            memo = {}
+            self._built_tables = memo
+        return memo
+
+    def invalidate_tables(self) -> None:
+        """Drop built tables. Call when the rows underneath may have changed."""
+        self._table_cache().clear()
+
+    def _build_table(
+        self,
+        measures: list[str],
+        *,
+        x_measure: str | None = None,
+        factor_variables: list[str] | None = None,
+    ) -> LongTable:
+        # `factor_variables` is accepted and ignored: a flat table's factors are
+        # already columns of every row, so there is nothing to join in
+        # (`groupable_with` returns none). Accepting it keeps one call shape for
+        # every source rather than making callers branch on which they hold.
+        table = self._table()
+        requested = [*measures, *([x_measure] if x_measure else [])]
+        unknown = [m for m in requested if m not in table.measure_names]
+        if unknown:
+            raise KeyError(
+                f"Unknown measure(s) {unknown}. Available: {table.measure_names}"
+            )
+        # A flat table already carries every column, so an x measure needs no
+        # join here — only stacking changes the frame's shape.
+        return self._stacked(table, measures) if len(measures) > 1 else table
+
+    def _stacked(self, table: LongTable, measures: list[str]) -> LongTable:
+        """Melt several measure columns into one, plus a ``Variable`` column.
+
+        The CSV equivalent of ``ScidbSource._stacked_table``: two columns of a
+        gait CSV are as much "Raw vs Filtered" as two scidb variables are, and
+        keeping the standalone path capable of it is what keeps the DataSource
+        protocol honest rather than scidb-shaped.
+
+        The melt goes via :data:`_STACK_VALUE` and is renamed afterwards. It has
+        to: the stacked column takes the PRIMARY measure's name, the primary is
+        always one of the columns being melted, and ``DataFrame.melt`` refuses a
+        ``value_name`` that matches any column it is melting. Passing the name
+        directly raised ``ValueError`` for every possible input, so stacking on
+        a CSV or DataFrame source never worked at all — found 2026-09-11 by the
+        first test to ask for it.
+        """
+        from ..variants import VARIABLE_COLUMN
+
+        primary = measures[0]
+        frame = table.frame
+        id_vars = [c for c in frame.columns if c not in table.measure_names]
+        melted = frame.melt(
+            id_vars=id_vars,
+            value_vars=list(measures),
+            var_name=VARIABLE_COLUMN,
+            value_name=_STACK_VALUE,
+        ).rename(columns={_STACK_VALUE: primary})
+        level_order = {f.name: list(f.levels) for f in table.factors}
+        # Declared order, not observed: the user listed the measures.
+        level_order[VARIABLE_COLUMN] = list(measures)
+        return LongTable.from_frame(
+            melted,
+            factors=[*table.factor_names, VARIABLE_COLUMN],
+            measures=[primary],
+            level_order=level_order,
+            index_column=table.index_column,
+            name=primary,
+            schema_levels=table.schema_levels,
+            measure_labels={primary: " / ".join(measures)},
+        )
+
+    def joinable_with(self, measure: str) -> list[str]:
+        return [m for m in self._table().measure_names if m != measure]
+
+    def groupable_with(self, measure: str) -> list[str]:
+        """A flat table's factors are already columns of every row.
+
+        Grouping variables exist because scidb records a subject-level fact
+        separately from trial-level data; a CSV has no such split, so there is
+        nothing to join in.
+        """
+        return []
+
+    def stackable_with(self, measure: str) -> list[str]:
+        """Same shape, so the two share an axis. A flat table has no levels to
+        reconcile, which is the only other thing scidb has to check."""
+        table = self._table()
+        try:
+            shape = table.shape_of(measure)
+        except KeyError:
+            return []
+        return [
+            name
+            for name in table.measure_names
+            if name != measure and table.shape_of(name) is shape
+        ]
+
+    def default_measure(self) -> str | None:
+        measures = self._table().measure_names
+        return measures[0] if measures else None
+
+    def metadata(self) -> dict[str, Any]:
+        return {"source": type(self).__name__, "name": self.name}

scistackplot/sources/csv.py

@@ -0,0 +1,67 @@
+"""
+CSV source — the standalone entry point, and the direct descendant of the
+R/Shiny proof of concept.
+
+Its factor/measure split follows the same rule the proof of concept used
+(``getColNames.R``: factor columns are the non-numeric ones), but derived from
+observed value shapes rather than R's ``is.factor``, so a column of integer
+subject IDs read from CSV can still be declared a factor explicitly.
+
+This path is kept first-class — the VS Code extension routes "Plot" on a .csv
+file here, with no project and no database — so the standalone claim stays
+exercised rather than aspirational.
+
+One inference limit worth knowing: a column of purely numeric IDs (``1, 2, 3``
+for subject) is indistinguishable from a measurement by value alone, so it is
+classified as a measure. Pass ``factors=["subject", ...]`` — or read it as text
+with ``dtype={"subject": str}`` — when that is not what you want. A scidb
+source never hits this: it knows which columns are schema keys.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable
+
+import pandas as pd
+from scistacklog import Log
+
+from ..table import LongTable
+from .base import BaseSource
+
+LAYER = "scistackplot"
+
+
+class CsvSource(BaseSource):
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        factors: Iterable[str] | None = None,
+        measures: Iterable[str] | None = None,
+        level_order: dict[str, list[Any]] | None = None,
+        index_column: str | None = None,
+        **read_csv_kwargs: Any,
+    ) -> None:
+        self.path = Path(path)
+        self.name = self.path.name
+        frame = pd.read_csv(self.path, **read_csv_kwargs)
+        self._long = LongTable.from_frame(
+            frame,
+            factors=factors,
+            measures=measures,
+            level_order=level_order,
+            index_column=index_column,
+            name=self.name,
+        )
+        Log.info(
+            "loaded %s: %d row(s), %d factor(s), %d measure(s)",
+            self.path.name,
+            len(frame),
+            len(self._long.factors),
+            len(self._long.measures),
+            layer=LAYER,
+        )
+
+    def _table(self) -> LongTable:
+        return self._long

scistackplot/sources/frame.py

@@ -0,0 +1,45 @@
+"""In-memory DataFrame source — the scifor-equivalent entry point."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+import pandas as pd
+
+from ..table import LongTable
+from .base import BaseSource
+
+
+class DataFrameSource(BaseSource):
+    """
+    Wrap a DataFrame you already have.
+
+    This is the direct analogue of ``scifor.for_each`` taking a plain table:
+    no database, no configuration, no file IO. Column roles are inferred from
+    observed value shapes when not given (see ``LongTable.from_frame``).
+    """
+
+    def __init__(
+        self,
+        frame: pd.DataFrame,
+        *,
+        factors: Iterable[str] | None = None,
+        measures: Iterable[str] | None = None,
+        level_order: dict[str, list[Any]] | None = None,
+        variant_factors: Iterable[str] = (),
+        index_column: str | None = None,
+        name: str = "dataframe",
+    ) -> None:
+        self.name = name
+        self._long = LongTable.from_frame(
+            frame,
+            factors=factors,
+            measures=measures,
+            level_order=level_order,
+            variant_factors=variant_factors,
+            index_column=index_column,
+            name=name,
+        )
+
+    def _table(self) -> LongTable:
+        return self._long