scistackplotdb 0.1.26__py3-none-any.whl

scistackplotdb/variants.py

@@ -0,0 +1,225 @@
+"""
+Variant selection, in scidb's vocabulary.
+
+Two jobs, both translations rather than policy:
+
+* :func:`variant_set` turns a ``scidb.Variant`` — the selector a scientist
+  already writes in ``for_each`` — into the column-keyed
+  ``scistackplot.VariantSet`` a spec can serialize. Writing the selector once
+  and having it mean the same thing in a run and in a figure is the whole point;
+  a second, plotting-only dialect for "the v1 records" would be one more thing
+  to keep in sync and one more thing to get wrong.
+* :func:`variant_graph` answers what a variant picker needs to draw itself:
+  which axes exist for a variable, and every version each function in its chain
+  has ever run under.
+
+The translation lives here because it needs *both* halves: scidb's namespacing
+(``__code__``, ``bandpass.low_hz``) and the plotting layer's column names
+(``Code:bandpass``). scistackplot must not import scidb — the CSV path depends
+on that — and scidb has no business knowing what a figure calls a column.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from scistacklog import Log
+from scistackplot import CODE_FACTOR_PREFIX, LongTable, VariantSet, natural_sort_key
+
+from .load import LATEST_COLUMN
+
+LAYER = "scistackplotdb"
+
+
+def variant_set(
+    name: str | None,
+    variant: Any,
+    table: LongTable | None = None,
+) -> VariantSet:
+    """
+    Build a named :class:`~scistackplot.spec.VariantSet` from a ``scidb.Variant``.
+
+    ::
+
+        table = source.get_table(["StepLength"])
+        spec = PlotSpec(
+            measures=["StepLength"],
+            variant_sets=[
+                variant_set("baseline",   Variant(StepLength, code_version="v1"), table),
+                variant_set("new filter", Variant(StepLength, fn="bandpass", low_hz=20), table),
+            ],
+            roles={"Variant": Role.COLOR, "session": Role.X},
+        )
+
+    ``table`` is what resolves the *abbreviations* scidb allows — a bare
+    ``code_version=`` (which function?) and a bare branch-param name (which
+    producing function's ``low_hz``?). Both are resolved exactly as scidb
+    resolves them at load time: by looking at what actually exists, and raising
+    rather than guessing when more than one candidate matches. Omit ``table``
+    only when every key is already unambiguous (``fn=``-qualified, or a dotted
+    name), and this raises if one is not — a variant that quietly selected the
+    wrong function's version would be undetectable in the figure.
+    """
+    branch_params = getattr(variant, "branch_params", None)
+    if branch_params is None:
+        raise TypeError(
+            f"variant_set expects a scidb.Variant (or anything carrying "
+            f"branch_params); got {type(variant).__name__}. For a selection you "
+            f"have already written as columns, build "
+            f"scistackplot.VariantSet(name, selection) directly."
+        )
+    return VariantSet(name=name, selection=selection_for(branch_params, table))
+
+
+def selection_for(
+    branch_params: dict[str, Any], table: LongTable | None = None
+) -> dict[str, Any]:
+    """``Variant.branch_params`` → a column-keyed selection.
+
+    ``__code__``/``__code__.fn`` become ``Code:fn``; branch params keep their
+    namespaced name, which is already the column name.
+    """
+    from scidb.variant import CODE_PIN_PREFIX
+
+    axes = _axes_of(table)
+    code_axes = [a for a in axes if a["kind"] == "code"]
+
+    selection: dict[str, Any] = {}
+    for key, value in branch_params.items():
+        if key == CODE_PIN_PREFIX:
+            selection[_bare_code_column(code_axes)] = value
+        elif key.startswith(f"{CODE_PIN_PREFIX}."):
+            selection[f"{CODE_FACTOR_PREFIX}{key.split('.', 1)[1]}"] = value
+        else:
+            selection[_param_column(key, axes)] = value
+    return selection
+
+
+def _axes_of(table: LongTable | None) -> list[dict]:
+    if table is None:
+        return []
+    return [f.origin for f in table.variant_factors if f.origin]
+
+
+def _bare_code_column(code_axes: list[dict]) -> str:
+    """The column a bare ``code_version=`` means, or a message naming the choice.
+
+    Same rule as ``scidb.database._filter_records_by_code_version``: exactly one
+    versioned function is unambiguous, several are not.
+    """
+    if len(code_axes) == 1:
+        return code_axes[0]["column"]
+    if not code_axes:
+        raise ValueError(
+            "code_version= needs a table to resolve against (pass one), and "
+            "that table must hold at least one versioned function. If you know "
+            'the function, name it: Variant(X, fn="bandpass", code_version="v1").'
+        )
+    names = sorted(a["function"] for a in code_axes)
+    raise ValueError(
+        f"code_version= is ambiguous: {len(names)} functions in this table hold "
+        f"more than one version ({names}). Name one with "
+        f'fn="{names[0]}", or add a variant per function.'
+    )
+
+
+def _param_column(key: str, axes: list[dict]) -> str:
+    """Resolve a branch-param key to its column, suffix-matching a bare name."""
+    columns = [a["column"] for a in axes if a["kind"] == "param"]
+    if not columns or key in columns:
+        # Already namespaced (or nothing to check it against — the caller passed
+        # no table, having promised the key is exact).
+        return key
+    hits = [c for c in columns if c.rsplit(".", 1)[-1] == key]
+    if len(hits) == 1:
+        return hits[0]
+    if not hits:
+        raise ValueError(
+            f"No variant axis matches branch param {key!r}. This table's axes "
+            f"are {sorted(columns)}."
+        )
+    raise ValueError(
+        f"Branch param {key!r} is ambiguous — {len(hits)} producing functions "
+        f"use it ({sorted(hits)}). Disambiguate with fn=, e.g. "
+        f'Variant(X, fn="{hits[0].rsplit(".", 1)[0]}", {key}=…).'
+    )
+
+
+def variant_graph(db, variable_frame, functions: list[str] | None = None) -> dict:
+    """
+    Everything a variant picker needs for one variable.
+
+    Returns ``{"axes": [...], "versions": {fn: [...]}, "latest_column": ...}``:
+
+    ``axes``
+        One entry per variant column — ``kind``/``function``/``param`` from
+        :func:`~scistackplotdb.load.attach_variants`, plus the levels present.
+    ``versions``
+        Every recorded version of every function in this variable's upstream
+        chain, **including functions that have only ever had one**. Single
+        version functions are not an *axis* (they distinguish no two records),
+        but they are still a legitimate thing to pick a version of, and a
+        dropdown that omitted them would be empty for the common case.
+        ``functions`` adds further names to look up — the GUI passes every
+        function node on the canvas, so nodes outside this variable's chain can
+        still say what they have run.
+    """
+    from scidb.provenance_query import code_versions_batch, function_versions
+
+    frame = variable_frame.frame
+    record_ids = frame["record_id"].tolist() if "record_id" in frame.columns else []
+    chain: set[str] = set()
+    if record_ids:
+        for by_fn in code_versions_batch(db._duck, record_ids).values():
+            chain.update(by_fn)
+
+    wanted = sorted(chain | set(functions or ()))
+    versions = function_versions(db._duck, wanted) if wanted else {}
+
+    axes = []
+    for axis in variable_frame.variant_axes:
+        column = axis["column"]
+        levels = (
+            sorted(
+                {str(v) for v in frame[column].dropna().unique()},
+                key=natural_sort_key,
+            )
+            if column in frame.columns
+            else []
+        )
+        axes.append({**axis, "levels": levels})
+
+    Log.info(
+        "variant_graph(%s): %d axis/axes, versions for %d function(s) "
+        "(%d in this variable's chain)",
+        variable_frame.name,
+        len(axes),
+        len(versions),
+        len(chain),
+        layer=LAYER,
+    )
+    # Each axis in the vocabulary the PICKER has to match on. `param` here is the
+    # producing function's ARGUMENT name (scidb's `fn.param` namespacing) — not
+    # the name of the Parameter entity feeding it, which is what the canvas node
+    # is labelled with. The two coincide only until someone renames a Parameter
+    # or wires the port from a glue node, and when they stop coinciding the axis
+    # silently drops out of the graph. Logged so the popup's binding can be
+    # checked against what it was actually given.
+    for axis in axes:
+        Log.info(
+            "  axis %s: kind=%s function=%s param=%s, %d level(s) %s",
+            axis["column"],
+            axis["kind"],
+            axis["function"],
+            axis["param"],
+            len(axis["levels"]),
+            axis["levels"][:10],
+            layer=LAYER,
+        )
+    return {
+        "variable": variable_frame.name,
+        "axes": axes,
+        "versions": versions,
+        "chain_functions": sorted(chain),
+        "latest_column": variable_frame.latest_column or LATEST_COLUMN,
+    }

scistackplotdb-0.1.26.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: scistackplotdb
+Version: 0.1.26
+Summary: scidb-backed plotting: load variables into long tables and plot them with scistackplot
+Author: SciStack Contributors
+License-Expression: MIT
+Keywords: plotting,provenance,scidb,scistack,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: scistack-db>=0.1.0
+Requires-Dist: scistackplot>=0.1.0
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.6; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: seaborn>=0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scistackplotdb
+
+## Plot what's in the database
+
+`scistackplotdb` loads SciDB variables into the long format
+[`scistackplot`](../scistackplot/README.md) consumes, and generates pipeline
+endpoints from a finished plot spec.
+
+```bash
+pip install scistackplotdb
+```
+
+```python
+from scidb import configure_database
+from scistackplot import PlotSpec, Role, PlotKind, render
+from scistackplotdb import ScidbSource
+
+db = configure_database("experiment.duckdb", ["subject", "session", "trial"])
+source = ScidbSource(db)
+
+table = source.get_table(["StepLength"])
+spec = PlotSpec(
+    measures=["StepLength"],
+    roles={"session": Role.X, "subject": Role.FREE, "trial": Role.FREE},
+    kind=PlotKind.BOX,
+)
+figure = render(table, spec)
+```
+
+## What this layer actually solves
+
+The long format is nearly free — schema keys are already columns once a
+variable is joined to `_schema`, the same shape `stat_` functions receive. The
+real work is the four things a flat CSV never had.
+
+**Shape classification.** Scalar, 1-D, or 2-D, decided from observed values
+rather than declared SQL type names, and cached. It determines which plot kinds
+are offered at all.
+
+**Joins across schema depth.** Plotting trial-level `Speed` against
+subject-level `Mass` broadcasts the shallower variable down the hierarchy:
+
+```python
+source.joinable_with("StepLength")     # -> ["Mass"]  (Signal is 1-D: no x axis)
+table = source.get_table(["StepLength", "Mass"])   # one Mass value per trial row
+```
+
+Because the dataset schema is an ordered, contiguous hierarchy, one variable's
+levels are always a prefix of the other's or the two cannot be joined — and
+`join_frames` refuses the latter with a message saying why.
+
+**Variants are factors — this one is a correctness trap.** A variable produced
+at two filter cutoffs has *two records per schema combination*. Treating those
+branch params as ordinary columns silently plots two pipelines' results as if
+they were replicates of one:
+
+```python
+spec = PlotSpec(measures=["Scaled"], roles={"session": Role.X})
+validate(spec, table)
+# RoleError: Variant factor(s) ['scale.factor'] would be pooled: their levels
+# are different pipeline variants, not replicates... Assign them
+# 'color'/'facet'/'iterate', select the variants you want with
+# PlotSpec.variant_sets, or — to pool them deliberately — set them to
+# 'aggregate' or 'free' yourself.
+```
+
+**A transport budget.** 1-D data across hundreds of trials is megabytes.
+`resolve(..., max_points=N)` downsamples for the interactive panel; export
+never does.
+
+## From spec to pipeline endpoint
+
+```python
+from scistackplotdb import generate_endpoint
+
+code = generate_endpoint(spec, table, input_variable="StepLength")
+print(code.source)
+```
+
+```python
+def plot_steplength(df, filename):
+    ...
+    return g.figure
+
+for_each(
+    plot_steplength,
+    inputs={
+        "df": StepLength,
+        "filename": PathOutput("plots/steplength_{subject}.png"),
+    },
+    outputs=[StepLengthFigure],
+    as_table=['df'],
+    finalized=True,
+    subject=[],
+)
+```
+
+The one translation that has to be exactly right is `Role.ITERATE` → a
+`for_each` iteration keyword. Interactively, ITERATE fans out through a pandas
+`groupby`; in the pipeline it fans out through `for_each` + `PathOutput`. If
+those disagree, the exported pipeline is not what you previewed —
+`tests/test_fanout_parity.py` runs both paths against the same database and
+compares the figure sets.
+
+Everything about *recording* the figure — `finalized`, artifact stamping,
+`skip_computed`, `scidb report` — is SciDB's existing endpoint machinery and is
+untouched.
+
+## Ordering
+
+Factor levels are ordered by SciDB's declared `schema_key_types`, not by
+pandas' default: a key declared `numeric` sorts numerically, and everything
+else goes through a natural sort so zero-padded IDs land as
+`01, 02, … 10` instead of `01, 10, 02`.
+
+See [`docs/claude/plotting-library-design.md`](../docs/claude/plotting-library-design.md).

scistackplotdb-0.1.26.dist-info/RECORD

@@ -0,0 +1,9 @@
+scistackplotdb/__init__.py,sha256=EVqx9UIPTkru8YgQzmFx_RTq5EEY0Snt_5cLSVutGts,2125
+scistackplotdb/endpoint.py,sha256=HOr4wrC4Sv76IO28FwKqUup1V_spRVVS99kwMHpjo_c,9713
+scistackplotdb/hierarchy.py,sha256=AixJ7MZEYAiXGhx9C3Nh0Wv9osEjXkpmiZhvc0hWO4s,5281
+scistackplotdb/load.py,sha256=qerlIOLZIVKgXP-psIaNsiov1AfPrcl2Z8J1ZVyw4uQ,19844
+scistackplotdb/source.py,sha256=cY7mEW43SQAXLGvVC04Wwqu7T7fPzp-aROrbnVqgn_A,33855
+scistackplotdb/variants.py,sha256=F4k4fRUpo_LzawKsMj3ucT3HA_qROt5IKnikz7Dmfow,8982
+scistackplotdb-0.1.26.dist-info/METADATA,sha256=Ky5shScyDimYHlybNW8FEor5L5r6mG3iElX6_SqV9mI,4990
+scistackplotdb-0.1.26.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+scistackplotdb-0.1.26.dist-info/RECORD,,

scistackplotdb-0.1.26.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any