scistackplotdb 0.1.65__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scistackplotdb
3
- Version: 0.1.65
3
+ Version: 0.2.0
4
4
  Summary: scidb-backed plotting: load variables into long tables and plot them with scistackplot
5
5
  Author: SciStack Contributors
6
6
  License-Expression: MIT
@@ -17,10 +17,11 @@ Classifier: Programming Language :: Python :: 3.13
17
17
  Classifier: Topic :: Scientific/Engineering :: Visualization
18
18
  Classifier: Typing :: Typed
19
19
  Requires-Python: >=3.10
20
- Requires-Dist: sciduckdb==0.1.65
21
- Requires-Dist: scistack-db==0.1.65
22
- Requires-Dist: scistacklog==0.1.65
23
- Requires-Dist: scistackplot==0.1.65
20
+ Requires-Dist: sciduckdb==0.2.0
21
+ Requires-Dist: scifor==0.2.0
22
+ Requires-Dist: scistack-db==0.2.0
23
+ Requires-Dist: scistacklog==0.2.0
24
+ Requires-Dist: scistackplot==0.2.0
24
25
  Provides-Extra: dev
25
26
  Requires-Dist: matplotlib>=3.6; extra == 'dev'
26
27
  Requires-Dist: pytest-cov>=4.0; extra == 'dev'
@@ -94,6 +95,18 @@ validate(spec.with_roles(**{"scale.factor": Role.COLLAPSE}), table)
94
95
  # PlotSpec.variant_sets.
95
96
  ```
96
97
 
98
+ **Text fields are their own measure.** One melted value column holds one
99
+ shape, so a wide variable with numeric AND text fields is listed twice:
100
+ `Gait` (its numeric fields, one `ColName` level each) and `Gait (text)` (its
101
+ text fields), drawn as counts, %s or categories (`scistackplot`'s "Text
102
+ measures"). A variable whose fields are all text is itself the text measure.
103
+ `scistackplotdb.text_fields` owns the name (`base_variable("Gait (text)")`
104
+ is `"Gait"`, which is what a generated endpoint's `for_each` reads):
105
+
106
+ ```python
107
+ source.get_table(["Gait (text)"]) # Side, Outcome, ... melted under ColName
108
+ ```
109
+
97
110
  **A transport budget.** 1-D data across hundreds of trials is megabytes.
98
111
  `resolve(..., max_points=N)` downsamples for the interactive panel; export
99
112
  never does.
@@ -172,7 +185,7 @@ else goes through a natural sort so zero-padded IDs land as
172
185
  `01, 02, … 10` instead of `01, 10, 02`.
173
186
 
174
187
  A project that declares its levels (`[schema_keys]` in scistack.toml, read by
175
- `scidb.schema_order`) wins over both: declared levels first, in that order,
188
+ `scifor.project.schema_order`) wins over both: declared levels first, in that order,
176
189
  the rest after them by the rule above. The declaration is read live, and a
177
190
  change drops the source's built tables, so an edit shows on the next plot
178
191
  request. Exported seaborn code states every order it relies on (`order=`,
@@ -64,6 +64,18 @@ validate(spec.with_roles(**{"scale.factor": Role.COLLAPSE}), table)
64
64
  # PlotSpec.variant_sets.
65
65
  ```
66
66
 
67
+ **Text fields are their own measure.** One melted value column holds one
68
+ shape, so a wide variable with numeric AND text fields is listed twice:
69
+ `Gait` (its numeric fields, one `ColName` level each) and `Gait (text)` (its
70
+ text fields), drawn as counts, %s or categories (`scistackplot`'s "Text
71
+ measures"). A variable whose fields are all text is itself the text measure.
72
+ `scistackplotdb.text_fields` owns the name (`base_variable("Gait (text)")`
73
+ is `"Gait"`, which is what a generated endpoint's `for_each` reads):
74
+
75
+ ```python
76
+ source.get_table(["Gait (text)"]) # Side, Outcome, ... melted under ColName
77
+ ```
78
+
67
79
  **A transport budget.** 1-D data across hundreds of trials is megabytes.
68
80
  `resolve(..., max_points=N)` downsamples for the interactive panel; export
69
81
  never does.
@@ -142,7 +154,7 @@ else goes through a natural sort so zero-padded IDs land as
142
154
  `01, 02, … 10` instead of `01, 10, 02`.
143
155
 
144
156
  A project that declares its levels (`[schema_keys]` in scistack.toml, read by
145
- `scidb.schema_order`) wins over both: declared levels first, in that order,
157
+ `scifor.project.schema_order`) wins over both: declared levels first, in that order,
146
158
  the rest after them by the rule above. The declaration is read live, and a
147
159
  change drops the source's built tables, so an edit shows on the next plot
148
160
  request. Exported seaborn code states every order it relies on (`order=`,
@@ -12,7 +12,7 @@ raw-options = { search_parent_directories = true, local_scheme = "no-local-versi
12
12
  # dependencies must be named here: CI's build job fails a wheel whose internal
13
13
  # dependency is not "==<its own version>".
14
14
  [tool.hatch.metadata.hooks.dependency-coversion]
15
- override-versions-of = ["scistackplot", "scistack-db", "sciduckdb", "scistacklog"]
15
+ override-versions-of = ["scistackplot", "scistack-db", "sciduckdb", "scifor", "scistacklog"]
16
16
 
17
17
  [project]
18
18
  name = "scistackplotdb"
@@ -48,6 +48,7 @@ dependencies = [
48
48
  "scistackplot",
49
49
  "scistack-db",
50
50
  "sciduckdb",
51
+ "scifor",
51
52
  "scistacklog",
52
53
  ]
53
54
 
@@ -65,6 +65,7 @@ from .saved import (
65
65
  save_plot,
66
66
  saved_plot_history,
67
67
  )
68
+ from .designs import DesignError, StoredDesign, apply_design, is_linked, link_design, load_design, save_design
68
69
  from .presets import (
69
70
  AppliedPreset,
70
71
  Preset,
@@ -82,6 +83,7 @@ from .presets import (
82
83
  save_preset,
83
84
  )
84
85
  from .source import ScidbSource
86
+ from .text_fields import TEXT_SUFFIX, base_variable, is_text_measure, text_measure_name
85
87
  from .variants import (
86
88
  branch_params_for,
87
89
  selection_for,
@@ -90,7 +92,19 @@ from .variants import (
90
92
  )
91
93
 
92
94
  __all__ = [
95
+ "DesignError",
96
+ "StoredDesign",
97
+ "apply_design",
98
+ "is_linked",
99
+ "link_design",
100
+ "load_design",
101
+ "save_design",
93
102
  "ScidbSource",
103
+ # a wide variable's text fields as their own measure
104
+ "TEXT_SUFFIX",
105
+ "base_variable",
106
+ "is_text_measure",
107
+ "text_measure_name",
94
108
  # saved plots
95
109
  "save_plot",
96
110
  "list_saved_plots",
@@ -1,5 +1,5 @@
1
1
  """
2
- The ``plots`` section of a project bundle (``scidb.bundle``): saved plots and
2
+ The ``plots`` section of a project bundle (``scidb.project.bundle``): saved plots and
3
3
  plot presets, copied row for row.
4
4
 
5
5
  Both stores key nothing by canvas ids or database record ids -- a saved plot
@@ -15,11 +15,16 @@ import json
15
15
 
16
16
  from scistacklog import Log
17
17
 
18
- from . import presets, saved
18
+ from . import designs, presets, saved
19
19
 
20
20
  LAYER = "scistackplotdb"
21
21
 
22
- _STORES = {"saved_plots.json": saved.STORE, "presets.json": presets.STORE}
22
+ _STORES = {
23
+ "saved_plots.json": saved.STORE,
24
+ "presets.json": presets.STORE,
25
+ # The shared design of a linked figure + table (designs.py).
26
+ "designs.json": designs.STORE,
27
+ }
23
28
 
24
29
 
25
30
  class PlotsSection:
@@ -41,19 +46,7 @@ class PlotsSection:
41
46
  if filename in files:
42
47
  rows = json.loads(files[filename].decode("utf-8"))
43
48
  if key_map is not None and not key_map.is_identity:
44
- rows = [_remap_row(row, store, key_map, ctx.map_report) for row in rows]
49
+ rows = [store.remap_row(row, key_map, ctx.map_report) for row in rows]
45
50
  report[store.table] = store.load_rows(ctx.db, rows)
46
51
  Log.info("[bundle_section] plots import: %s", report, layer=LAYER)
47
52
  return report
48
-
49
-
50
- def _remap_row(row: dict, store, key_map, map_report) -> dict:
51
- """A saved plot or preset carried into another schema (portability Stage
52
- 6). A spec names factors in many fields (roles, groups, facets, colours,
53
- filters, difference bars, ...), so every string EQUAL to an exporter key
54
- is renamed (``KeyMap.exact_strings``) and the item is flagged for review
55
- -- a factor that merely equals a key name cannot be told apart."""
56
- envelope = json.loads(row["envelope_json"])
57
- where = f"{store.noun} {row.get('name')!r}"
58
- mapped = key_map.exact_strings(envelope, where, map_report)
59
- return {**row, "envelope_json": json.dumps(mapped)}
@@ -0,0 +1,148 @@
1
+ """
2
+ The shared design of a linked figure and table: one owner
3
+ (docs/claude/studio-unification.md, user decision 2026-11-01).
4
+
5
+ A saved plot and the StatStudio tables linked to it used to each keep their
6
+ own copy of the design, with "Sync to…" banners to copy one onto the other.
7
+ Now the design of a linked pair lives in ONE row set here, keyed by the
8
+ saved plot's ``plot_id``. Either studio writes it; both read it on open, and
9
+ an edit in one reaches the other through the GUI's broadcast.
10
+
11
+ What the design is, field by field, is still
12
+ :data:`scistackplot.model.design.DESIGN_FIELDS`. This store keeps a whole
13
+ ``PlotSpec`` dict (so it reads back through ``restore_spec``) but only its
14
+ design fields are ever applied (:func:`apply_design`, through
15
+ ``copy_design``). Display settings stay with each artifact.
16
+
17
+ **A design exists only once something is linked.** :func:`link_design` is
18
+ called when a StatStudio table is set up from a saved plot. An unlinked plot
19
+ has no row here and its saved envelope stays the owner of its design.
20
+
21
+ Rows are the shared ``VersionedStore`` (append-only, never deleted): the
22
+ item's NAME is the plot id, so "the design of plot X" is a name lookup, and
23
+ each change is a new version. A write that would not change the design
24
+ (same ``design_fingerprint``) appends nothing.
25
+ """
26
+
27
+ from __future__ import annotations
28
+
29
+ from dataclasses import dataclass
30
+ from typing import Any
31
+
32
+ from scistacklog import Log
33
+
34
+ from scidb.store.versioned_store import VersionedStore
35
+
36
+ LAYER = "scistackplotdb"
37
+
38
+ TABLE = "_plot_design"
39
+
40
+ ENVELOPE_FORMAT = 1
41
+
42
+
43
+ class DesignError(ValueError):
44
+ """A design that cannot be stored or read as asked."""
45
+
46
+
47
+ STORE = VersionedStore(
48
+ table=TABLE,
49
+ id_column="design_id",
50
+ scope_column=None,
51
+ noun="shared design",
52
+ tag="design",
53
+ error=DesignError,
54
+ owner="scistackplotdb",
55
+ )
56
+
57
+
58
+ @dataclass(frozen=True)
59
+ class StoredDesign:
60
+ plot_id: str
61
+ design_id: str
62
+ version: int
63
+ #: The stored spec (a full PlotSpec; only its design fields apply).
64
+ spec: Any
65
+ fingerprint: str
66
+
67
+
68
+ def _row_for(db, plot_id: str):
69
+ if not plot_id:
70
+ return None
71
+ return STORE.visible_by_name(db, None, plot_id)
72
+
73
+
74
+ def load_design(db, plot_id: str) -> StoredDesign | None:
75
+ """The newest shared design of saved plot *plot_id*, or None when it is
76
+ not linked to anything (or the row cannot be read)."""
77
+ from scistackplot import restore_spec
78
+ from scistackplot.model.design import design_fingerprint
79
+
80
+ row = _row_for(db, plot_id)
81
+ if row is None:
82
+ return None
83
+ _, text = STORE.load(db, row[0])
84
+ envelope = STORE.parse_envelope(text, f"design of {plot_id[:8]}")
85
+ raw = envelope.get("spec")
86
+ if not isinstance(raw, dict):
87
+ Log.warn("[design] %s: stored design has no spec; ignoring it", plot_id[:8], layer=LAYER)
88
+ return None
89
+ restored = restore_spec(raw, fallback_measure=(raw.get("measures") or [None])[0])
90
+ for note in restored.notes:
91
+ Log.info("[design] %s: restore note: %s", plot_id[:8], getattr(note, "message", note), layer=LAYER)
92
+ spec = restored.spec
93
+ return StoredDesign(plot_id, row[0], row[3], spec, design_fingerprint(spec))
94
+
95
+
96
+ def is_linked(db, plot_id: str | None) -> bool:
97
+ return bool(plot_id) and _row_for(db, plot_id) is not None
98
+
99
+
100
+ def save_design(db, plot_id: str, spec) -> tuple[StoredDesign, bool]:
101
+ """Write *spec*'s design as the shared design of *plot_id*.
102
+
103
+ Returns ``(stored, changed)``. When the design fields are the same as
104
+ the newest stored version, nothing is appended and ``changed`` is
105
+ False, so a broadcast echo between two open studios stops here.
106
+ """
107
+ from scistackplot.model.design import design_fingerprint
108
+
109
+ if not plot_id:
110
+ raise DesignError("A shared design needs the saved plot it belongs to.")
111
+ fingerprint = design_fingerprint(spec)
112
+ current = load_design(db, plot_id)
113
+ if current is not None and current.fingerprint == fingerprint:
114
+ Log.debug("[design] %s: unchanged (fingerprint %s); nothing appended", plot_id[:8], fingerprint,
115
+ layer=LAYER)
116
+ return current, False
117
+ envelope = {"format": ENVELOPE_FORMAT, "plot_id": plot_id, "spec": spec.to_dict()}
118
+ row, is_new = STORE.save(db, None, plot_id, envelope, overwrite=True, current_id=None,
119
+ on_clash=lambda r: DesignError(f"design clash for {plot_id}"))
120
+ Log.info("[design] %s: %s version %d (fingerprint %s)", plot_id[:8],
121
+ "linked, first" if is_new else "changed, new", row[3], fingerprint, layer=LAYER)
122
+ return StoredDesign(plot_id, row[0], row[3], spec, fingerprint), True
123
+
124
+
125
+ def link_design(db, plot_id: str, spec) -> StoredDesign:
126
+ """Make *plot_id*'s design shared, starting from *spec* when nothing is
127
+ stored yet. An already-linked plot keeps its stored design."""
128
+ current = load_design(db, plot_id)
129
+ if current is not None:
130
+ Log.info("[design] %s: already linked (version %d)", plot_id[:8], current.version, layer=LAYER)
131
+ return current
132
+ stored, _ = save_design(db, plot_id, spec)
133
+ return stored
134
+
135
+
136
+ def apply_design(db, plot_id: str | None, spec) -> tuple[Any, list, int | None]:
137
+ """*spec* with the shared design of *plot_id* copied onto it
138
+ (``copy_design``: design fields only, display kept). Unchanged, with
139
+ version None, when *plot_id* is not linked."""
140
+ from scistackplot.model.design import copy_design
141
+
142
+ stored = load_design(db, plot_id) if plot_id else None
143
+ if stored is None:
144
+ return spec, [], None
145
+ merged, notes = copy_design(stored.spec, spec)
146
+ Log.info("[design] %s: applied version %d onto a %s spec (%d note(s))", plot_id[:8], stored.version,
147
+ getattr(spec.kind, "value", spec.kind), len(notes), layer=LAYER)
148
+ return merged, notes, stored.version
@@ -2,7 +2,7 @@
2
2
  Turning a ``PlotSpec`` into a pipeline endpoint.
3
3
 
4
4
  The GUI's "Add to pipeline" produces two things: a ``plot_`` function (generated
5
- by ``scistackplot.codegen`` — literal seaborn, no runtime dependency on this
5
+ by ``scistackplot.export.codegen`` — literal seaborn, no runtime dependency on this
6
6
  package) and the ``for_each`` call that runs it. This module owns the second
7
7
  half, and with it the one translation that has to be exactly right:
8
8
 
@@ -26,11 +26,12 @@ from dataclasses import dataclass, field
26
26
  from scistacklog import Log
27
27
  from scistackplot import LongTable, PlotSpec, default_function_name
28
28
  from scistackplot import generate_plot_function
29
- from scistackplot.codegen import group_param, variant_params
30
- from scistackplot.roles import fanout_keys
31
- from scistackplot.variants import defined_sets
29
+ from scistackplot.export.codegen import group_param, variant_params
30
+ from scistackplot.model.roles import fanout_keys
31
+ from scistackplot.reduce.variants import defined_sets
32
32
 
33
33
  from .load import LATEST_COLUMN
34
+ from .text_fields import base_variable
34
35
 
35
36
  LAYER = "scistackplotdb"
36
37
 
@@ -69,6 +70,9 @@ def generate_endpoint(
69
70
  ``input_variable`` is the scidb variable type supplying the data;
70
71
  ``x_variable`` is the optional second measure for an x–y scatter.
71
72
  """
73
+ # A text measure (`Gait (text)`) is its variable's text fields: the
74
+ # for_each input is the variable, and the plot function melts the fields.
75
+ input_variable = base_variable(input_variable)
72
76
  name = function_name or default_function_name(spec)
73
77
  # NOT spec.iterate_factors: the fan-out includes schema keys promoted
74
78
  # because a nested key iterates, and runs in schema order. The preview and
@@ -143,7 +147,7 @@ def _pin_literal(value) -> str:
143
147
 
144
148
  def row_expression(input_variable: str, variant_set, table=None) -> str:
145
149
  """One variant ROW as a ``Variant(...)`` load — through the row's
146
- EFFECTIVE selection (``scistackplot.variants.export_selection``), so the
150
+ EFFECTIVE selection (``scistackplot.reduce.variants.export_selection``), so the
147
151
  exported code loads what the preview drew: current code for a row that
148
152
  names none, the frozen version for a reopened saved plot.
149
153
 
@@ -152,7 +156,7 @@ def row_expression(input_variable: str, variant_set, table=None) -> str:
152
156
  """
153
157
  from types import SimpleNamespace
154
158
 
155
- from scistackplot.variants import export_selection
159
+ from scistackplot.reduce.variants import export_selection
156
160
 
157
161
  # The TABLE's default, exactly what the preview applied: a table with
158
162
  # none (nothing superseded) exports its rows as written.
@@ -177,7 +181,7 @@ def variant_expression(input_variable: str, variant_set) -> str:
177
181
 
178
182
  Variant(Variant(EMG, fn="loadEMG", code_version="v1"), fn="bandpass", low_hz=20)
179
183
 
180
- Nesting is documented, merges the two filters (``scidb.variant.Variant``
184
+ Nesting is documented, merges the two filters (``scidb.model.variant.Variant``
181
185
  handles it explicitly), and keeps every keyword readable — where
182
186
  ``**{"__code__.loadEMG": "v1"}`` would leak a reserved namespace into code a
183
187
  user is meant to edit.