scistackplot 0.1.40__tar.gz → 0.1.42__tar.gz

{scistackplot-0.1.40 → 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.40 → scistackplot-0.1.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.40
+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.40
+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.40 → 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.40 → scistackplot-0.1.42}/src/scistackplot/codegen.py

@@ -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):
@@ -1695,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]:
@@ -1865,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.40 → 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
@@ -1385,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.40 → 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.40 → 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.40 → 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