scistackplot 0.1.63__tar.gz → 0.1.66__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 (56) hide show
  1. {scistackplot-0.1.63 → scistackplot-0.1.66}/PKG-INFO +40 -3
  2. {scistackplot-0.1.63 → scistackplot-0.1.66}/README.md +37 -0
  3. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/__init__.py +27 -0
  4. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/capability.py +191 -6
  5. scistackplot-0.1.66/src/scistackplot/categorical.py +573 -0
  6. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/cell.py +32 -1
  7. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/codegen.py +195 -12
  8. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/design.py +5 -0
  9. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/export.py +45 -2
  10. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/presets.py +13 -1
  11. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/reduce.py +148 -8
  12. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/reducer.py +1 -1
  13. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/render/base.py +37 -0
  14. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/render/mpl.py +80 -9
  15. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/render/plotly_.py +77 -13
  16. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/resolved.py +18 -0
  17. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/roles.py +190 -3
  18. scistackplot-0.1.66/src/scistackplot/rows.py +185 -0
  19. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/series_stats.py +7 -1
  20. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/shape.py +34 -2
  21. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/spec.py +91 -3
  22. scistackplot-0.1.66/src/scistackplot/stacking.py +86 -0
  23. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/table.py +56 -7
  24. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/variants.py +9 -1
  25. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/ylimits.py +32 -3
  26. {scistackplot-0.1.63 → scistackplot-0.1.66}/.gitignore +0 -0
  27. {scistackplot-0.1.63 → scistackplot-0.1.66}/pyproject.toml +0 -0
  28. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/aliases.py +0 -0
  29. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/autosize.py +0 -0
  30. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/bins.py +0 -0
  31. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/colors.py +0 -0
  32. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/compare.py +0 -0
  33. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/custom.py +0 -0
  34. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/dedup.py +0 -0
  35. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/diffbars.py +0 -0
  36. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/figsize.py +0 -0
  37. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/figure_file.py +0 -0
  38. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/fits.py +0 -0
  39. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/framesize.py +0 -0
  40. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/groups.py +0 -0
  41. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/numeric.py +0 -0
  42. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/panels.py +0 -0
  43. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/paper.py +0 -0
  44. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/render/__init__.py +0 -0
  45. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/restore.py +0 -0
  46. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/sources/__init__.py +0 -0
  47. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/sources/base.py +0 -0
  48. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/sources/csv.py +0 -0
  49. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/sources/frame.py +0 -0
  50. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/spaghetti.py +0 -0
  51. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/spread.py +0 -0
  52. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/temporal.py +0 -0
  53. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/textsize.py +0 -0
  54. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/ticklabels.py +0 -0
  55. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/weights.py +0 -0
  56. {scistackplot-0.1.63 → scistackplot-0.1.66}/src/scistackplot/xaxis.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scistackplot
3
- Version: 0.1.63
3
+ Version: 0.1.66
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.1.63
24
- Requires-Dist: scistacklog==0.1.63
23
+ Requires-Dist: scicanonicalhash==0.1.66
24
+ Requires-Dist: scistacklog==0.1.66
25
25
  Provides-Extra: dev
26
26
  Requires-Dist: matplotlib>=3.6; extra == 'dev'
27
27
  Requires-Dist: plotly>=5.0; extra == 'dev'
@@ -113,6 +113,7 @@ collapsed. That single rule produces both defaults and availability:
113
113
  | scalar | scatter, or a bar with no error bar | box / violin / bar + CI |
114
114
  | 1-D array | one line per leaf group | mean line + shaded error band |
115
115
  | 2-D | heatmap | mean heatmap |
116
+ | text | count bar | proportion bar + error (see "Text measures") |
116
117
 
117
118
  "Average over trials, then show the spread across subjects" is
118
119
  `trial=COLLAPSE, subject=COLLAPSE`: trial averages within each subject
@@ -178,6 +179,42 @@ change does not apply. Save data writes ISO times and names the zone in the
178
179
  header, and the exported code draws the same date ticks. See
179
180
  `docs/claude/plot-datetimes.md`.
180
181
 
182
+ ## Text measures
183
+
184
+ A text (or True/False) column is plotted by rewriting it into numbers first
185
+ (`scistackplot.categorical`), and the plot type decides how:
186
+
187
+ | Plot type | What it draws | "Show sample" |
188
+ |---|---|---|
189
+ | Count bar (the default) | records per category | — (a count has no sample) |
190
+ | Proportion bar + error | the mean of each unit's % ± the error band | each unit's % |
191
+ | Count / proportion heatmap | categories × one grouping layer | — |
192
+ | Strip of categories | every record at its category on a category axis | — |
193
+ | Spaghetti of categories / of % per unit | one line per unit across x | — |
194
+
195
+ ```python
196
+ from scistackplot import CategoricalOptions, CategoricalStat
197
+
198
+ spec = PlotSpec(
199
+ measures=["Outcome"],
200
+ roles={"Level": Role.GROUP, "subject": Role.COLLAPSE, "trial": Role.COLLAPSE},
201
+ groups=["Level"], color="Level", # one bar per category
202
+ kind=PlotKind.BAR,
203
+ categorical=CategoricalOptions(stat=CategoricalStat.PROPORTION),
204
+ )
205
+ ```
206
+
207
+ **Collapse means pool** for a text measure: a collapsed key's records merge
208
+ into one bucket, never an average of averages. A count sums every collapsed
209
+ key; a proportion pools everything beneath the sample key (the last
210
+ collapsed one) into one % per unit, then draws the mean of the units.
211
+ `Level` is the synthetic factor naming the categories; `CategoricalOptions.level`
212
+ draws one category only. A filter on the measure keeps records by category;
213
+ a range filter on it is refused. More than 50 distinct values is free text,
214
+ refused with that reason. `BarOptions(stack=True)` stacks the coloured layer
215
+ (any measure) — with a % per category on colour, the 100% stacked bar. See
216
+ `docs/claude/categorical-measures.md`.
217
+
181
218
  ## Histograms and regressions
182
219
 
183
220
  Two kinds put a number line on x. A **histogram** bins the measure itself:
@@ -72,6 +72,7 @@ collapsed. That single rule produces both defaults and availability:
72
72
  | scalar | scatter, or a bar with no error bar | box / violin / bar + CI |
73
73
  | 1-D array | one line per leaf group | mean line + shaded error band |
74
74
  | 2-D | heatmap | mean heatmap |
75
+ | text | count bar | proportion bar + error (see "Text measures") |
75
76
 
76
77
  "Average over trials, then show the spread across subjects" is
77
78
  `trial=COLLAPSE, subject=COLLAPSE`: trial averages within each subject
@@ -137,6 +138,42 @@ change does not apply. Save data writes ISO times and names the zone in the
137
138
  header, and the exported code draws the same date ticks. See
138
139
  `docs/claude/plot-datetimes.md`.
139
140
 
141
+ ## Text measures
142
+
143
+ A text (or True/False) column is plotted by rewriting it into numbers first
144
+ (`scistackplot.categorical`), and the plot type decides how:
145
+
146
+ | Plot type | What it draws | "Show sample" |
147
+ |---|---|---|
148
+ | Count bar (the default) | records per category | — (a count has no sample) |
149
+ | Proportion bar + error | the mean of each unit's % ± the error band | each unit's % |
150
+ | Count / proportion heatmap | categories × one grouping layer | — |
151
+ | Strip of categories | every record at its category on a category axis | — |
152
+ | Spaghetti of categories / of % per unit | one line per unit across x | — |
153
+
154
+ ```python
155
+ from scistackplot import CategoricalOptions, CategoricalStat
156
+
157
+ spec = PlotSpec(
158
+ measures=["Outcome"],
159
+ roles={"Level": Role.GROUP, "subject": Role.COLLAPSE, "trial": Role.COLLAPSE},
160
+ groups=["Level"], color="Level", # one bar per category
161
+ kind=PlotKind.BAR,
162
+ categorical=CategoricalOptions(stat=CategoricalStat.PROPORTION),
163
+ )
164
+ ```
165
+
166
+ **Collapse means pool** for a text measure: a collapsed key's records merge
167
+ into one bucket, never an average of averages. A count sums every collapsed
168
+ key; a proportion pools everything beneath the sample key (the last
169
+ collapsed one) into one % per unit, then draws the mean of the units.
170
+ `Level` is the synthetic factor naming the categories; `CategoricalOptions.level`
171
+ draws one category only. A filter on the measure keeps records by category;
172
+ a range filter on it is refused. More than 50 distinct values is free text,
173
+ refused with that reason. `BarOptions(stack=True)` stacks the coloured layer
174
+ (any measure) — with a % per category on colour, the 100% stacked bar. See
175
+ `docs/claude/categorical-measures.md`.
176
+
140
177
  ## Histograms and regressions
141
178
 
142
179
  Two kinds put a number line on x. A **histogram** bins the measure itself:
@@ -47,6 +47,14 @@ from .capability import (
47
47
  variant_summary,
48
48
  why_unavailable,
49
49
  )
50
+ from .categorical import (
51
+ LEVEL_FACTOR,
52
+ MAX_CATEGORY_LEVELS,
53
+ apply_categorical,
54
+ categorical_mode,
55
+ mode_for_kind,
56
+ )
57
+ from .stacking import stack_bases, stacks
50
58
  from .cell import apply_cell_collapse, cell_collapse_note, cell_collapses, effective_shape
51
59
  from .codegen import (
52
60
  default_function_name,
@@ -111,9 +119,13 @@ from .custom import (
111
119
  )
112
120
  from .diffbars import DifferenceBar, bars_for_panel, slot_endpoints
113
121
  from .panels import PanelOverride, override_for
122
+ from .rows import ROW_FACTOR, element_values, explode_row_lists, row_factor, row_origin
114
123
  from .shape import Shape, classify_column, classify_value, is_plottable
115
124
  from .sources import BaseSource, CsvSource, DataFrameSource, DataSource, UnknownMeasureError
116
125
  from .spec import (
126
+ BarOptions,
127
+ CategoricalOptions,
128
+ CategoricalStat,
117
129
  Aggregation,
118
130
  BinMode,
119
131
  CONTINUOUS_X_KINDS,
@@ -245,6 +257,16 @@ __all__ = [
245
257
  "CONTINUOUS_X_KINDS",
246
258
  "FitBy",
247
259
  "HistMultiple",
260
+ "BarOptions",
261
+ "CategoricalOptions",
262
+ "CategoricalStat",
263
+ "LEVEL_FACTOR",
264
+ "MAX_CATEGORY_LEVELS",
265
+ "apply_categorical",
266
+ "categorical_mode",
267
+ "mode_for_kind",
268
+ "stack_bases",
269
+ "stacks",
248
270
  "HistStat",
249
271
  "HistogramOptions",
250
272
  "RegressionOptions",
@@ -331,6 +353,11 @@ __all__ = [
331
353
  "FactorInfo",
332
354
  "MISSING_LEVEL",
333
355
  "MeasureInfo",
356
+ "ROW_FACTOR",
357
+ "element_values",
358
+ "explode_row_lists",
359
+ "row_factor",
360
+ "row_origin",
334
361
  "Shape",
335
362
  "classify_value",
336
363
  "classify_column",
@@ -17,6 +17,15 @@ from __future__ import annotations
17
17
 
18
18
  from dataclasses import replace
19
19
 
20
+ from scistacklog import Log
21
+
22
+ from .categorical import (
23
+ CATEGORICAL_KINDS,
24
+ categorical_mode,
25
+ categorical_problem,
26
+ free_text_reason,
27
+ mode_for_kind,
28
+ )
20
29
  from .compare import comparison_summary
21
30
  from .roles import (
22
31
  layer_cap_reason,
@@ -38,7 +47,16 @@ from .roles import (
38
47
  sample_key,
39
48
  )
40
49
  from .shape import Shape
41
- from .spec import BAR_KINDS, BUILTIN_KINDS, MAX_X_LAYERS, SCALAR_KINDS, PlotKind, PlotSpec, Role
50
+ from .spec import (
51
+ BAR_KINDS,
52
+ BUILTIN_KINDS,
53
+ MAX_X_LAYERS,
54
+ SCALAR_KINDS,
55
+ CategoricalStat,
56
+ PlotKind,
57
+ PlotSpec,
58
+ Role,
59
+ )
42
60
  from .table import CODE_FACTOR_PREFIX, RUN_FACTOR_PREFIX, LongTable
43
61
  from .temporal import BAR_REASON, time_zone_summary
44
62
 
@@ -268,7 +286,22 @@ def available_plots(
268
286
  return kinds
269
287
 
270
288
  if shape is Shape.SCALAR:
271
- return scalar_kinds()
289
+ # The grid heatmap (two grouping layers, one cell per pair) only for a
290
+ # measure that IS scalar: a 1-D measure's heatmap would have to say
291
+ # whether it collapses its cells, and `cell.cell_collapses` does not.
292
+ grid = kind_requirement(PlotKind.HEATMAP, shape, roles, n_groups) is None
293
+ return [*scalar_kinds(), *([PlotKind.HEATMAP] if grid else [])]
294
+
295
+ if shape is Shape.CATEGORICAL:
296
+ # A text measure (`categorical`): counts and %s as bars or a heatmap,
297
+ # or its categories as positions on a strip or a spaghetti. Whether a
298
+ # % has its sample is `categorical.categorical_problem`'s, judged
299
+ # per tile in `capabilities`.
300
+ return [
301
+ kind
302
+ for kind in CATEGORICAL_KINDS
303
+ if kind_requirement(kind, Shape.SCALAR, roles, n_groups) is None
304
+ ]
272
305
 
273
306
  return []
274
307
 
@@ -286,6 +319,7 @@ def default_plot(
286
319
  scalar → scatter, or box once there is a sample to distribute;
287
320
  1-D → one line per observation, or a mean line with a shaded error region
288
321
  once there is a sample; 2-D → heatmap.
322
+ A text measure → its count per category, as a bar (user, 2026-11-01).
289
323
  """
290
324
  kinds = available_plots(shape, roles, has_x_measure=has_x_measure, n_groups=n_groups)
291
325
  if not kinds:
@@ -340,6 +374,11 @@ def why_unavailable(
340
374
  return BAR_REASON
341
375
  if shape is Shape.MATRIX_2D:
342
376
  return "2-D measures render as a heatmap."
377
+ if shape is Shape.CATEGORICAL and kind not in CATEGORICAL_KINDS:
378
+ return (
379
+ "A text measure is drawn as a count or % (bar, horizontal bar, "
380
+ "heatmap) or as its categories (strip, spaghetti)."
381
+ )
343
382
  # Shape mismatches first: a scalar band is refused for being a band on a
344
383
  # scalar, not for lacking a sample it could never use.
345
384
  if kind is PlotKind.BAND and shape is not Shape.SERIES_1D:
@@ -361,6 +400,7 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
361
400
  would be for the current role assignment.
362
401
  """
363
402
  from .cell import apply_cell_collapse, cell_collapses
403
+ from .categorical import apply_categorical
364
404
  from .export import data_export_options
365
405
  from .groups import apply_level_groups
366
406
  from .variants import apply_variant_sets, strip_answered_roles
@@ -381,10 +421,18 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
381
421
  # BAND as soon as a violin was selected, stranding the user on the scalar
382
422
  # kinds with no way back (docs/claude/measure-shape-and-collapse.md).
383
423
  collapsed = apply_cell_collapse(spec, derived)
424
+ # A text measure is rewritten into numbers the same way resolve rewrites
425
+ # it (`categorical`), so the factors, roles and summaries below describe
426
+ # the figure — the `Level` factor included. `kind_spec` keeps the spec as
427
+ # the user holds it for the per-kind loop, which re-asks the rewrite per
428
+ # tile (a strip has no `Level`; its tile must still be able to offer one).
429
+ kind_spec = spec
430
+ spec, collapsed = apply_categorical(spec, collapsed)
384
431
  assignment = complete_assignment(spec, collapsed)
385
432
  roles = assignment.roles
386
433
  raw_shape = derived.shape_of(spec.y_measure)
387
434
  shape = collapsed.shape_of(spec.y_measure)
435
+ categorical = raw_shape is Shape.CATEGORICAL and spec.x_measure is None
388
436
  collapsing = cell_collapses(spec, derived)
389
437
  collapsible = raw_shape is Shape.SERIES_1D and spec.x_measure is None
390
438
  has_x_measure = spec.x_measure is not None
@@ -403,7 +451,7 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
403
451
  # assignment it brings with it closes that loop: clicking Violin both
404
452
  # collapses a factor and draws the distribution, in one click.
405
453
  entries = []
406
- for kind in BUILTIN_KINDS:
454
+ for kind in BUILTIN_KINDS if not categorical else ():
407
455
  suggested = roles_for_kind(spec, derived, kind)
408
456
  kind_roles = suggested.roles if suggested else roles
409
457
  kind_groups = suggested.groups if suggested else assignment.groups
@@ -454,9 +502,13 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
454
502
  "assignment": None if suggested is None else suggested.to_dict(),
455
503
  }
456
504
  )
505
+ if categorical:
506
+ entries = categorical_kind_entries(kind_spec, derived, roles, assignment.groups)
457
507
  # Derived from the entries rather than computed a second time: two lists
458
508
  # that could disagree about one kind is the bug, not the saving.
459
- allowed = [PlotKind(entry["kind"]) for entry in entries if entry["available"]]
509
+ allowed = list(
510
+ dict.fromkeys(PlotKind(entry["kind"]) for entry in entries if entry["available"])
511
+ )
460
512
 
461
513
  return {
462
514
  # What the FIGURE is — scalar while a cell collapse is in effect. The
@@ -504,7 +556,10 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
504
556
  "data_export": data_export_options(spec, roles, collapsed, shape).to_dict(),
505
557
  "default": str(
506
558
  default_plot(
507
- shape, roles, has_x_measure=has_x_measure, n_groups=len(assignment.groups)
559
+ raw_shape if categorical else shape,
560
+ roles,
561
+ has_x_measure=has_x_measure,
562
+ n_groups=len(assignment.groups),
508
563
  )
509
564
  or ""
510
565
  ),
@@ -522,6 +577,11 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
522
577
  # continuous_kind_problem — the message validate refuses with).
523
578
  "histogram": histogram_summary(spec, derived),
524
579
  "regression": regression_summary(spec, derived),
580
+ # The Categories section (a text measure): its mode, its categories
581
+ # for the "one category" picker, and why it cannot be drawn at all.
582
+ "categorical": categorical_summary(kind_spec, derived),
583
+ # Bar options: stacking, and what stacking turns off.
584
+ "bar": bar_summary(spec),
525
585
  # The X variable picker's current state. Which variables it may offer
526
586
  # is the source's question (`DataSource.joinable_with`), answered by
527
587
  # the GUI's variable list, not by this one loaded table.
@@ -536,6 +596,131 @@ def capabilities(spec: PlotSpec, table: LongTable) -> dict:
536
596
  }
537
597
 
538
598
 
599
+ #: The plot-type tiles a TEXT measure is offered, in grid order: each a kind
600
+ #: plus the stat it draws (``categorical.mode_for_kind``). Two bar types —
601
+ #: "Count" (the pooled records, no sample) and "Proportion" (the mean of
602
+ #: per-unit %s ± error, "Show sample" on) — are separate tiles (user,
603
+ #: 2026-11-01), as are the heatmap and spaghetti forms.
604
+ CATEGORICAL_TILES: tuple[tuple[PlotKind, CategoricalStat, str], ...] = (
605
+ (PlotKind.BAR, CategoricalStat.COUNT, "Count bar"),
606
+ (PlotKind.BAR, CategoricalStat.PROPORTION, "Proportion bar + error"),
607
+ (PlotKind.HBAR, CategoricalStat.COUNT, "Horizontal count bar"),
608
+ (PlotKind.HBAR, CategoricalStat.PROPORTION, "Horizontal proportion bar + error"),
609
+ (PlotKind.HEATMAP, CategoricalStat.COUNT, "Count heatmap"),
610
+ (PlotKind.HEATMAP, CategoricalStat.PROPORTION, "Proportion heatmap"),
611
+ (PlotKind.STRIP, CategoricalStat.VALUE, "Strip of categories"),
612
+ (PlotKind.SPAGHETTI, CategoricalStat.VALUE, "Spaghetti of categories"),
613
+ (PlotKind.SPAGHETTI, CategoricalStat.PROPORTION, "Spaghetti of % per unit"),
614
+ )
615
+
616
+
617
+ def categorical_kind_entries(
618
+ spec: PlotSpec,
619
+ table: LongTable,
620
+ roles: dict[str, Role],
621
+ groups: list[str],
622
+ ) -> list[dict]:
623
+ """The kind grid for a text measure: one entry per :data:`CATEGORICAL_TILES`
624
+ tile, then every other built-in kind, unavailable with its reason.
625
+
626
+ Each tile is judged, like every kind, against the assignment it would
627
+ open with (``roles.categorical_roles_for`` — only from an untouched
628
+ default) and carries it, plus the ``categorical`` patch its click
629
+ applies; ``selected`` says which tile the current spec IS, so the panel
630
+ never re-derives the kind→stat rule. ``table`` is the raw derived table
631
+ (before the text rewrite)."""
632
+ from .roles import categorical_roles_for
633
+
634
+ current = mode_for_kind(spec.kind, spec.categorical.stat)
635
+ free_text = free_text_reason(table, spec.y_measure)
636
+ entries: list[dict] = []
637
+ for kind, stat, label in CATEGORICAL_TILES:
638
+ candidate = replace(spec, kind=kind, categorical=replace(spec.categorical, stat=stat))
639
+ suggested = categorical_roles_for(spec, table, kind, stat)
640
+ if suggested is not None:
641
+ candidate = suggested.apply(candidate)
642
+ kind_roles = suggested.roles if suggested else roles
643
+ kind_groups = suggested.groups if suggested else groups
644
+ reason = free_text or why_unavailable(
645
+ kind, Shape.CATEGORICAL, kind_roles, n_groups=len(kind_groups)
646
+ ) or categorical_problem(candidate, table)
647
+ entries.append(
648
+ {
649
+ "kind": str(kind),
650
+ "id": f"{kind}:{stat}",
651
+ "label": label,
652
+ "available": reason is None,
653
+ "reason": reason,
654
+ "collapses": False,
655
+ "assignment": None if suggested is None else suggested.to_dict(),
656
+ "categorical": {"stat": str(stat)},
657
+ "selected": spec.kind is kind and current is mode_for_kind(kind, stat),
658
+ }
659
+ )
660
+ tiled = {kind for kind, _stat, _label in CATEGORICAL_TILES}
661
+ for kind in BUILTIN_KINDS:
662
+ if kind in tiled:
663
+ continue
664
+ entries.append(
665
+ {
666
+ "kind": str(kind),
667
+ "available": False,
668
+ "reason": why_unavailable(kind, Shape.CATEGORICAL, roles, n_groups=len(groups)),
669
+ "collapses": False,
670
+ "assignment": None,
671
+ }
672
+ )
673
+ Log.debug(
674
+ "categorical kinds for %r: %d of %d tile(s) available; current %s/%s",
675
+ spec.y_measure,
676
+ sum(1 for e in entries if e["available"]),
677
+ len(CATEGORICAL_TILES),
678
+ spec.kind,
679
+ current,
680
+ layer="scistackplot",
681
+ )
682
+ return entries
683
+
684
+
685
+ def categorical_summary(spec: PlotSpec, table: LongTable) -> dict:
686
+ """The Categories section: whether the measure is text, what it is drawn
687
+ as, its categories (the "one category" picker) and why it cannot be
688
+ drawn at all (free text). ``table`` is the raw derived table."""
689
+ from .categorical import is_categorical_measure
690
+
691
+ applies = is_categorical_measure(table, spec.y_measure) and spec.x_measure is None
692
+ if not applies:
693
+ return {"applies": False}
694
+ info = table.measure(spec.y_measure)
695
+ mode = categorical_mode(spec, table)
696
+ return {
697
+ "applies": True,
698
+ "mode": str(mode) if mode else None,
699
+ "stat": str(spec.categorical.stat),
700
+ "level": spec.categorical.level,
701
+ # The one-category picker applies to a count or a %, not to positions.
702
+ "level_applies": mode is not CategoricalStat.VALUE,
703
+ "levels": [str(level) for level in info.levels],
704
+ "problem": free_text_reason(table, spec.y_measure),
705
+ }
706
+
707
+
708
+ def bar_summary(spec: PlotSpec) -> dict:
709
+ """The bar options: whether they apply (a bar kind), whether the bars
710
+ stack, and what stacking turns off — said once here, shown in the panel."""
711
+ applies = spec.kind in BAR_KINDS
712
+ return {
713
+ "applies": applies,
714
+ "stack": spec.bar.stack,
715
+ "note": (
716
+ "Stacked bars pile the colour levels on one tick; no error bars, "
717
+ "no sample points."
718
+ if applies and spec.bar.stack
719
+ else None
720
+ ),
721
+ }
722
+
723
+
539
724
  def histogram_summary(spec: PlotSpec, table: LongTable) -> dict:
540
725
  """The Histogram section's data model: whether it applies, whether the
541
726
  binned measure is a datetime (the width then takes a duration), the
@@ -587,7 +772,7 @@ def sample_overlay_summary(
587
772
  of a point's identity, which a deeper tick implies for every shallower
588
773
  key). ``ignored`` are ticked names that are not collapsed right now.
589
774
  """
590
- reason = overlay_unavailable(spec, roles, shape)
775
+ reason = overlay_unavailable(spec, roles, shape, categorical_mode(spec, table))
591
776
  order = collapse_order(roles, table)
592
777
  steps = overlay_steps(spec, roles, table) if reason is None else None
593
778
  join = overlay_join(spec, roles, table, steps) if steps is not None else None