scistackplot 0.1.33__tar.gz → 0.1.35__tar.gz

{scistackplot-0.1.33 → scistackplot-0.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.33
+Version: 0.1.35
 Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
 Author: SciStack Contributors
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.21
 Requires-Dist: pandas>=1.5
-Requires-Dist: scistacklog==0.1.33
+Requires-Dist: scistacklog==0.1.35
 Provides-Extra: dev
 Requires-Dist: matplotlib>=3.6; extra == 'dev'
 Requires-Dist: plotly>=5.0; extra == 'dev'
@@ -32,6 +32,9 @@ Requires-Dist: plotly>=5.0; extra == 'interactive'
 Provides-Extra: mpl
 Requires-Dist: matplotlib>=3.6; extra == 'mpl'
 Requires-Dist: seaborn>=0.13; extra == 'mpl'
+Provides-Extra: plotly-export
+Requires-Dist: kaleido>=1.0; extra == 'plotly-export'
+Requires-Dist: plotly>=6.1; extra == 'plotly-export'
 Description-Content-Type: text/markdown
 
 # scistackplot
@@ -259,6 +262,18 @@ that looks like a data problem. `LongTable` carries each factor's real level
 order; sources that know better (SciDB knows its declared `schema_key_types`)
 supply it explicitly, and everything else falls back to a natural sort.
 
+## Missing levels stay visible
+
+A figure with no data for an x level that the rest of the plot has keeps an
+empty tick for it: under `subject=ITERATE`, the figure of a subject who never
+ran session 2 still shows a session 2 slot, so the gap reads as missing data.
+`PlotSpec.show_missing_levels=False` leaves those ticks off, which makes the
+remaining marks wider. "Missing" is measured against the plot's filtered
+rows, so a level you filtered out never comes back as an empty tick. Leaves
+of a nested axis work the same way, and no position is ever made for a
+combination no figure has. Either way `ResolvedPlot.missing_x` lists the
+levels, and the exported code draws the same ticks as the preview.
+
 ## Rendering
 
 Two backends translate the same reduced plot, so the interactive view and the
@@ -341,16 +356,20 @@ one owner (`resolve_sizes`, `rc_params`). The export, the generated code and
 the plotly preview (as px) all read it, under `rc_context` so nothing leaks
 into the next figure. See `docs/claude/plot-text-and-labels.md`.
 
-**Automatic size (the default).** With `base` unset (`None`), `scistackplot.autosize`
-makes each unfixed element as large as the figure lays it out cleanly, inside
-the band of `TextSizes.target`: `"print"` (8–12 pt, the default) or `"slide"`
-(14–28 pt), in points at the saved size. It searches per element on real
-matplotlib layouts. A rotated or shrunk x tick limits only `x_ticks`, a legend
-moved below limits only `legend`, and a plot area under 55 % of the canvas
-limits all of them. The chosen sizes ride on `ResolvedPlot.auto_text`, and
-every renderer reads them through `textsize.sizes_for`.
-`settle_text_size(resolved)` runs the search by hand. A number in `base`
-turns it off.
+**Automatic size (the default).** `base` is ONE reference size; every unfixed
+element is drawn at reference × its ratio (`DEFAULT_TEXT_RATIOS`: title 1.44,
+axis and legend titles 1.2, the rest 1.0, overridable per element in
+`TextSizes.ratios`), clamped into that element's floor/ceiling (the band of
+`TextSizes.target` × the ratio — `"print"` 8–12 pt, `"slide"` 14–28 pt — or
+`TextSizes.floors` / `ceilings` in pt). With `base` unset (`None`),
+`scistackplot.autosize` searches the largest reference whose real matplotlib
+layout breaks no rule: no text into text (tick fit, numeric tick collisions,
+neighbouring panels, brackets, legend), nothing off the canvas, at least 3
+tick labels per numeric axis, no y title taller than its panel. One failing
+rule steps all the text down together, so the proportions hold. The result
+rides on `ResolvedPlot.auto_text`, and every renderer reads it through
+`textsize.sizes_for`. `settle_text_size(resolved)` runs the search by hand. A
+number in `base` fixes the reference (unclamped).
 
 The figure's **paper** (white background, black text, a black frame round every
 panel, outward ticks, no grid, and the error-bar ink) has one owner,
@@ -432,6 +451,43 @@ key. The exported code writes the merged pins in as literals.
 `render.base.palette_for` stays the one owner of the colour a mark is drawn
 in. See `docs/claude/plot-colors.md`.
 
+## Your own plot function
+
+A `plot_` function of your project can draw the figure instead of a built-in
+kind. Plot Studio opens on it from the `plot_` node, and the node's edges bind
+its inputs. The same works from code:
+
+```python
+from dataclasses import replace
+
+from scistackplot import CustomCall, CustomPlot, PlotKind, resolve_custom, write_figure
+
+def plot_steps(steps, mass, ax, context):
+    for _, row in steps.iterrows():
+        ax.plot([context.x(row)], [row["StepLength"]], "o", color=context.color_of(row["session"]))
+
+call = CustomCall(fn=plot_steps, inputs={"steps": steps_table, "mass": mass_table},
+                  variables={"steps": "StepLength", "mass": "Mass"})
+spec = replace(spec, kind=PlotKind.CUSTOM, custom=CustomPlot(function="plot_steps"))
+for figure in resolve_custom(spec, call):
+    write_figure(figure, f"{figure.figure_label}.png")
+```
+
+**With an `ax` parameter**, the function draws one panel per call, and
+everything else is scistackplot's: panels, ticks, legend, text, size and
+colours. `context.x(...)` places a mark on the tick its group levels name.
+**Without `ax`**, it returns a whole matplotlib or plotly figure; only the
+data settings and the size apply.
+
+**What the function receives:**
+- Each input is its own table: rows selected by the figure's and panel's
+  levels, with the inner collapsed keys averaged away.
+- An input at a coarser level is passed whole to every call.
+- With `as_table` off, an input arrives as the bare value instead of a table.
+
+Writing a plotly figure needs `pip install "scistackplot[plotly-export]"`.
+See `docs/claude/custom-plot-kinds.md`.
+
 ## Export: real code, not a call back into this library
 
 ```python

{scistackplot-0.1.33 → scistackplot-0.1.35}/README.md

@@ -223,6 +223,18 @@ that looks like a data problem. `LongTable` carries each factor's real level
 order; sources that know better (SciDB knows its declared `schema_key_types`)
 supply it explicitly, and everything else falls back to a natural sort.
 
+## Missing levels stay visible
+
+A figure with no data for an x level that the rest of the plot has keeps an
+empty tick for it: under `subject=ITERATE`, the figure of a subject who never
+ran session 2 still shows a session 2 slot, so the gap reads as missing data.
+`PlotSpec.show_missing_levels=False` leaves those ticks off, which makes the
+remaining marks wider. "Missing" is measured against the plot's filtered
+rows, so a level you filtered out never comes back as an empty tick. Leaves
+of a nested axis work the same way, and no position is ever made for a
+combination no figure has. Either way `ResolvedPlot.missing_x` lists the
+levels, and the exported code draws the same ticks as the preview.
+
 ## Rendering
 
 Two backends translate the same reduced plot, so the interactive view and the
@@ -305,16 +317,20 @@ one owner (`resolve_sizes`, `rc_params`). The export, the generated code and
 the plotly preview (as px) all read it, under `rc_context` so nothing leaks
 into the next figure. See `docs/claude/plot-text-and-labels.md`.
 
-**Automatic size (the default).** With `base` unset (`None`), `scistackplot.autosize`
-makes each unfixed element as large as the figure lays it out cleanly, inside
-the band of `TextSizes.target`: `"print"` (8–12 pt, the default) or `"slide"`
-(14–28 pt), in points at the saved size. It searches per element on real
-matplotlib layouts. A rotated or shrunk x tick limits only `x_ticks`, a legend
-moved below limits only `legend`, and a plot area under 55 % of the canvas
-limits all of them. The chosen sizes ride on `ResolvedPlot.auto_text`, and
-every renderer reads them through `textsize.sizes_for`.
-`settle_text_size(resolved)` runs the search by hand. A number in `base`
-turns it off.
+**Automatic size (the default).** `base` is ONE reference size; every unfixed
+element is drawn at reference × its ratio (`DEFAULT_TEXT_RATIOS`: title 1.44,
+axis and legend titles 1.2, the rest 1.0, overridable per element in
+`TextSizes.ratios`), clamped into that element's floor/ceiling (the band of
+`TextSizes.target` × the ratio — `"print"` 8–12 pt, `"slide"` 14–28 pt — or
+`TextSizes.floors` / `ceilings` in pt). With `base` unset (`None`),
+`scistackplot.autosize` searches the largest reference whose real matplotlib
+layout breaks no rule: no text into text (tick fit, numeric tick collisions,
+neighbouring panels, brackets, legend), nothing off the canvas, at least 3
+tick labels per numeric axis, no y title taller than its panel. One failing
+rule steps all the text down together, so the proportions hold. The result
+rides on `ResolvedPlot.auto_text`, and every renderer reads it through
+`textsize.sizes_for`. `settle_text_size(resolved)` runs the search by hand. A
+number in `base` fixes the reference (unclamped).
 
 The figure's **paper** (white background, black text, a black frame round every
 panel, outward ticks, no grid, and the error-bar ink) has one owner,
@@ -396,6 +412,43 @@ key. The exported code writes the merged pins in as literals.
 `render.base.palette_for` stays the one owner of the colour a mark is drawn
 in. See `docs/claude/plot-colors.md`.
 
+## Your own plot function
+
+A `plot_` function of your project can draw the figure instead of a built-in
+kind. Plot Studio opens on it from the `plot_` node, and the node's edges bind
+its inputs. The same works from code:
+
+```python
+from dataclasses import replace
+
+from scistackplot import CustomCall, CustomPlot, PlotKind, resolve_custom, write_figure
+
+def plot_steps(steps, mass, ax, context):
+    for _, row in steps.iterrows():
+        ax.plot([context.x(row)], [row["StepLength"]], "o", color=context.color_of(row["session"]))
+
+call = CustomCall(fn=plot_steps, inputs={"steps": steps_table, "mass": mass_table},
+                  variables={"steps": "StepLength", "mass": "Mass"})
+spec = replace(spec, kind=PlotKind.CUSTOM, custom=CustomPlot(function="plot_steps"))
+for figure in resolve_custom(spec, call):
+    write_figure(figure, f"{figure.figure_label}.png")
+```
+
+**With an `ax` parameter**, the function draws one panel per call, and
+everything else is scistackplot's: panels, ticks, legend, text, size and
+colours. `context.x(...)` places a mark on the tick its group levels name.
+**Without `ax`**, it returns a whole matplotlib or plotly figure; only the
+data settings and the size apply.
+
+**What the function receives:**
+- Each input is its own table: rows selected by the figure's and panel's
+  levels, with the inner collapsed keys averaged away.
+- An input at a coarser level is passed whole to every call.
+- With `as_table` off, an input arrives as the bare value instead of a table.
+
+Writing a plotly figure needs `pip install "scistackplot[plotly-export]"`.
+See `docs/claude/custom-plot-kinds.md`.
+
 ## Export: real code, not a call back into this library
 
 ```python

{scistackplot-0.1.33 → scistackplot-0.1.35}/pyproject.toml

@@ -58,6 +58,13 @@ mpl = [
 interactive = [
     "plotly>=5.0",
 ]
+# Writing a plotly figure a custom plot_ function returned to a file
+# (scistackplot.custom.write_plotly). kaleido 1.x also needs Chrome, which
+# `plotly_get_chrome` installs.
+plotly-export = [
+    "plotly>=6.1",
+    "kaleido>=1.0",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",

{scistackplot-0.1.33 → scistackplot-0.1.35}/src/scistackplot/__init__.py

@@ -97,6 +97,18 @@ from .roles import (
 from .restore import NoteKind, RestoreError, RestoreNote, Restored, reconcile, restore_spec
 from .presets import FieldClass, apply_preset, make_template, shape_warning
 from .compare import CompareMode, Comparison
+from .custom import (
+    CustomCall,
+    CustomFunctionError,
+    CustomSignature,
+    PlotContext,
+    custom_capabilities,
+    custom_requirement,
+    inspect_function,
+    preview_payload as custom_preview,
+    resolve_custom,
+    resolve_custom_one,
+)
 from .diffbars import DifferenceBar, bars_for_panel, slot_endpoints
 from .panels import PanelOverride, override_for
 from .shape import Shape, classify_column, classify_value, is_plottable
@@ -112,6 +124,8 @@ from .spec import (
     LocationFilter,
     MatchOp,
     Matcher,
+    BUILTIN_KINDS,
+    CustomPlot,
     PlotKind,
     PlotSpec,
     Role,
@@ -120,14 +134,23 @@ from .spec import (
     Statistic,
     Alias,
     StyleOptions,
+    TEXT_ELEMENTS,
     TEXT_TARGETS,
     TextSizes,
     VariantSet,
     YAxis,
     grid_shape_for,
 )
-from .textsize import ResolvedSizes, rc_params, resolve_sizes, sizes_for
-from .autosize import AutoTextSize, BANDS, settle as settle_text_size
+from .textsize import (
+    BANDS,
+    DEFAULT_TEXT_RATIOS,
+    ResolvedSizes,
+    drawn_sizes,
+    rc_params,
+    resolve_sizes,
+    sizes_for,
+)
+from .autosize import AutoTextSize, settle as settle_text_size
 from .aliases import AliasError, DisplayText, display_text
 from .colors import ColorError, MarkColors, mark_colors, parse_color
 from .figsize import (
@@ -185,6 +208,8 @@ __all__ = [
     "PlotSpec",
     "Role",
     "PlotKind",
+    "BUILTIN_KINDS",
+    "CustomPlot",
     "Statistic",
     "ErrorBand",
     "Aggregation",
@@ -209,6 +234,17 @@ __all__ = [
     # difference bars (.claude/plan-difference-bars.md)
     "CompareMode",
     "Comparison",
+    # custom plot kinds: a user plot_ function draws the figure
+    "CustomCall",
+    "CustomFunctionError",
+    "CustomSignature",
+    "PlotContext",
+    "custom_capabilities",
+    "custom_requirement",
+    "inspect_function",
+    "custom_preview",
+    "resolve_custom",
+    "resolve_custom_one",
     "DifferenceBar",
     "bars_for_panel",
     "slot_endpoints",
@@ -232,9 +268,12 @@ __all__ = [
     "ResolvedSizes",
     "resolve_sizes",
     "sizes_for",
+    "drawn_sizes",
+    "DEFAULT_TEXT_RATIOS",
     "rc_params",
     # automatic text size (autosize)
     "TEXT_TARGETS",
+    "TEXT_ELEMENTS",
     "BANDS",
     "AutoTextSize",
     "settle_text_size",