scistackplot 0.4.1__tar.gz → 0.4.3__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.
Files changed (66) hide show
  1. {scistackplot-0.4.1 → scistackplot-0.4.3}/PKG-INFO +3 -3
  2. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/__init__.py +13 -1
  3. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/export/codegen.py +9 -0
  4. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/export/custom.py +3 -0
  5. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/capability.py +20 -2
  6. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/design.py +6 -0
  7. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/presets.py +5 -0
  8. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/spec.py +24 -1
  9. scistackplot-0.4.3/src/scistackplot/model/where_check.py +158 -0
  10. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/diffbars.py +153 -3
  11. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/resolve.py +8 -0
  12. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/render/base.py +29 -0
  13. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/render/mpl.py +28 -7
  14. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/render/plotly_.py +40 -5
  15. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/sources/base.py +12 -2
  16. {scistackplot-0.4.1 → scistackplot-0.4.3}/.gitignore +0 -0
  17. {scistackplot-0.4.1 → scistackplot-0.4.3}/README.md +0 -0
  18. {scistackplot-0.4.1 → scistackplot-0.4.3}/pyproject.toml +0 -0
  19. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/export/__init__.py +0 -0
  20. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/export/figure_file.py +0 -0
  21. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/export/plot_data.py +0 -0
  22. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/export/reduction_code.py +0 -0
  23. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/__init__.py +0 -0
  24. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/restore.py +0 -0
  25. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/role_labels.py +0 -0
  26. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/roles.py +0 -0
  27. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/shape.py +0 -0
  28. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/model/table.py +0 -0
  29. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/__init__.py +0 -0
  30. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/bins.py +0 -0
  31. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/categorical.py +0 -0
  32. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/cell.py +0 -0
  33. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/chain.py +0 -0
  34. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/compare.py +0 -0
  35. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/fits.py +0 -0
  36. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/groups.py +0 -0
  37. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/kde.py +0 -0
  38. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/numeric.py +0 -0
  39. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/omissions.py +0 -0
  40. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/panels.py +0 -0
  41. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/reducer.py +0 -0
  42. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/reduction.py +0 -0
  43. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/resolved.py +0 -0
  44. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/series_stats.py +0 -0
  45. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/spaghetti.py +0 -0
  46. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/spread.py +0 -0
  47. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/stacking.py +0 -0
  48. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/temporal.py +0 -0
  49. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/variants.py +0 -0
  50. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/weights.py +0 -0
  51. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/reduce/ylimits.py +0 -0
  52. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/render/__init__.py +0 -0
  53. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/sources/__init__.py +0 -0
  54. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/sources/csv.py +0 -0
  55. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/sources/dedup.py +0 -0
  56. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/sources/frame.py +0 -0
  57. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/__init__.py +0 -0
  58. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/aliases.py +0 -0
  59. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/autosize.py +0 -0
  60. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/colors.py +0 -0
  61. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/figsize.py +0 -0
  62. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/framesize.py +0 -0
  63. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/paper.py +0 -0
  64. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/textsize.py +0 -0
  65. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/ticklabels.py +0 -0
  66. {scistackplot-0.4.1 → scistackplot-0.4.3}/src/scistackplot/text/xaxis.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scistackplot
3
- Version: 0.4.1
3
+ Version: 0.4.3
4
4
  Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
5
5
  Author: SciStack Contributors
6
6
  License-Expression: MIT
@@ -20,8 +20,8 @@ Requires-Python: >=3.10
20
20
  Requires-Dist: csv-stats>=0.5.0
21
21
  Requires-Dist: numpy>=1.21
22
22
  Requires-Dist: pandas>=1.5
23
- Requires-Dist: scicanonicalhash==0.4.1
24
- Requires-Dist: scistacklog==0.4.1
23
+ Requires-Dist: scicanonicalhash==0.4.3
24
+ Requires-Dist: scistacklog==0.4.3
25
25
  Provides-Extra: dev
26
26
  Requires-Dist: matplotlib>=3.6; extra == 'dev'
27
27
  Requires-Dist: plotly>=5.0; extra == 'dev'
@@ -118,7 +118,15 @@ from .export.custom import (
118
118
  resolve_custom,
119
119
  resolve_custom_one,
120
120
  )
121
- from .reduce.diffbars import DifferenceBar, bars_for_panel, slot_endpoints
121
+ from .reduce.diffbars import (
122
+ Derived,
123
+ DifferenceBar,
124
+ PanelNote,
125
+ StatMarks,
126
+ bars_for_panel,
127
+ slot_endpoints,
128
+ with_derived,
129
+ )
122
130
  from .reduce.panels import PanelOverride, override_for
123
131
  from .model.shape import Shape, classify_column, classify_value, is_plottable
124
132
  from .sources import BaseSource, CsvSource, DataFrameSource, DataSource, UnknownMeasureError
@@ -297,7 +305,11 @@ __all__ = [
297
305
  "custom_preview",
298
306
  "resolve_custom",
299
307
  "resolve_custom_one",
308
+ "Derived",
300
309
  "DifferenceBar",
310
+ "PanelNote",
311
+ "StatMarks",
312
+ "with_derived",
301
313
  "bars_for_panel",
302
314
  "slot_endpoints",
303
315
  "eligible_scope",
@@ -186,6 +186,15 @@ def generate_plot_function(
186
186
  settle it (``autosize.settle`` at the spec's size), and the chosen sizes
187
187
  are emitted as literals: the generated code does not search.
188
188
  """
189
+ if spec.where_check:
190
+ # The check's factors are attached by the source and are not mirrored
191
+ # here (synthetic-factors invariant 4): the function would draw a
192
+ # different figure from the one on screen. `capabilities` says so too.
193
+ raise ValueError(
194
+ "A where= check cannot be exported as code: its Yes/No factors are "
195
+ "not part of the exported function. Apply the filter to the node, "
196
+ "then plot normally."
197
+ )
189
198
  auto, note = _export_auto(spec, table)
190
199
  token = _EXPORT_AUTO.set(auto.reference if auto is not None else None)
191
200
  try:
@@ -51,6 +51,7 @@ import pandas as pd
51
51
 
52
52
  from scistacklog import Log
53
53
 
54
+ from ..reduce.diffbars import StatMarks
54
55
  from ..reduce.groups import apply_level_groups
55
56
  from ..model.roles import (
56
57
  CollapseSteps,
@@ -250,6 +251,8 @@ def _input_spec(spec: PlotSpec, variable: str, primary_variable: str, kind: Plot
250
251
  sample_color=None,
251
252
  comparison=None,
252
253
  difference_bars=[],
254
+ stat_marks=StatMarks(),
255
+ derived=None,
253
256
  )
254
257
 
255
258
 
@@ -548,6 +548,18 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
548
548
  # and the depth picker's choices with the header each would write —
549
549
  # the same answer `export.plot_data` validates against.
550
550
  "data_export": data_export_options(spec, roles, collapsed, shape).to_dict(),
551
+ # "Export code" and "Add to pipeline": a where= check's factors are built
552
+ # by the source and are not mirrored in codegen, so the generated
553
+ # function would draw a different figure (synthetic-factors invariant 4).
554
+ "code_export": {
555
+ "available": not spec.where_check,
556
+ "reason": (
557
+ "A where= check is for looking: its Yes/No factors are not part of "
558
+ "the exported function. Apply the filter to the node, then plot normally."
559
+ if spec.where_check
560
+ else None
561
+ ),
562
+ },
551
563
  "default": str(
552
564
  default_plot(
553
565
  raw_shape if categorical else shape,
@@ -761,10 +773,16 @@ def regression_summary(spec: PlotSpec, table: LongTable) -> dict:
761
773
 
762
774
 
763
775
  def _difference_bars_summary(spec: PlotSpec, shape: Shape, temporal: bool = False) -> dict:
764
- from ..reduce.diffbars import unavailable
776
+ from ..reduce.diffbars import STAT_LABELS, STAT_PAIRS, unavailable
765
777
 
766
778
  reason = unavailable(spec, shape, temporal=temporal)
767
- return {"available": reason is None, "reason": reason}
779
+ # The stat_marks vocabulary rides here, so Plot Studio holds none of its own.
780
+ return {
781
+ "available": reason is None,
782
+ "reason": reason,
783
+ "stat_pairs": list(STAT_PAIRS),
784
+ "stat_labels": list(STAT_LABELS),
785
+ }
768
786
 
769
787
 
770
788
  def sample_overlay_summary(
@@ -97,6 +97,10 @@ DESIGN_FIELDS: dict[str, SyncClass] = {
97
97
  "colors": _P,
98
98
  "panel_overrides": _P,
99
99
  "difference_bars": _P,
100
+ # Which results the figure draws: display. The facts are handed in per
101
+ # resolve and never stored (`derived`).
102
+ "stat_marks": _P,
103
+ "derived": _P,
100
104
  # Compare-to-reference changes the values themselves.
101
105
  "comparison": _D,
102
106
  # A datetime's wall clock depends on the zone it is read in, so a
@@ -106,6 +110,7 @@ DESIGN_FIELDS: dict[str, SyncClass] = {
106
110
  "location_filter": _D,
107
111
  "factor_variables": _D,
108
112
  "level_groups": _D,
113
+ "where_check": _D,
109
114
  }
110
115
 
111
116
  #: What the banner calls each design field.
@@ -125,6 +130,7 @@ LABELS: dict[str, str] = {
125
130
  "location_filter": "Schema locations",
126
131
  "factor_variables": "Joined factors",
127
132
  "level_groups": "Combines",
133
+ "where_check": "where= check",
128
134
  }
129
135
 
130
136
 
@@ -153,11 +153,16 @@ FIELD_CLASSES: dict[str, FieldClass] = {
153
153
  "panel_overrides[].y_label": _V,
154
154
  "panel_overrides[].y_label_hidden": _T,
155
155
  "difference_bars": _T,
156
+ "stat_marks": _T,
157
+ # Handed in per resolve, never stored: no preset carries it.
158
+ "derived": _D,
156
159
  "comparison": _T,
157
160
  "filters": _T,
158
161
  "location_filter": _T,
159
162
  "factor_variables": _R,
160
163
  "level_groups": _T,
164
+ # A look at a node's filters, never stored with a preset.
165
+ "where_check": _D,
161
166
  }
162
167
 
163
168
  #: Blocks classified field by field rather than as a whole.
@@ -20,8 +20,9 @@ from enum import Enum
20
20
  from typing import Any
21
21
 
22
22
  from ..reduce.compare import Comparison
23
- from ..reduce.diffbars import DifferenceBar
23
+ from ..reduce.diffbars import DifferenceBar, Derived, StatMarks
24
24
  from ..reduce.panels import Y_TITLES_EVERY_PANEL, PanelOverride
25
+ from .where_check import WhereCheck
25
26
 
26
27
 
27
28
  class Role(str, Enum):
@@ -1568,6 +1569,14 @@ class PlotSpec:
1568
1569
  #: panel. One that resolves nowhere is kept and does nothing.
1569
1570
  #: ``diffbars`` is the one owner (.claude/plan-difference-bars.md).
1570
1571
  difference_bars: list[DifferenceBar] = field(default_factory=list)
1572
+ #: Which statistical results the figure draws (brackets, per-panel omnibus
1573
+ #: lines, a caption). Display only: the REQUEST, never the numbers. The
1574
+ #: facts come from a layer above through `diffbars.with_derived`.
1575
+ stat_marks: StatMarks = field(default_factory=StatMarks)
1576
+ #: Facts handed in for ONE resolve (`diffbars.with_derived`): panel notes
1577
+ #: and the caption. Never stored: callers save the spec they started from.
1578
+ #: `to_dict` writes it only when set, so a request payload can carry it.
1579
+ derived: Derived | None = None
1571
1580
  #: Compare to reference: the measure re-expressed relative to one level of
1572
1581
  #: a grouping layer, as a difference or a % change. None = raw values.
1573
1582
  #: Inert (drawn raw, reason reported) when it cannot apply; `compare` is
@@ -1588,6 +1597,9 @@ class PlotSpec:
1588
1597
  #: Combines: factors derived by combining another factor's levels, each
1589
1598
  #: replacing its source while active (:class:`LevelGroup`).
1590
1599
  level_groups: list[LevelGroup] = field(default_factory=list)
1600
+ #: A where= check: Yes/No factors from a node's filters, attached at the
1601
+ #: source (:mod:`.where_check`). None = an ordinary figure.
1602
+ where_check: WhereCheck | None = None
1591
1603
  #: Named variants to plot — one entry per row of the GUI's Variants section.
1592
1604
  #:
1593
1605
  #: One entry is a pin: the figure shows that variant and nothing else.
@@ -1736,12 +1748,20 @@ class PlotSpec:
1736
1748
  raw["location_filter"] = self.location_filter.to_dict()
1737
1749
  raw["variant_sets"] = [s.to_dict() for s in self.variant_sets]
1738
1750
  raw["level_groups"] = [g.to_dict() for g in self.level_groups]
1751
+ raw["where_check"] = self.where_check.to_dict() if self.where_check else None
1739
1752
  raw["factor_variables"] = [f.to_dict() for f in self.factor_variables]
1740
1753
  raw["groups"] = list(self.groups)
1741
1754
  raw["show_sample"] = list(self.show_sample)
1742
1755
  raw["aliases"] = {thing: alias.to_dict() for thing, alias in self.aliases.items()}
1743
1756
  raw["panel_overrides"] = [o.to_dict() for o in self.panel_overrides]
1744
1757
  raw["difference_bars"] = [b.to_dict() for b in self.difference_bars]
1758
+ raw["stat_marks"] = self.stat_marks.to_dict()
1759
+ # Only a spec handed facts for one resolve (`diffbars.with_derived`)
1760
+ # carries them: the request payload is how they reach the resolve.
1761
+ # Callers save the spec they started from, which has none.
1762
+ raw["derived"] = self.derived.to_dict() if self.derived is not None else None
1763
+ if raw["derived"] is None:
1764
+ del raw["derived"]
1745
1765
  raw["comparison"] = self.comparison.to_dict() if self.comparison else None
1746
1766
  raw["custom"] = self.custom.to_dict() if self.custom else None
1747
1767
  # Unset text tables are absent, as unset sizes are (null-dropped), so a
@@ -1800,6 +1820,8 @@ class PlotSpec:
1800
1820
  difference_bars=[
1801
1821
  DifferenceBar.from_dict(b) for b in (raw.get("difference_bars") or [])
1802
1822
  ],
1823
+ stat_marks=StatMarks.from_dict(raw.get("stat_marks")),
1824
+ derived=Derived.from_dict(raw["derived"]) if raw.get("derived") else None,
1803
1825
  comparison=(
1804
1826
  Comparison.from_dict(raw["comparison"]) if raw.get("comparison") else None
1805
1827
  ),
@@ -1815,6 +1837,7 @@ class PlotSpec:
1815
1837
  variant_sets=[
1816
1838
  VariantSet.from_dict(s) for s in (raw.get("variant_sets") or [])
1817
1839
  ],
1840
+ where_check=WhereCheck.from_dict(raw.get("where_check")),
1818
1841
  )
1819
1842
 
1820
1843
  def to_json(self, *, indent: int | None = 2) -> str:
@@ -0,0 +1,158 @@
1
+ """A ``where=`` check: Yes/No factors on the rows of an ordinary figure.
2
+
3
+ A node's ``where=`` filters decide which locations its function runs on.
4
+ Seeing why a location is in or out is a figure question: *this* variable, at
5
+ *these* locations, passes or fails *this* comparison. So a check is not a
6
+ second screen. It is an ordinary figure whose table carries extra factor
7
+ columns, drawn by the same renderers, coloured and faceted by the same roles:
8
+
9
+ * :data:`MATCHING_FACTOR` -- Yes when every ENABLED filter passes, No when one
10
+ fails, "No value" when none failed but one could not be answered;
11
+ * one factor per filter (``Filter 1``, ``Filter 2``, by position) when
12
+ there are two or more, with the levels Yes / No / "No value".
13
+
14
+ **Who owns what.** scidb owns the verdict (``scidb.model.filters.
15
+ filter_report``); the source (``scistackplotdb.source``) joins it onto the
16
+ rows; this module owns only the NAMES and LEVELS those columns carry and the
17
+ spec field that asks for them. Nothing downstream reads a flag: the columns
18
+ are ordinary categorical factors by the time ``validate`` sees them
19
+ (synthetic-factors invariant 1).
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ from dataclasses import dataclass
25
+ from typing import Any
26
+
27
+ #: The factor holding the verdict of all enabled filters together.
28
+ MATCHING_FACTOR = "Matching"
29
+
30
+ LEVEL_YES = "Yes"
31
+ LEVEL_NO = "No"
32
+ LEVEL_NO_VALUE = "No value"
33
+
34
+ #: Declared level order of every check factor.
35
+ LEVEL_ORDER: tuple[str, ...] = (LEVEL_YES, LEVEL_NO, LEVEL_NO_VALUE)
36
+
37
+ #: The opening colours of a check (level -> colour), the same on every check
38
+ #: so the colours mean one thing. Green / red / grey.
39
+ CHECK_COLORS: dict[str, str] = {
40
+ LEVEL_YES: "#2e9e5b",
41
+ LEVEL_NO: "#d6453d",
42
+ LEVEL_NO_VALUE: "#9aa0a6",
43
+ }
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class WhereCheckFilter:
48
+ """One filter row of a check: the node's dict form plus a tick.
49
+
50
+ ``enabled`` False keeps the row on screen (and as a factor) but leaves it
51
+ out of :data:`MATCHING_FACTOR`: the tick box explores a filter's effect
52
+ without deleting it.
53
+ """
54
+
55
+ variable: str
56
+ column: str | None = None
57
+ op: str = "=="
58
+ value: str = ""
59
+ enabled: bool = True
60
+
61
+ def to_dict(self) -> dict:
62
+ return {
63
+ "variable": self.variable,
64
+ "column": self.column,
65
+ "op": self.op,
66
+ "value": self.value,
67
+ "enabled": self.enabled,
68
+ }
69
+
70
+ @classmethod
71
+ def from_dict(cls, raw: dict) -> "WhereCheckFilter":
72
+ value = raw.get("value")
73
+ return cls(
74
+ variable=str(raw.get("variable") or ""),
75
+ column=(str(raw["column"]) if raw.get("column") else None),
76
+ op=str(raw.get("op") or "=="),
77
+ value="" if value is None else str(value),
78
+ enabled=bool(raw.get("enabled", True)),
79
+ )
80
+
81
+ def filter_dict(self) -> dict:
82
+ """The scidb filter dict (``filter_from_dict``) without the tick."""
83
+ return {
84
+ "variable": self.variable,
85
+ "column": self.column,
86
+ "op": self.op,
87
+ "value": self.value,
88
+ }
89
+
90
+
91
+ @dataclass(frozen=True)
92
+ class WhereCheck:
93
+ """``PlotSpec.where_check``: the filters a figure is checking, and the
94
+ function node they belong to (where Apply writes them back).
95
+
96
+ Frozen and hashable: ``BaseSource.get_table`` memoizes on it.
97
+ """
98
+
99
+ node_id: str | None = None
100
+ filters: tuple[WhereCheckFilter, ...] = ()
101
+ #: The function's name, for the banner only; nothing reads it back.
102
+ function_name: str | None = None
103
+
104
+ def __post_init__(self) -> None:
105
+ # The restore walk keeps a tuple-typed field as stored (a list of
106
+ # dicts); the class decides, like FactorVariable.variant.
107
+ rows = tuple(
108
+ f if isinstance(f, WhereCheckFilter) else WhereCheckFilter.from_dict(f)
109
+ for f in self.filters
110
+ )
111
+ object.__setattr__(self, "filters", rows)
112
+
113
+ def __bool__(self) -> bool:
114
+ return bool(self.filters)
115
+
116
+ @property
117
+ def enabled(self) -> tuple[WhereCheckFilter, ...]:
118
+ return tuple(f for f in self.filters if f.enabled)
119
+
120
+ def to_dict(self) -> dict:
121
+ return {
122
+ "node_id": self.node_id,
123
+ "function_name": self.function_name,
124
+ "filters": [f.to_dict() for f in self.filters],
125
+ }
126
+
127
+ @classmethod
128
+ def from_dict(cls, raw: "dict | None") -> "WhereCheck | None":
129
+ if not raw or not raw.get("filters"):
130
+ return None
131
+ return cls(
132
+ node_id=raw.get("node_id"),
133
+ function_name=raw.get("function_name"),
134
+ filters=tuple(WhereCheckFilter.from_dict(f) for f in raw["filters"]),
135
+ )
136
+
137
+
138
+ def filter_factor_name(index: int) -> str:
139
+ """The factor of the *index*-th (0-based) filter. By POSITION, not by the
140
+ filter's text: editing a comparison in the check must not rename the
141
+ factor, or every role and colour naming it would go stale. The text is the
142
+ section row's label."""
143
+ return f"Filter {index + 1}"
144
+
145
+
146
+ def matching_verdict(verdicts: "list[Any]") -> str:
147
+ """The Matching level for one location from its enabled filters' verdicts
148
+ (``"pass"`` / ``"fail"`` / ``"no value"``). One rule, one place."""
149
+ if any(v == "fail" for v in verdicts):
150
+ return LEVEL_NO
151
+ if any(v == "no value" for v in verdicts):
152
+ return LEVEL_NO_VALUE
153
+ return LEVEL_YES
154
+
155
+
156
+ def verdict_level(verdict: str) -> str:
157
+ """The factor level of one filter's verdict."""
158
+ return {"pass": LEVEL_YES, "fail": LEVEL_NO}.get(verdict, LEVEL_NO_VALUE)
@@ -152,6 +152,147 @@ def _end_text(end: dict[str, str]) -> str:
152
152
  return " · ".join(end.values())
153
153
 
154
154
 
155
+ # ---------------------------------------------------------------------------
156
+ # Statistical marks: what a figure is asked to show of a test's results
157
+ # (plan: .claude/plan-stats-on-figure.md). The plot layer stores the REQUEST
158
+ # (:class:`StatMarks`) and draws the FACTS it is handed (:class:`Derived`); it
159
+ # computes nothing and never imports statistics (``scistackstats.marks``).
160
+
161
+ #: ``StatMarks.pairs``: which comparisons get a bracket.
162
+ STAT_PAIRS = ("significant", "all", "adjacent")
163
+ #: ``StatMarks.label``: what a bracket says.
164
+ STAT_LABELS = ("stars", "p", "effect", "difference")
165
+ #: ``origin`` of a note or bar derived from a statistics result.
166
+ TEST = "test"
167
+
168
+
169
+ @dataclass(frozen=True)
170
+ class StatMarks:
171
+ """Which statistical results the figure draws (display only).
172
+
173
+ - ``brackets``: a bracket per comparison chosen by ``pairs``, labelled
174
+ per ``label``.
175
+ - ``hidden``: comparison ids whose bracket is not drawn; hidden, never
176
+ deleted.
177
+ - ``omnibus``: one line per panel (:class:`PanelNote`).
178
+ - ``caption``: one line under the figure.
179
+ """
180
+
181
+ brackets: bool = False
182
+ pairs: str = "significant"
183
+ label: str = "stars"
184
+ hidden: tuple[str, ...] = ()
185
+ omnibus: bool = False
186
+ caption: bool = False
187
+
188
+ def __post_init__(self) -> None:
189
+ if self.pairs not in STAT_PAIRS:
190
+ raise ValueError(f"stat_marks.pairs must be one of {STAT_PAIRS}, got {self.pairs!r}")
191
+ if self.label not in STAT_LABELS:
192
+ raise ValueError(f"stat_marks.label must be one of {STAT_LABELS}, got {self.label!r}")
193
+ object.__setattr__(self, "hidden", tuple(str(h) for h in self.hidden))
194
+
195
+ @property
196
+ def wanted(self) -> bool:
197
+ """Whether the figure asks for anything at all."""
198
+ return self.brackets or self.omnibus or self.caption
199
+
200
+ def to_dict(self) -> dict:
201
+ return {
202
+ "brackets": self.brackets,
203
+ "pairs": self.pairs,
204
+ "label": self.label,
205
+ "hidden": list(self.hidden),
206
+ "omnibus": self.omnibus,
207
+ "caption": self.caption,
208
+ }
209
+
210
+ @classmethod
211
+ def from_dict(cls, raw: Any) -> "StatMarks":
212
+ raw = raw or {}
213
+ if not isinstance(raw, dict):
214
+ raise ValueError(f"stat_marks must be a table, got {type(raw).__name__}")
215
+ known = {"brackets", "pairs", "label", "hidden", "omnibus", "caption"}
216
+ unknown = sorted(set(raw) - known)
217
+ if unknown:
218
+ raise ValueError(f"stat_marks: unknown setting(s) {unknown}")
219
+ return cls(**{k: (tuple(v) if k == "hidden" else v) for k, v in raw.items()})
220
+
221
+
222
+ @dataclass(frozen=True)
223
+ class PanelNote:
224
+ """A line of text under one panel's title: a test's omnibus result.
225
+
226
+ ``match`` names the panel exactly as :class:`DifferenceBar` does (the
227
+ panel's ITERATE + FACET values as text).
228
+ """
229
+
230
+ match: dict[str, str] = field(default_factory=dict)
231
+ text: str = ""
232
+ origin: str = TEST
233
+
234
+ def matches_panel(self, values: dict[str, Any]) -> bool:
235
+ if set(self.match) != set(values):
236
+ return False
237
+ return all(self.match[name] == panel_key_text(values[name]) for name in values)
238
+
239
+ def to_dict(self) -> dict:
240
+ return {"match": dict(self.match), "text": self.text, "origin": self.origin}
241
+
242
+ @classmethod
243
+ def from_dict(cls, raw: dict) -> "PanelNote":
244
+ return cls(
245
+ match=_text_dict(raw.get("match")),
246
+ text=str(raw.get("text") or ""),
247
+ origin=str(raw.get("origin") or TEST),
248
+ )
249
+
250
+
251
+ @dataclass(frozen=True)
252
+ class Derived:
253
+ """Facts a layer above computed for ONE resolve; never stored.
254
+
255
+ ``bars`` join the figure's difference bars (:func:`with_derived`);
256
+ ``panel_notes`` and ``caption`` are drawn by the renderers.
257
+ """
258
+
259
+ # Annotated `list` so `restore_spec`'s dataclass walk reads each entry as a
260
+ # DifferenceBar / PanelNote; stored as tuples (frozen, comparable).
261
+ bars: list[DifferenceBar] = () # type: ignore[assignment]
262
+ panel_notes: list[PanelNote] = () # type: ignore[assignment]
263
+ caption: str | None = None
264
+
265
+ def __post_init__(self) -> None:
266
+ object.__setattr__(self, "bars", tuple(self.bars))
267
+ object.__setattr__(self, "panel_notes", tuple(self.panel_notes))
268
+
269
+ def to_dict(self) -> dict:
270
+ return {
271
+ "bars": [b.to_dict() for b in self.bars],
272
+ "panel_notes": [n.to_dict() for n in self.panel_notes],
273
+ "caption": self.caption,
274
+ }
275
+
276
+ @classmethod
277
+ def from_dict(cls, raw: dict | None) -> "Derived":
278
+ raw = raw or {}
279
+ return cls(
280
+ bars=tuple(DifferenceBar.from_dict(b) for b in (raw.get("bars") or [])),
281
+ panel_notes=tuple(PanelNote.from_dict(n) for n in (raw.get("panel_notes") or [])),
282
+ caption=(str(raw["caption"]) if raw.get("caption") else None),
283
+ )
284
+
285
+
286
+ def panel_note_for(resolved: "ResolvedPlot", panel: "Panel") -> str | None:
287
+ """The derived note for *panel*, or None. The one matcher the renderers ask."""
288
+ derived = resolved.spec.derived
289
+ if derived is None or not derived.panel_notes:
290
+ return None
291
+ values = {**resolved.figure_key, **panel.key}
292
+ found = [n.text for n in derived.panel_notes if n.text and n.matches_panel(values)]
293
+ return "\n".join(found) if found else None
294
+
295
+
155
296
  # ---------------------------------------------------------------------------
156
297
  # Where a figure can carry bars
157
298
 
@@ -1422,8 +1563,11 @@ def difference_meta(
1422
1563
  # ---------------------------------------------------------------------------
1423
1564
 
1424
1565
 
1425
- def with_derived_bars(spec: "PlotSpec", derived: list[DifferenceBar]) -> "PlotSpec":
1426
- """``spec`` drawing ``derived`` bars as well as its own, for one resolve.
1566
+ def with_derived(spec: "PlotSpec", facts: Derived) -> "PlotSpec":
1567
+ """``spec`` drawing the derived ``facts`` as well as its own, for one resolve.
1568
+
1569
+ Panel notes and the caption ride on ``spec.derived`` (bars cleared: they
1570
+ are merged into ``difference_bars`` below, one owner).
1427
1571
 
1428
1572
  The one place derived bars join a figure. A derived bar is intent
1429
1573
  computed from something else (a statistics result), so it is never
@@ -1435,6 +1579,7 @@ def with_derived_bars(spec: "PlotSpec", derived: list[DifferenceBar]) -> "PlotSp
1435
1579
  """
1436
1580
  from dataclasses import replace
1437
1581
 
1582
+ derived = list(facts.bars)
1438
1583
  manual = list(spec.difference_bars)
1439
1584
  kept = [bar for bar in derived if not any(bar.same_pair(m) for m in manual)]
1440
1585
  dropped = len(derived) - len(kept)
@@ -1446,4 +1591,9 @@ def with_derived_bars(spec: "PlotSpec", derived: list[DifferenceBar]) -> "PlotSp
1446
1591
  f"; {dropped} derived bar(s) dropped (a manual bar has that pair)" if dropped else "",
1447
1592
  layer=LAYER,
1448
1593
  )
1449
- return replace(spec, difference_bars=[*kept, *manual])
1594
+ text = Derived(panel_notes=facts.panel_notes, caption=facts.caption)
1595
+ return replace(
1596
+ spec,
1597
+ difference_bars=[*kept, *manual],
1598
+ derived=text if (text.panel_notes or text.caption) else None,
1599
+ )
@@ -182,6 +182,8 @@ _PLAN_IRRELEVANT_FIELDS = (
182
182
  "colors",
183
183
  "panel_overrides",
184
184
  "difference_bars",
185
+ "stat_marks",
186
+ "derived",
185
187
  "comparison",
186
188
  # Binned and fitted per figure, over rows the plan already holds.
187
189
  "histogram",
@@ -1922,6 +1924,12 @@ def _build_figure(
1922
1924
  # Which difference bars land on which panel, once per figure, so a bar
1923
1925
  # that draws nowhere is explained in scistack.log (diffbars D3).
1924
1926
  log_difference_bars(resolved)
1927
+ if resolved.spec.stat_marks.wanted and resolved.spec.derived is None and not resolved.spec.difference_bars:
1928
+ Log.info(
1929
+ "stat_marks ask for test results but none were supplied; "
1930
+ "scistackstats.marks.marks_for supplies them (via diffbars.with_derived)",
1931
+ layer=LAYER,
1932
+ )
1925
1933
  return resolved
1926
1934
 
1927
1935
 
@@ -1282,3 +1282,32 @@ def not_plotted_note(resolved: ResolvedPlot) -> str | None:
1282
1282
  if not resolved.spec.style.not_plotted_note or report is None or not report.items:
1283
1283
  return None
1284
1284
  return report.sentence()
1285
+
1286
+
1287
+ def footnote_text(resolved: ResolvedPlot, width_pt: float | None = None) -> str | None:
1288
+ """The whole footnote both renderers draw under the figure, or None: the
1289
+ derived statistics caption (``Derived.caption``, asked for by
1290
+ ``StatMarks.caption``), then the "Not plotted" note, one line each.
1291
+
1292
+ The ONE owner of the footnote's content. With *width_pt* each part is
1293
+ wrapped to that width (an average glyph is about half the font size wide),
1294
+ so a long caption takes more lines and the renderers reserve their count.
1295
+ """
1296
+ import textwrap
1297
+
1298
+ from ..text.textsize import sizes_for
1299
+
1300
+ parts: list[str] = []
1301
+ derived = resolved.spec.derived
1302
+ if resolved.spec.stat_marks.caption and derived is not None and derived.caption:
1303
+ parts.append(derived.caption)
1304
+ note = not_plotted_note(resolved)
1305
+ if note:
1306
+ parts.append(note)
1307
+ if not parts:
1308
+ return None
1309
+ if width_pt is not None:
1310
+ size = sizes_for(resolved).legend
1311
+ chars = max(int(width_pt / max(size * 0.5, 1.0)), 20)
1312
+ parts = ["\n".join(textwrap.wrap(part, chars) or [part]) for part in parts]
1313
+ return "\n".join(parts)
@@ -63,7 +63,7 @@ from .base import (
63
63
  univariate_x_range,
64
64
  histogram_ticks,
65
65
  is_special_bin,
66
- not_plotted_note,
66
+ footnote_text,
67
67
  rug_rows,
68
68
  SPECIAL_BIN_HATCH,
69
69
  is_categorical_x,
@@ -300,6 +300,7 @@ def _render(resolved: ResolvedPlot):
300
300
  layer=LAYER,
301
301
  )
302
302
 
303
+ _draw_panel_notes(panel_axes, resolved)
303
304
  if resolved.labels.title:
304
305
  fig.suptitle(resolved.labels.title)
305
306
  # tight_layout is told how much room the legend took. A FIGURE legend
@@ -751,16 +752,36 @@ def _draw_distribution(ax, frame, resolved, *, violin: bool) -> None:
751
752
 
752
753
 
753
754
  def _draw_not_plotted_note(fig, resolved: ResolvedPlot) -> float:
754
- """The "Not plotted" footnote (``base.not_plotted_note``) at the bottom
755
- left of the figure. Returns the figure fraction it takes, which the
756
- layout keeps free (``_reserve_bottom``); 0 when there is none."""
757
- note = not_plotted_note(resolved)
755
+ """The footnote (``base.footnote_text``: the statistics caption, then the
756
+ "Not plotted" note) at the bottom left of the figure. Returns the figure
757
+ fraction it takes, which the layout keeps free (``_reserve_bottom``); 0
758
+ when there is none."""
759
+ size = sizes_for(resolved).legend
760
+ note = footnote_text(resolved, fig.get_figwidth() * 72.0)
758
761
  if not note:
759
762
  return 0.0
760
- size = sizes_for(resolved).legend
761
763
  height_pt = fig.get_figheight() * 72.0
764
+ lines = note.count("\n") + 1
762
765
  fig.text(0.01, 0.005, note, ha="left", va="bottom", fontsize=size, gid="not_plotted_note")
763
- return min(size * 1.8 / height_pt, 0.25)
766
+ return min(size * (1.5 * lines + 0.3) / height_pt, 0.25)
767
+
768
+
769
+ def _draw_panel_notes(panel_axes: dict[int, Any], resolved: ResolvedPlot) -> int:
770
+ """The derived per-panel line (``diffbars.panel_note_for``: a test's omnibus
771
+ result) as the axes' own title, so the layout pass measures it. Returns
772
+ how many were drawn."""
773
+ from ..reduce.diffbars import panel_note_for
774
+
775
+ if resolved.spec.derived is None or not resolved.spec.stat_marks.omnibus:
776
+ return 0
777
+ size = sizes_for(resolved).legend
778
+ drawn = 0
779
+ for index, ax in panel_axes.items():
780
+ note = panel_note_for(resolved, resolved.panels[index])
781
+ if note:
782
+ ax.set_title(note, loc="left", fontsize=size)
783
+ drawn += 1
784
+ return drawn
764
785
 
765
786
 
766
787
  def _reserve_bottom(rect, room: float):
@@ -68,7 +68,7 @@ from .base import (
68
68
  univariate_x_range,
69
69
  histogram_ticks,
70
70
  is_special_bin,
71
- not_plotted_note,
71
+ footnote_text,
72
72
  rug_rows,
73
73
  SPECIAL_BIN_PATTERN,
74
74
  is_categorical_x,
@@ -361,6 +361,7 @@ def render(
361
361
  )
362
362
  panel_axes[index] = (x_axis, y_axis)
363
363
  _add_difference_bars(layout, resolved, difference, index, x_axis, y_axis)
364
+ _add_panel_note(layout, resolved, panel, x_axis, y_axis)
364
365
 
365
366
  # What Plot Studio's Difference bars section shows and picks from
366
367
  # (diffbars.difference_meta); None where the figure cannot carry bars.
@@ -381,13 +382,15 @@ def render(
381
382
  layout["font"]["family"] = PREVIEW_FONT_FAMILY
382
383
  if decisions is not None:
383
384
  _apply_decisions(layout, resolved, decisions)
384
- note = not_plotted_note(resolved)
385
+ width_px = layout.get("width")
386
+ note = footnote_text(resolved, float(width_px) * 0.75 if width_px else 700.0)
385
387
  if note:
386
- # The "Not plotted" footnote (base.not_plotted_note): bottom left,
387
- # below everything, in a margin grown by its own line.
388
+ # The footnote (base.footnote_text: statistics caption, then the
389
+ # "Not plotted" note): bottom left, below everything, in a margin
390
+ # grown by its own lines.
388
391
  size = sizes.legend
389
392
  margin = layout.setdefault("margin", {})
390
- margin["b"] = float(margin.get("b", 0) or 0) + size * 2
393
+ margin["b"] = float(margin.get("b", 0) or 0) + size * (1.7 * (note.count("\n") + 1) + 0.3)
391
394
  layout["annotations"].append(
392
395
  {
393
396
  "text": _html(note),
@@ -1957,6 +1960,38 @@ def _estimated_panel_frames(
1957
1960
  return frames
1958
1961
 
1959
1962
 
1963
+ def _add_panel_note(layout: dict, resolved: ResolvedPlot, panel, x_axis: str, y_axis: str) -> None:
1964
+ """The derived per-panel line (``diffbars.panel_note_for``) above the
1965
+ panel's plot area, left aligned, in the panel's own domain. The top margin
1966
+ grows by one line the first time (a one-row figure has nothing above it)."""
1967
+ from ..reduce.diffbars import panel_note_for
1968
+
1969
+ if resolved.spec.derived is None or not resolved.spec.stat_marks.omnibus:
1970
+ return
1971
+ note = panel_note_for(resolved, panel)
1972
+ if not note:
1973
+ return
1974
+ size = sizes_for(resolved).legend
1975
+ if not any(a.get("name") == "panel_note" for a in layout["annotations"]):
1976
+ margin = layout.setdefault("margin", {})
1977
+ margin["t"] = float(margin.get("t", 0) or 0) + size * 1.7
1978
+ layout["annotations"].append(
1979
+ {
1980
+ "text": _plain(note).replace("\n", "<br>"),
1981
+ "xref": f"{x_axis} domain",
1982
+ "yref": f"{y_axis} domain",
1983
+ "x": 0.0,
1984
+ "y": 1.0,
1985
+ "xanchor": "left",
1986
+ "yanchor": "bottom",
1987
+ "yshift": 2,
1988
+ "showarrow": False,
1989
+ "font": {"size": size, "color": PAPER.text},
1990
+ "name": "panel_note",
1991
+ }
1992
+ )
1993
+
1994
+
1960
1995
  def _add_difference_bars(
1961
1996
  layout: dict, resolved: ResolvedPlot, placement, index: int, x_axis: str, y_axis: str
1962
1997
  ) -> None:
@@ -20,6 +20,7 @@ from .dedup import SingleFlight
20
20
  from ..text.framesize import format_extent, frame_extent
21
21
  from ..model.spec import FactorVariable
22
22
  from ..model.table import LongTable
23
+ from ..model.where_check import WhereCheck
23
24
 
24
25
  LAYER = "scistackplot"
25
26
 
@@ -78,6 +79,7 @@ class DataSource(Protocol):
78
79
  *,
79
80
  x_measure: str | None = None,
80
81
  factor_variables: "list[FactorVariable] | None" = None,
82
+ where_check: "WhereCheck | None" = None,
81
83
  ) -> LongTable:
82
84
  """The long-format table for a plot's measures.
83
85
 
@@ -174,6 +176,7 @@ class BaseSource:
174
176
  *,
175
177
  x_measure: str | None = None,
176
178
  factor_variables: "list[FactorVariable] | None" = None,
179
+ where_check: "WhereCheck | None" = None,
177
180
  ) -> LongTable:
178
181
  """The long table for these measures, built once per distinct request.
179
182
 
@@ -211,13 +214,15 @@ class BaseSource:
211
214
  # never reached.
212
215
  self._revalidate(
213
216
  [*measures, *([x_measure] if x_measure else []),
214
- *(group.variable for group in (factor_variables or ()))]
217
+ *(group.variable for group in (factor_variables or ())),
218
+ *(f.variable for f in (where_check.filters if where_check else ()))]
215
219
  )
216
220
  memo = self._current_table_cache()
217
221
  key = (
218
222
  tuple(measures),
219
223
  x_measure,
220
224
  tuple(factor_variables or ()),
225
+ where_check,
221
226
  )
222
227
  label = f"get_table({', '.join(measures)})"
223
228
  if key in memo:
@@ -242,7 +247,10 @@ class BaseSource:
242
247
  with Log.timer(label, layer=LAYER) as timer:
243
248
  with timer.phase("build_table"):
244
249
  table = self._build_table(
245
- measures, x_measure=x_measure, factor_variables=factor_variables
250
+ measures,
251
+ x_measure=x_measure,
252
+ factor_variables=factor_variables,
253
+ where_check=where_check,
246
254
  )
247
255
  table = self._attach_project_sources(table)
248
256
  # Size the result in cells and SAMPLES, not just rows: a row count
@@ -379,11 +387,13 @@ class BaseSource:
379
387
  *,
380
388
  x_measure: str | None = None,
381
389
  factor_variables: "list[FactorVariable] | None" = None,
390
+ where_check: "WhereCheck | None" = None,
382
391
  ) -> LongTable:
383
392
  # `factor_variables` is accepted and ignored: a flat table's factors are
384
393
  # already columns of every row, so there is nothing to join in
385
394
  # (`groupable_with` returns none). Accepting it keeps one call shape for
386
395
  # every source rather than making callers branch on which they hold.
396
+ # `where_check` likewise: a flat table has no variable to check a filter against.
387
397
  table = self._table()
388
398
  requested = [*measures, *([x_measure] if x_measure else [])]
389
399
  unknown = [m for m in requested if m not in table.measure_names]
File without changes
File without changes