scistackplot 0.1.39__tar.gz → 0.1.42__tar.gz

{scistackplot-0.1.39 → scistackplot-0.1.42}/.gitignore

@@ -32,3 +32,6 @@ scistack-gui/frontend/dist/
 *.log
 output.txt
 scimatlab/tests/matlab/test-failures.txt
+
+# csv-stats is its own repo (github.com/mtillman14/csv-stats), cloned here for editable dev
+/csv-stats/

{scistackplot-0.1.39 → scistackplot-0.1.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.39
+Version: 0.1.42
 Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
 Author: SciStack Contributors
 License-Expression: MIT
@@ -17,9 +17,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: csv-stats>=0.2.1
 Requires-Dist: numpy>=1.21
 Requires-Dist: pandas>=1.5
-Requires-Dist: scistacklog==0.1.39
+Requires-Dist: scistacklog==0.1.42
 Provides-Extra: dev
 Requires-Dist: matplotlib>=3.6; extra == 'dev'
 Requires-Dist: plotly>=5.0; extra == 'dev'

{scistackplot-0.1.39 → scistackplot-0.1.42}/pyproject.toml

@@ -47,6 +47,9 @@ classifiers = [
 dependencies = [
     "pandas>=1.5",
     "numpy>=1.21",
+    # The one owner of every descriptive formula (error bars: spread.py).
+    # Core only: numpy, pandas, scipy. Not a scistack sibling, so not coversioned.
+    "csv-stats>=0.2.1",
     "scistacklog",
 ]
 

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/codegen.py

@@ -64,7 +64,7 @@ from .spec import (
 from .table import MISSING_LEVEL, LongTable
 from .paper import PAPER, figure_rc_params, paper_axes_code, seaborn_err_kws
 from .textsize import ResolvedSizes, resolve_sizes
-from .weights import sample_weight, spaghetti_weight
+from .weights import SAMPLE_EDGE_WIDTH, sample_weight, spaghetti_weight
 from .ylimits import GLOBAL_KEY, pinned_ends
 from .variants import (
     LATEST,
@@ -88,7 +88,9 @@ SPEC_BEGIN = "scistackplot-spec:"
 _SEABORN_ERRORBAR = {
     ErrorBand.SD: '"sd"',
     ErrorBand.SEM: '"se"',
-    ErrorBand.CI95: '("ci", 95)',
+    # Not seaborn's ("ci", 95): that is a bootstrap; the preview is t-based.
+    # `_ci95` is csvstats.descriptive.ci_interval, bound by `_ci95_lines`.
+    ErrorBand.CI95: "_ci95",
     ErrorBand.IQR: '("pi", 50)',
     ErrorBand.NONE: "None",
 }
@@ -227,6 +229,7 @@ def _generate_plot_function(
             else []
         ),
         *(["    import numpy as np"] if collapsing else []),
+        *(["    from csvstats.descriptive import ci_interval"] if _uses_ci95(spec, shape) else []),
         *(
             ["    import re"]
             if spec.kind is PlotKind.SPAGHETTI
@@ -484,7 +487,8 @@ def _docstring(spec: PlotSpec, table: LongTable, roles: dict, y_plan: _YLimitPla
         chain = " -> ".join([*steps.pre, " x ".join(steps.sample)])
         if spec.kind in (PlotKind.BAR, PlotKind.BAND):
             what = (
-                f"error bars: {spec.aggregate.error} across "
+                f"error bars: {spec.aggregate.error}"
+                f"{' (t-based)' if spec.aggregate.error is ErrorBand.CI95 else ''} across "
                 f"{' x '.join(steps.sample)}{' (pooled)' if len(steps.sample) > 1 else ''}"
             )
         elif spec.kind in (PlotKind.BOX, PlotKind.VIOLIN):
@@ -1309,7 +1313,7 @@ def _sample_draw_lines(
                     ),
                     f"            _ax.scatter(_part[{_X_POSITION!r}], _part[{y!r}], "
                     f"s={weight.marker_area:.3f}, color=_point_colors, alpha={SAMPLE_ALPHA}, "
-                    f"edgecolors={SAMPLE_EDGE_COLOR!r}, linewidths=0.5, "
+                    f"edgecolors={SAMPLE_EDGE_COLOR!r}, linewidths={SAMPLE_EDGE_WIDTH:g}, "
                     + (
                         # Over the line, and marked as part of its run
                         # (render.base.SAMPLE_LINE_POINTS_GID), as the preview.
@@ -1325,7 +1329,8 @@ def _sample_draw_lines(
             "        _ax.plot(",
             f"            _part[{_X_POSITION!r}], _part[{y!r}],",
             f"            linestyle={linestyle!r}, marker='o', markersize={weight.marker_pt:.3f},",
-            f"            markeredgecolor={SAMPLE_EDGE_COLOR!r}, markeredgewidth=0.5,",
+            f"            markeredgecolor={SAMPLE_EDGE_COLOR!r}, "
+            f"markeredgewidth={SAMPLE_EDGE_WIDTH:g},",
             f"            color={paint}, alpha={SAMPLE_ALPHA}, "
             f"linewidth={weight.line_pt:.3f}, zorder=3,",
             "        )",
@@ -1363,7 +1368,7 @@ def _sample_legend_lines(
         "    for _lvl in _sample_levels:",
         "        _entries[_lvl] = Line2D([], [], color=_sample_palette[_lvl], "
         f"linestyle={linestyle!r}, marker='o', markeredgecolor={SAMPLE_EDGE_COLOR!r}, "
-        "markeredgewidth=0.5)",
+        f"markeredgewidth={SAMPLE_EDGE_WIDTH:g})",
         f"    g.add_legend(legend_data=_entries, title={title!r})",
     ]
 
@@ -1694,6 +1699,32 @@ def _alias_relabel_lines(aliases: _ExportAliases, x_categorical: bool) -> list[s
     return lines
 
 
+def _uses_ci95(spec, shape) -> bool:
+    """True when the plot call passes `errorbar=_ci95` (bar and band only)."""
+    return (
+        shape is not Shape.MATRIX_2D
+        and spec.kind in (PlotKind.BAR, PlotKind.BAND)
+        and spec.aggregate.error is ErrorBand.CI95
+    )
+
+
+def _ci95_lines(spec, shape) -> list[str]:
+    """Bind `_ci95`, the errorbar callable: csv-stats' t-based CI.
+
+    The preview gets its CI95 from `csvstats.descriptive` (via `spread`), so
+    the exported code calls the same function rather than restating it.
+    """
+    if not _uses_ci95(spec, shape):
+        return []
+    if spec.aggregate.statistic is Statistic.MEDIAN:
+        return [
+            "# t-based 95% CI (csvstats.descriptive), on the median like the bars",
+            '_ci95 = lambda values: ci_interval(values, centre="median")',
+            "",
+        ]
+    return ["# t-based 95% CI of the mean (csvstats.descriptive)", "_ci95 = ci_interval", ""]
+
+
 def _plot_call(
     spec, table, roles, shape, y_plan: _YLimitPlan, base: LongTable | None = None
 ) -> list[str]:
@@ -1864,6 +1895,7 @@ def _plot_call(
     aliases = _export_aliases(spec, table, roles, shape)
     lines = [
         *order_lines,
+        *_ci95_lines(spec, shape),
         *palette_lines,
         *_alias_definition_lines(aliases),
         f"g = {call}(",

scistackplot-0.1.42/src/scistackplot/design.py

@@ -0,0 +1,275 @@
+"""Which plot settings are the DATA DESIGN, the one owner (statistics S11).
+
+A figure and a StatStudio table may hold different designs (user decision
+2026-10-17). Both studios show a banner when they diverge, and each has a
+one-way "Sync to…" button. What syncs is the design and only the design: the
+variables, the roles, the grouping order, the collapse, filters and
+exclusions, joined factors, combines and variant selection. Display settings
+(kind, colours, sizes, text, layout) never sync. Neither do stats-only
+settings, which do not live on a ``PlotSpec`` at all.
+
+:data:`DESIGN_FIELDS` classifies every ``PlotSpec`` field once. It is read by:
+
+- :func:`design_of` / :func:`design_fingerprint`: what a stats spec stores,
+  and what the banners compare;
+- :func:`design_diff`: the banner's list of differences, with labels;
+- :func:`copy_design`: the Sync buttons, in both directions.
+
+``tests/test_design.py`` fails on an unclassified field, the same guard
+``presets.FIELD_CLASSES`` has. The two tables answer different questions
+(what travels with a preset vs. what is the design), so they are separate,
+but each has one owner.
+
+The plot layer never imports statistics. A stats spec *holds* a ``PlotSpec``
+as its design carrier, and the GUI service compares the two.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, fields, replace
+from enum import Enum
+from typing import Any
+
+from scistacklog import Log
+
+from .spec import Aggregation, PlotSpec, Role
+
+LAYER = "scistackplot"
+
+
+class SyncClass(str, Enum):
+    """Whether a setting is part of the data design."""
+
+    #: Changes which rows exist or what a row means. Syncs.
+    DESIGN = "design"
+    #: How the rows are drawn. Never syncs.
+    DISPLAY = "display"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+_D, _P = SyncClass.DESIGN, SyncClass.DISPLAY
+
+#: Blocks classified per sub-field: ``aggregate.pooled`` changes the rows
+#: (weight by N), while ``aggregate.statistic`` / ``.error`` only draw them.
+_SPLIT_BLOCKS: dict[str, type] = {"aggregate": Aggregation}
+
+#: Every ``PlotSpec`` field, classified. Paths into split blocks are dotted.
+DESIGN_FIELDS: dict[str, SyncClass] = {
+    "measures": _D,
+    "variant_sets": _D,
+    "x_measure": _D,
+    "roles": _D,
+    "groups": _D,
+    # Which grouping layer is painted. The layer itself is in `groups`.
+    "color": _P,
+    # Kind decides the drawing. The stats layer reads its rows at a fixed
+    # analysis kind, so a bar-vs-box choice never moves a number.
+    "kind": _P,
+    "custom": _P,
+    "aggregate.statistic": _P,
+    "aggregate.error": _P,
+    "aggregate.pooled": _D,
+    # A 1-D measure's cell statistic makes the scalar each row holds.
+    "cell_statistic": _D,
+    "index_column": _D,
+    "show_sample": _P,
+    "join_sample": _P,
+    "sample_color": _P,
+    "sample_in_legend": _P,
+    "show_missing_levels": _P,
+    "facet": _P,
+    "y_axis": _P,
+    "style": _P,
+    "aliases": _P,
+    "colors": _P,
+    "panel_overrides": _P,
+    "difference_bars": _P,
+    # Compare-to-reference changes the values themselves.
+    "comparison": _D,
+    "filters": _D,
+    "location_filter": _D,
+    "factor_variables": _D,
+    "level_groups": _D,
+}
+
+#: What the banner calls each design field.
+LABELS: dict[str, str] = {
+    "measures": "Variable",
+    "variant_sets": "Variants",
+    "x_measure": "X variable",
+    "roles": "Roles",
+    "groups": "Grouping order",
+    "aggregate.pooled": "Weight by N",
+    "cell_statistic": "Cell statistic",
+    "index_column": "Index column",
+    "comparison": "Compare to reference",
+    "filters": "Filters",
+    "location_filter": "Schema locations",
+    "factor_variables": "Joined factors",
+    "level_groups": "Combines",
+}
+
+
+def unclassified_fields() -> tuple[list[str], list[str]]:
+    """``(missing, stale)``: PlotSpec fields with no class, and entries naming
+    no field. Drives ``test_every_plot_field_is_classified``."""
+    expected: set[str] = set()
+    for f in fields(PlotSpec):
+        if not f.init:
+            continue
+        if f.name in _SPLIT_BLOCKS:
+            expected.update(f"{f.name}.{sub.name}" for sub in fields(_SPLIT_BLOCKS[f.name]))
+        else:
+            expected.add(f.name)
+    known = set(DESIGN_FIELDS)
+    return sorted(expected - known), sorted(known - expected)
+
+
+def design_paths() -> list[str]:
+    return [path for path, cls in DESIGN_FIELDS.items() if cls is SyncClass.DESIGN]
+
+
+def _value_at(spec: PlotSpec, path: str) -> Any:
+    head, _, tail = path.partition(".")
+    value = getattr(spec, head)
+    return getattr(value, tail) if tail else value
+
+
+def _jsonable(value: Any) -> Any:
+    """A design value as plain JSON, through the spec's own serialisers."""
+    if isinstance(value, Enum):
+        return str(value)
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    if hasattr(value, "__dataclass_fields__"):
+        return _jsonable(asdict(value))
+    return value
+
+
+def design_of(spec: PlotSpec) -> dict[str, Any]:
+    """The design fields of ``spec`` as JSON, keyed by path."""
+    return {path: _jsonable(_value_at(spec, path)) for path in design_paths()}
+
+
+def design_fingerprint(spec: PlotSpec) -> str:
+    """A short stable digest of :func:`design_of`, for "has it diverged?"."""
+    text = json.dumps(design_of(spec), sort_keys=True, default=str)
+    return hashlib.sha1(text.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass(frozen=True)
+class DesignDifference:
+    """One design field that differs between two specs."""
+
+    path: str
+    label: str
+    a: str
+    b: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"path": self.path, "label": self.label, "a": self.a, "b": self.b}
+
+
+def _summary(path: str, value: Any) -> str:
+    """Short human text for a design value (the banner's two sides)."""
+    if path == "roles" and isinstance(value, dict):
+        return ", ".join(f"{k}={v}" for k, v in sorted(value.items())) or "(none)"
+    if path == "groups" and isinstance(value, list):
+        # Innermost first in the spec; read outermost-first, as nested ticks do.
+        return " × ".join(reversed([str(v) for v in value])) or "(none)"
+    if isinstance(value, list) and all(isinstance(v, str) for v in value):
+        return ", ".join(value) or "(none)"
+    if value in (None, [], {}):
+        return "(none)"
+    if isinstance(value, bool):
+        return "on" if value else "off"
+    if isinstance(value, (str, int, float)):
+        return str(value)
+    text = json.dumps(value, sort_keys=True, default=str)
+    return text if len(text) <= 80 else text[:77] + "…"
+
+
+def design_diff(a: PlotSpec, b: PlotSpec) -> list[DesignDifference]:
+    """Every design field where ``a`` and ``b`` differ, in table order.
+
+    Roles compare as a mapping, so the order the roles were assigned in is not
+    a difference. Everything else compares by its JSON form.
+    """
+    da, db = design_of(a), design_of(b)
+    out = []
+    for path in design_paths():
+        va, vb = da[path], db[path]
+        same = (
+            dict(va or {}) == dict(vb or {})
+            if path == "roles"
+            else json.dumps(va, sort_keys=True, default=str) == json.dumps(vb, sort_keys=True, default=str)
+        )
+        if not same:
+            out.append(DesignDifference(path, LABELS.get(path, path), _summary(path, va), _summary(path, vb)))
+    Log.debug(
+        "design diff: %d field(s) differ%s",
+        len(out),
+        f" ({', '.join(d.path for d in out)})" if out else "",
+        layer=LAYER,
+    )
+    return out
+
+
+@dataclass(frozen=True)
+class SyncNote:
+    """A display setting that pointed at a factor the new design dropped."""
+
+    path: str
+    message: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"path": self.path, "message": self.message}
+
+
+def copy_design(source: PlotSpec, target: PlotSpec) -> tuple[PlotSpec, list[SyncNote]]:
+    """``target`` with every design field taken from ``source`` (one way,
+    wholesale — no merging). Display settings stay ``target``'s.
+
+    A display setting that names a factor no longer in the right role is
+    cleared, with a note: the colour must be a grouping layer, and
+    "show sample" and its colour must name collapsed keys.
+    """
+    changes: dict[str, Any] = {}
+    for path in design_paths():
+        head, _, tail = path.partition(".")
+        if tail:
+            block = changes.get(head, getattr(target, head))
+            changes[head] = replace(block, **{tail: getattr(getattr(source, head), tail)})
+        else:
+            changes[head] = getattr(source, head)
+    result = replace(target, **changes)
+    notes: list[SyncNote] = []
+    grouped = {name for name, role in result.roles.items() if role is Role.GROUP}
+    collapsed = {name for name, role in result.roles.items() if role is Role.COLLAPSE}
+    if result.color and result.color not in grouped:
+        notes.append(SyncNote("color", f"colour by {result.color!r} cleared: it is no longer a grouping layer"))
+        result = replace(result, color=None)
+    kept = [name for name in result.show_sample if name in collapsed]
+    if kept != list(result.show_sample):
+        dropped = [n for n in result.show_sample if n not in collapsed]
+        notes.append(SyncNote("show_sample", f"show sample for {dropped!r} cleared: no longer collapsed"))
+        result = replace(result, show_sample=kept)
+    if result.sample_color and result.sample_color not in result.roles:
+        notes.append(SyncNote("sample_color", f"sample colour {result.sample_color!r} cleared"))
+        result = replace(result, sample_color=None)
+    Log.info(
+        "design sync: %d design field(s) copied, %d display note(s)%s",
+        len(design_paths()),
+        len(notes),
+        "".join(f"; {n.message}" for n in notes),
+        layer=LAYER,
+    )
+    return result, notes

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/diffbars.py

@@ -44,6 +44,8 @@ LAYER = "scistackplot"
 
 #: The label a new bar carries.
 DEFAULT_LABEL = "*"
+#: ``DifferenceBar.origin`` of a bar the user placed.
+MANUAL = "manual"
 
 
 @dataclass(frozen=True)
@@ -55,12 +57,17 @@ class DifferenceBar:
     - ``a``, ``b``: the two ends, ``{x layer: level text}`` over EVERY x
       layer (a nested axis names each layer). Unordered.
     - ``label``: drawn over the bar's middle.
+    - ``origin``: who made it. ``"manual"`` (clicked in Plot Studio, stored
+      on the spec), or another tag for a bar derived at resolve time by a
+      layer above (``"test"``: a statistics result; never stored). The plot
+      layer draws every origin the same way and never asks what made a bar.
     """
 
     match: dict[str, str] = field(default_factory=dict)
     a: dict[str, str] = field(default_factory=dict)
     b: dict[str, str] = field(default_factory=dict)
     label: str = DEFAULT_LABEL
+    origin: str = MANUAL
 
     def problem(self) -> str | None:
         """Why this bar can never be drawn anywhere, or None."""
@@ -97,12 +104,15 @@ class DifferenceBar:
         )
 
     def to_dict(self) -> dict:
-        return {
+        out = {
             "match": dict(self.match),
             "a": dict(self.a),
             "b": dict(self.b),
             "label": self.label,
         }
+        if self.origin != MANUAL:
+            out["origin"] = self.origin
+        return out
 
     @classmethod
     def from_dict(cls, raw: dict) -> "DifferenceBar":
@@ -112,6 +122,7 @@ class DifferenceBar:
             a=_text_dict(raw.get("a")),
             b=_text_dict(raw.get("b")),
             label=DEFAULT_LABEL if label is None else str(label),
+            origin=str(raw.get("origin") or MANUAL),
         )
 
     @classmethod
@@ -428,8 +439,15 @@ def log_figure(resolved: "ResolvedPlot") -> None:
 # bars need depends on ``u``, which depends on the top, so the top is found
 # by iterating to a fixed point (:func:`place_group`).
 
-#: Clearance between whatever is below and a bar's line (or a leg's foot).
+#: Clearance between whatever is below and a bar's line.
 GAP_PT = 3.0
+#: Clearance between the data under an end and that leg's foot (2026-10-16:
+#: at GAP_PT the leg read as touching the data). Larger than GAP_PT: the line
+#: only spans, a leg points AT a mark.
+FOOT_GAP_PT = 6.0
+#: The shortest a leg is drawn, from its foot to the line (2026-10-16:
+#: before, the leg over the taller end was half a line width — no leg).
+MIN_LEG_PT = 5.0
 #: A bar's line width.
 LINE_PT = 1.0
 #: Between the line and the bottom of its label's box.
@@ -560,6 +578,8 @@ class BarSizes:
     #: The label's font size (``TextSizes.differences``).
     label_font_pt: float
     gap_pt: float = GAP_PT
+    foot_gap_pt: float = FOOT_GAP_PT
+    min_leg_pt: float = MIN_LEG_PT
     line_pt: float = LINE_PT
     label_gap_pt: float = LABEL_GAP_PT
     pad_pt: float = PAD_PT
@@ -703,19 +723,31 @@ def _place_once(
             floors.append(under_label - above_line)
         floor = max(floors) if floors else bottom
         y = floor + (sizes.gap_pt + half_line) / per_y
+
+        # Each leg stops ``foot_gap_pt`` above what is under its end, so it
+        # never reads as touching the data. The line rises until every leg is
+        # at least ``min_leg_pt`` long (the end under the span's highest mark,
+        # or a lower bar's level, would otherwise get no visible leg). Both in
+        # points, so neither changes with the y range.
+        min_leg = sizes.min_leg_pt / per_y
+        foot_gap = sizes.foot_gap_pt / per_y
+        # A leg is a line: what it must clear is under its whole width, not
+        # its centre (a marker 3.01 pt off a leg of half-width 0.5 pt with a
+        # 3.5 pt reach was missed at the centre and touched, 2026-10-16).
+        half_leg = half_line / per_x
+        unders = [height(x - half_leg, x + half_leg) for x in (left, right)]
+        raised = [under + foot_gap + min_leg for under in unders if under is not None]
+        if raised:
+            y = max(y, max(raised))
+        feet = [
+            under + foot_gap
+            if under is not None
+            else max(bottom, y - max(2 * sizes.gap_pt / per_y, min_leg))
+            for under in unders
+        ]
         label_bottom = y + above_line
         label_top = label_bottom + height_pt / per_y
 
-        feet = []
-        for x in (left, right):
-            under = height(x, x)
-            foot = (
-                min(y, under + sizes.gap_pt / per_y)
-                if under is not None
-                else max(bottom, y - 2 * sizes.gap_pt / per_y)
-            )
-            feet.append(foot)
-
         if pinned and label_top > top:
             unfit.append(item)
             continue
@@ -842,6 +874,59 @@ def place_group(
     )
 
 
+def leg_lengths_pt(
+    result: GroupPlacement, frames: list[PanelFrame], log: bool = False
+) -> list[float]:
+    """Every placed leg's length in points on the final axis — what
+    ``MIN_LEG_PT`` guarantees (unless a leg reaches the axis bottom)."""
+    axis = (lambda v: math.log10(v)) if log else (lambda v: v)
+    bottom, top = axis(result.limits[0]), axis(result.limits[1])
+    lengths = []
+    for placed, frame in zip(result.placed, frames):
+        per_y = frame.height_pt / (top - bottom) if top > bottom else 0.0
+        for bar in placed:
+            for foot in (bar.left_foot, bar.right_foot):
+                lengths.append((axis(bar.y) - axis(foot)) * per_y)
+    return lengths
+
+
+def foot_clearances_pt(
+    result: GroupPlacement, problems: list[PanelProblem], log: bool = False
+) -> list[float]:
+    """Every placed foot's height above the data under it, in points on the
+    final axis — what ``FOOT_GAP_PT`` guarantees. *problems* hold the data's
+    obstacles only (no bars), so a foot resting over a lower bar reports
+    its height above the data, which is more than the gap. A foot with no
+    data under it is left out."""
+    axis = (lambda v: math.log10(v)) if log else (lambda v: v)
+    bottom, top = axis(result.limits[0]), axis(result.limits[1])
+    clearances = []
+    for placed, problem in zip(result.placed, problems):
+        if top <= bottom:
+            continue
+        per_y = problem.frame.height_pt / (top - bottom)
+        per_x = problem.frame.per_unit_x
+        obstacles = problem.obstacles.to_axis(log)
+        half_leg = (LINE_PT / 2.0) / per_x
+        for bar in placed:
+            for x, foot in ((bar.left, bar.left_foot), (bar.right, bar.right_foot)):
+                under = obstacles.top_over(
+                    x - half_leg, x + half_leg, per_unit_y=per_y, per_unit_x=per_x
+                )
+                if under is not None:
+                    clearances.append((axis(foot) - under) * per_y)
+    return clearances
+
+
+def _legs_note(result: GroupPlacement, problems: list[PanelProblem], log: bool) -> str:
+    lengths = leg_lengths_pt(result, [p.frame for p in problems], log)
+    clearances = foot_clearances_pt(result, problems, log)
+    note = f", shortest leg {min(lengths):.1f} pt" if lengths else ""
+    if clearances:
+        note += f", lowest foot {min(clearances):.1f} pt above the data"
+    return note
+
+
 # ---------------------------------------------------------------------------
 # A resolved figure -> problems
 
@@ -859,9 +944,10 @@ def panel_obstacles(resolved: "ResolvedPlot", panel: "Panel") -> Obstacles:
       ``spanmode: "hard"`` stop at the data); a box's flier adds its radius;
     - strip: every point, jittered ``±STRIP_JITTER``, plus the marker radius;
     - scatter: every point plus the marker radius;
-    - spaghetti: every point at its line's offset plus the marker radius,
+    - spaghetti: every point at its line's offset plus the marker's reach
+      (radius + half its edge stroke, ``weights.ResolvedWeight.marker_reach_pt``),
       and every segment of every run plus half the line width;
-    - overlay: every point at ``sample_positions`` plus its radius, and the
+    - overlay: every point at ``sample_positions`` plus its reach, and the
       joining segments when joined.
     """
     from .render.base import (
@@ -918,7 +1004,7 @@ def panel_obstacles(resolved: "ResolvedPlot", panel: "Panel") -> Obstacles:
                 xs, _ = x_positions(run[encoding.x], resolved)
                 xs = xs + offsets.get(str(series_id), 0.0)
                 ys = pd.to_numeric(run[encoding.y], errors="coerce").to_numpy(dtype=float)
-                rows.extend(_polyline(xs, ys, weight.marker_pt / 2.0, weight.line_pt / 2.0, True))
+                rows.extend(_polyline(xs, ys, weight.marker_reach_pt, weight.line_pt / 2.0, True))
         else:  # scatter, and anything else drawn as points
             rows.extend((p, p, v, v, marker_radius) for p, v in zip(positions, values))
 
@@ -929,7 +1015,7 @@ def panel_obstacles(resolved: "ResolvedPlot", panel: "Panel") -> Obstacles:
             xs = sample_positions(run.rows, resolved, run.identity)
             ys = pd.to_numeric(run.rows[encoding.y], errors="coerce").to_numpy(dtype=float)
             joined = resolved.sample_join and len(run.rows) > 1
-            rows.extend(_polyline(xs, ys, weight.marker_pt / 2.0, weight.line_pt / 2.0, joined))
+            rows.extend(_polyline(xs, ys, weight.marker_reach_pt, weight.line_pt / 2.0, joined))
     return Obstacles.build(rows)
 
 
@@ -1106,7 +1192,9 @@ def place_figure(
         notes.append(
             f"{names}: {sum(len(p) for p in result.placed)} placed, {n_unfit} unfit, "
             f"top {shared[1]:.6g} -> {result.limits[1]:.6g} "
-            f"({result.iterations} iteration(s), bars {result.bar_fraction:.0%} of the height)"
+            f"({result.iterations} iteration(s), bars {result.bar_fraction:.0%} of the height"
+            + _legs_note(result, problems, log)
+            + ")"
             + (f", raised to at least {top_floor:.6g} for other figures" if top_floor is not None else "")
         )
         Log.debug(
@@ -1308,3 +1396,35 @@ def difference_meta(
         # decisions) or the preview's estimate.
         "estimated": estimated,
     }
+
+
+# ---------------------------------------------------------------------------
+# Derived bars (a layer above hands bars in at resolve time)
+# ---------------------------------------------------------------------------
+
+
+def with_derived_bars(spec: "PlotSpec", derived: list[DifferenceBar]) -> "PlotSpec":
+    """``spec`` drawing ``derived`` bars as well as its own, for one resolve.
+
+    The one place derived bars join a figure. A derived bar is intent
+    computed from something else (a statistics result), so it is never
+    stored: callers resolve the returned spec and keep saving the original.
+    Derived bars go FIRST and the spec's manual bars after them, so on a
+    duplicate pair the manual bar's label wins (``bars_for_panel`` keeps the
+    last entry), and the duplicate derived bar is dropped here with a log
+    line rather than reaching the WARN.
+    """
+    from dataclasses import replace
+
+    manual = list(spec.difference_bars)
+    kept = [bar for bar in derived if not any(bar.same_pair(m) for m in manual)]
+    dropped = len(derived) - len(kept)
+    Log.info(
+        "difference bars: %d derived (%s) + %d manual%s",
+        len(kept),
+        ", ".join(sorted({bar.origin for bar in kept})) or "none",
+        len(manual),
+        f"; {dropped} derived bar(s) dropped (a manual bar has that pair)" if dropped else "",
+        layer=LAYER,
+    )
+    return replace(spec, difference_bars=[*kept, *manual])

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/export.py

@@ -608,3 +608,65 @@ def _describe_chain(options: DataExportOptions) -> str:
     if options.pooled:
         return " x ".join(options.chain) + " (pooled sample)"
     return " -> ".join([*options.chain[:-1], f"{options.chain[-1]} (sample)"])
+
+
+# ---------------------------------------------------------------------------
+# 1-D sample curves (statistics: SPM, plan stage 13)
+# ---------------------------------------------------------------------------
+
+
+def sample_curves(spec: PlotSpec, table: LongTable) -> pd.DataFrame:
+    """One row per SAMPLE per cell, its 1-D curve kept as an ndarray in the
+    measure column: the rows a statistical parametric mapping (SPM) test sees.
+
+    The same plan and collapse chain a 1-D band figure runs: ``reduce._plan``
+    and the numpy reducer's ``reducer._chain`` (per-position means over the
+    collapsed keys, deepest first). So the per-position mean across these
+    rows is the band's centre (``tests/test_sample_curves.py``). Every figure
+    of the fan-out goes into one frame, the figure keys as columns.
+
+    ``spec`` must draw the measure as 1-D (a line or band kind). A scalar kind
+    collapses each cell first and has no curves, so it raises ``ValueError``
+    saying so. Curves of unequal length are kept, with a WARN naming the
+    rows: an SPM test needs equal lengths and refuses them itself.
+    """
+    from collections import Counter
+
+    from .reduce import _plan
+    from .reducer import _chain
+    from .series_stats import cell_arrays
+
+    plan = _plan(spec, table)
+    if plan.shape is not Shape.SERIES_1D:
+        raise ValueError(
+            f"{spec.y_measure} is drawn as {plan.shape} for kind {spec.kind}; sample curves "
+            f"need a 1-D measure at a line or band kind"
+        )
+    steps = collapse_steps(plan.spec, plan.roles, plan.table)
+    y = plan.spec.y_measure
+    pieces: list[pd.DataFrame] = []
+    for figure_key, group in plan.groups:
+        frame = group.reset_index(drop=True)
+        arrays = cell_arrays(frame[y])
+        kept, arrays = _chain(frame, arrays, list(steps.pre), plan.table)
+        kept = kept.copy()
+        for name, value in figure_key.items():
+            if name not in kept.columns:
+                kept[name] = value
+        kept[y] = list(arrays)
+        pieces.append(kept)
+    out = pd.concat(pieces, ignore_index=True) if pieces else pd.DataFrame(columns=[y])
+    lengths = Counter(len(a) for a in out[y])
+    Log.info(
+        "[sample-curves] %s: %d figure(s), %d curve(s), lengths %s, %s averaged first",
+        y, len(plan.groups), len(out), dict(lengths), list(steps.pre) or "nothing", layer=LAYER,
+    )
+    if len(lengths) > 1:
+        common = lengths.most_common(1)[0][0]
+        odd = [i for i, a in enumerate(out[y]) if len(a) != common]
+        Log.warn(
+            "[sample-curves] %s: curves of unequal length (%s); rows %s differ from the common %d. "
+            "An SPM test refuses them: time-normalise first",
+            y, dict(lengths), odd[:10], common, layer=LAYER,
+        )
+    return out

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/render/mpl.py

@@ -25,7 +25,7 @@ from ..spec import PlotKind
 from ..table import natural_sort_key
 from ..paper import PAPER, apply_paper_axes, describe_paper, figure_rc_params
 from ..textsize import ResolvedSizes, sizes_for
-from ..weights import describe_weights, sample_weight, spaghetti_weight
+from ..weights import SAMPLE_EDGE_WIDTH, describe_weights, sample_weight, spaghetti_weight
 from ..ticklabels import (
     BRACKET_POLICY,
     TICK_POLICY,
@@ -396,6 +396,7 @@ def _draw_spaghetti(ax, frame, resolved) -> None:
                 # A diameter in pt (weights.spaghetti_weight): at 1x the same
                 # visual size as the scatter kinds' `s` area.
                 markersize=weight.marker_pt,
+                markeredgewidth=weight.marker_edge_pt,
                 label=(
                     resolved.text.color_level(level)
                     if (level is not None and position == 0)
@@ -629,7 +630,7 @@ def _draw_sample(ax, panel, resolved: ResolvedPlot) -> tuple[int, int]:
                 marker="o",
                 markersize=weight.marker_pt,
                 markeredgecolor=SAMPLE_EDGE_COLOR,
-                markeredgewidth=0.5,
+                markeredgewidth=weight.marker_edge_pt,
                 zorder=3,
             )
             continue
@@ -651,7 +652,7 @@ def _draw_sample(ax, panel, resolved: ResolvedPlot) -> tuple[int, int]:
             color=[run.point_colors[i] for i in order],
             alpha=SAMPLE_ALPHA,
             edgecolors=SAMPLE_EDGE_COLOR,
-            linewidths=0.5,
+            linewidths=weight.marker_edge_pt,
             zorder=3.1,
             gid=SAMPLE_LINE_POINTS_GID,
         )
@@ -663,7 +664,7 @@ def _draw_sample(ax, panel, resolved: ResolvedPlot) -> tuple[int, int]:
             color=color,
             alpha=SAMPLE_ALPHA,
             edgecolors=SAMPLE_EDGE_COLOR,
-            linewidths=0.5,
+            linewidths=weight.marker_edge_pt,
             zorder=3,
         )
     artists += len(lone)
@@ -687,7 +688,7 @@ def _sample_legend_handles(ax, resolved: ResolvedPlot) -> None:
             linestyle="-" if resolved.sample_join else "none",
             marker="o",
             markeredgecolor=SAMPLE_EDGE_COLOR,
-            markeredgewidth=0.5,
+            markeredgewidth=SAMPLE_EDGE_WIDTH,
             label=resolved.text.sample_level(level),
         )
 

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/render/plotly_.py

@@ -43,7 +43,7 @@ from ..diffbars import (
     sibling_floors,
 )
 from ..textsize import sizes_for
-from ..weights import mark_weights_meta, sample_weight, spaghetti_weight
+from ..weights import SAMPLE_EDGE_WIDTH, mark_weights_meta, sample_weight, spaghetti_weight
 from ..xaxis import LEAF_SEPARATOR
 from .base import (
     MARK_OFFSET_GROUP,
@@ -758,7 +758,7 @@ def _sample_traces(
                     if run.uniform
                     else [run.point_colors[i] for i in order],
                     "size": weight.marker_px,
-                    "line": {"color": SAMPLE_EDGE_COLOR, "width": 0.5},
+                    "line": {"color": SAMPLE_EDGE_COLOR, "width": SAMPLE_EDGE_WIDTH},
                 },
                 "line": {"color": run.line_color, "width": weight.line_pt},
                 "opacity": SAMPLE_ALPHA,

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/series_stats.py

@@ -38,6 +38,7 @@ from typing import Any
 import numpy as np
 
 from .spec import ErrorBand, Statistic
+from .spread import SD_DDOF, ci95_spread, sem_spread
 
 
 def cell_array(value: Any) -> np.ndarray:
@@ -187,18 +188,19 @@ def position_stats(
                 low[start:stop] = c
                 high[start:stop] = c
             elif error is ErrorBand.IQR:
+                # numpy's default interpolation is linear, csv-stats'
+                # QUANTILE_METHOD (pinned by tests/test_ci95.py).
                 low[start:stop] = np.nanpercentile(padded, 25, axis=0)
                 high[start:stop] = np.nanpercentile(padded, 75, axis=0)
             else:
-                sd = np.nanstd(padded, axis=0, ddof=1)
+                sd = np.nanstd(padded, axis=0, ddof=SD_DDOF)
                 sd = np.where(n >= 2, sd, 0.0)  # std(ddof=1).fillna(0.0)
-                denominator = np.where(n > 0, n, 1)  # count.where(count > 0, 1)
                 if error is ErrorBand.SD:
                     spread = sd
                 elif error is ErrorBand.SEM:
-                    spread = sd / np.sqrt(denominator)
-                else:  # CI95
-                    spread = 1.96 * sd / np.sqrt(denominator)
+                    spread = sem_spread(sd, n)
+                else:  # CI95 — t-based, csvstats.descriptive via spread
+                    spread = ci95_spread(sd, n)
                 low[start:stop] = c - spread
                 high[start:stop] = c + spread
     return centre, low, high, count

scistackplot-0.1.42/src/scistackplot/spread.py

@@ -0,0 +1,68 @@
+"""How a plot DRAWS a 95% confidence interval. The formula is not defined here.
+
+The formula belongs to ``csvstats.descriptive``, the one owner of every
+descriptive statistic in scistack (user decision 2026-10-17). It is the
+t-based interval of the mean, ``centre ± t(0.975, n - 1) · SD / √n``.
+StatStudio's tables and csv-stats' test results read the same functions, so a
+figure's error bar and a table's CI cannot disagree.
+
+This module adds only the drawing policy. csv-stats returns NaN when there
+are fewer than two values, and a plot draws that as a zero-width bar,
+matching the ``std(ddof=1).fillna(0.0)`` its SD bars already use.
+
+Consumers: ``ylimits.spread_bounds`` / ``ylimits._summary_bounds`` (pandas;
+what ``reduce._summarize`` draws), ``series_stats.position_stats`` (the numpy
+twin), and ``codegen``, whose exported code calls ``csvstats.descriptive.
+ci_interval`` as seaborn's ``errorbar=``.
+
+Before 2026-10-17 the preview drew ``1.96 · SEM`` and the export drew
+seaborn's bootstrap ``("ci", 95)``: two answers for one spec.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from csvstats.descriptive import QUANTILE_METHOD, SD_DDOF, ci_half_width, sem
+from scistacklog import Log
+
+LAYER = "scistackplot"
+
+#: SD_DDOF / QUANTILE_METHOD are csv-stats' conventions, re-exported for the plot's
+#: own groupby/nan reductions so they name the choice instead of restating it.
+__all__ = ["SD_DDOF", "QUANTILE_METHOD", "ci95_spread", "sem_spread"]
+
+
+def _zero_where_undefined(half: Any) -> Any:
+    """NaN (no interval below two values) drawn as a zero-width bar."""
+    if isinstance(half, pd.Series):
+        return half.fillna(0.0)
+    if np.ndim(half) == 0:
+        return 0.0 if np.isnan(half) else float(half)
+    return np.nan_to_num(half, nan=0.0)
+
+
+def sem_spread(sd: Any, count: Any) -> Any:
+    """Half-width of the SEM bar: csv-stats' SEM, 0 where it has none."""
+    return _zero_where_undefined(sem(sd, count))
+
+
+def ci95_spread(sd: Any, count: Any) -> Any:
+    """Half-width of the CI95 bar: csv-stats' value, 0 where it has none.
+
+    Takes and returns a scalar, numpy array or pandas Series (index kept).
+    """
+    half = ci_half_width(sd, count)
+    counts = np.asarray(count, dtype=float)
+    if counts.size:
+        valid = counts[counts >= 2]
+        if valid.size:
+            Log.debug(
+                "spread ci95: t-based (csvstats.descriptive), n %d..%d",
+                int(valid.min()),
+                int(valid.max()),
+                layer=LAYER,
+            )
+    return _zero_where_undefined(half)

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/weights.py

@@ -29,6 +29,14 @@ SAMPLE_MARKER_FRACTION = 0.45
 SAMPLE_LINE_WIDTH = 1.0
 #: A spaghetti's own polylines at 1x.
 SPAGHETTI_LINE_WIDTH = 1.2
+#: The edge stroke round a marker, in points, at every weight (it outlines;
+#: it does not scale). It widens the marker by half its width on each side,
+#: which ``diffbars.panel_obstacles`` must count (2026-10-16: a leg touched a
+#: spaghetti marker the obstacle model thought it cleared).
+SAMPLE_EDGE_WIDTH = 0.5
+#: matplotlib's ``lines.markeredgewidth`` default, which the spaghetti drew
+#: before it was stated here.
+SPAGHETTI_EDGE_WIDTH = 1.0
 #: The plotly preview draws a marker of ``d`` pt at ``d x 4/3`` px — the
 #: 96/72 pt-to-px ratio. Pinned so 1x reproduces the preview as it was (8 px
 #: markers where matplotlib draws 6 pt). Lines are 1 pt = 1 px, as before.
@@ -54,6 +62,13 @@ class ResolvedWeight:
     marker_pt: float
     #: Line width in points (and px in the preview).
     line_pt: float
+    #: The marker's edge stroke in points (``markeredgewidth``).
+    marker_edge_pt: float
+
+    @property
+    def marker_reach_pt(self) -> float:
+        """How far a marker reaches from its centre, edge included."""
+        return self.marker_pt / 2.0 + self.marker_edge_pt / 2.0
 
     @property
     def marker_area(self) -> float:
@@ -83,6 +98,7 @@ def sample_weight(style: StyleOptions) -> ResolvedWeight:
         weight=w,
         marker_pt=math.sqrt(style.marker_size * SAMPLE_MARKER_FRACTION) * w,
         line_pt=SAMPLE_LINE_WIDTH * w,
+        marker_edge_pt=SAMPLE_EDGE_WIDTH,
     )
 
 
@@ -94,6 +110,7 @@ def spaghetti_weight(style: StyleOptions) -> ResolvedWeight:
         weight=w,
         marker_pt=math.sqrt(style.marker_size) * w,
         line_pt=SPAGHETTI_LINE_WIDTH * w,
+        marker_edge_pt=SPAGHETTI_EDGE_WIDTH,
     )
 
 

{scistackplot-0.1.39 → scistackplot-0.1.42}/src/scistackplot/ylimits.py

@@ -47,6 +47,7 @@ from .numeric import coerce_numeric
 from .panels import PanelOverride
 from .shape import Shape
 from .spec import ErrorBand, PlotKind, PlotSpec, Role, Statistic
+from .spread import QUANTILE_METHOD, SD_DDOF, ci95_spread, sem_spread
 from .table import LongTable
 
 LAYER = "scistackplot"
@@ -730,15 +731,18 @@ def spread_bounds(grouped, centre, spec: PlotSpec):
     if error is ErrorBand.NONE:
         return centre, centre
     if error is ErrorBand.IQR:
-        return grouped.quantile(0.25), grouped.quantile(0.75)
-    sd = grouped.std(ddof=1).fillna(0.0)
+        return (
+            grouped.quantile(0.25, interpolation=QUANTILE_METHOD),
+            grouped.quantile(0.75, interpolation=QUANTILE_METHOD),
+        )
+    sd = grouped.std(ddof=SD_DDOF).fillna(0.0)
     count = grouped.count()
     if error is ErrorBand.SD:
         spread = sd
     elif error is ErrorBand.SEM:
-        spread = sd / np.sqrt(count.where(count > 0, 1))
-    else:  # CI95
-        spread = 1.96 * sd / np.sqrt(count.where(count > 0, 1))
+        spread = sem_spread(sd, count)
+    else:  # CI95 — t-based, csvstats.descriptive via spread
+        spread = ci95_spread(sd, count)
     return centre - spread, centre + spread
 
 
@@ -751,16 +755,20 @@ def _summary_bounds(values: pd.Series, spec: PlotSpec):
     if error is ErrorBand.NONE:
         return centre, centre, centre
     if error is ErrorBand.IQR:
-        return centre, values.quantile(0.25), values.quantile(0.75)
-    sd = values.std(ddof=1)
+        return (
+            centre,
+            values.quantile(0.25, interpolation=QUANTILE_METHOD),
+            values.quantile(0.75, interpolation=QUANTILE_METHOD),
+        )
+    sd = values.std(ddof=SD_DDOF)
     sd = 0.0 if pd.isna(sd) else sd
     count = max(len(values), 1)
     if error is ErrorBand.SD:
         spread = sd
     elif error is ErrorBand.SEM:
-        spread = sd / np.sqrt(count)
-    else:
-        spread = 1.96 * sd / np.sqrt(count)
+        spread = sem_spread(sd, count)
+    else:  # CI95 — t-based, csvstats.descriptive via spread
+        spread = ci95_spread(sd, count)
     return centre, centre - spread, centre + spread