quantized-lab 0.25.0__tar.gz → 0.26.0__tar.gz

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quantized-lab
-Version: 0.25.0
+Version: 0.26.0
 Summary: Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines.
 Project-URL: Homepage, https://github.com/pquarterman17/quantized
 Project-URL: Documentation, https://github.com/pquarterman17/quantized/wiki

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quantized-lab"
-version = "0.25.0"
+version = "0.26.0"
 description = "Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines."
 readme = "README.md"
 requires-python = ">=3.11"

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/__init__.py

@@ -7,5 +7,5 @@ Layered, enforced architecture (see CLAUDE.md):
 
 from __future__ import annotations
 
-__version__ = "0.25.0"
+__version__ = "0.26.0"
 __all__ = ["__version__"]

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/corrections.py

@@ -16,7 +16,9 @@ from typing import Any
 
 import numpy as np
 
+from ..cat_levels import surviving_cat_levels, surviving_level_order
 from ..datastruct import DataStruct
+from ..row_sidecars import slice_row_sidecars
 from .backgrounds import anchor_baseline, footprint_factor
 from .processing import (
     cumulative_integral,
@@ -96,6 +98,45 @@ def apply_corrections(
     """
     time = np.asarray(data.time, dtype=float).copy()
     values = np.asarray(data.values, dtype=float).copy()
+    # BUG-005: kept to decide, at the end, which `cat_levels` entries the
+    # pipeline actually invalidated. `values` above is mutated in place from here
+    # on, so the comparison needs its own reference.
+    values_in = np.asarray(data.values, dtype=float)
+    # BUG-005 review, HIGH 1. Bit-identity of a column is NOT evidence that its
+    # level codes survived: a transform can map codes to themselves by
+    # ARITHMETIC ACCIDENT. Measured on a single-level channel (every code 0,
+    # which is the commonest real case — a Sample/Phase/Status column constant
+    # within one file): dY/dX, ∫Y dx, a moving-average smooth, all four
+    # normalizations, a unit conversion and yScale=1000 each left it
+    # [0, 0, 0] and so kept the table, and `level_of` then returned the LABEL
+    # for a dY/dX channel. That is precisely the "labels for values that cannot
+    # have them" failure the strip exists to prevent.
+    #
+    # So the survival test is a CONJUNCTION: no step may have redefined what the
+    # channel IS (this flag), AND the numbers must be unchanged
+    # (`surviving_cat_levels`). Each half covers the other's blind spot — the
+    # flag catches an arithmetic coincidence, and the value comparison catches a
+    # step added later that forgets to set the flag.
+    #
+    # WHICH STEPS SET IT: those that REDEFINE THE QUANTITY — a derivative,
+    # integral, smooth, any normalization, a unit conversion, a mass/volume
+    # normalization, the footprint or neutron scale. After any of those the
+    # channel is no longer the thing its level table names, whatever the numbers
+    # happen to be.
+    #
+    # WHICH DO NOT: same-units arithmetic that is a genuine identity when its
+    # parameters are zero — the background/y-offset subtraction and the reference-
+    # dataset subtraction. Those run on EVERY call (`values - y_bg - y_off` is
+    # unconditional, with zeros by default), so flagging them made the flag always
+    # true and silently reverted this whole fix; the first version of it did
+    # exactly that and the identity/trim tests caught it. For these the value
+    # comparison IS the right test: subtract a real background and the codes move
+    # and are dropped; subtract zero and the channel is untouched.
+    #
+    # A NEW QUANTITY-REDEFINING STEP MUST SET THIS. `test_calc_corrections.py::
+    # test_corrections_drops_cat_levels_for_every_y_transforming_step` enumerates
+    # the current ones against a single-level channel.
+    y_touched = False
     labels = list(data.labels)
 
     # 0. Arbitrary X/Y rescaling (MAIN_PLAN #37) — a non-destructive unit
@@ -117,10 +158,12 @@ def apply_corrections(
         time = time * x_scale
     if y_scale != 1.0:
         values = values * y_scale
+        y_touched = True
 
     # 1. Trim on x.
     x_min = params.get("xTrimMin", float("nan"))
     x_max = params.get("xTrimMax", float("nan"))
+    kept_rows: list[int] | None = None
     if not (math.isnan(x_min) and math.isnan(x_max)):
         mask = np.ones(time.size, dtype=bool)
         if not math.isnan(x_min):
@@ -129,6 +172,18 @@ def apply_corrections(
             mask &= time <= x_max
         time = time[mask]
         values = values[mask, :]
+        # BUG-006 site 7. This is the ONLY step here that changes the ROW COUNT,
+        # so it is the only one whose row-indexed metadata sidecars need to move
+        # -- and they were riding through unsliced, which is strictly worse than
+        # the Extract/Split cases the bug started from: those produce a derived
+        # copy, while this response is written straight back into the dataset and
+        # the .dwk. Trim the first 50 of 100 rows and `text_columns` still held
+        # 100 cells starting at row 0, so every visible text cell described a
+        # row 50 places away. (An earlier version of this comment said "the code
+        # below already reasons about `excludedRows` shifting under this same
+        # trim" -- there is no `excludedRows` anywhere in this module; that
+        # reasoning is in the FRONTEND, `store/corrections.ts`.)
+        kept_rows = [int(i) for i in np.flatnonzero(mask)]
 
     # 2. X offset.
     time = time - params.get("xOff", 0.0)
@@ -145,6 +200,7 @@ def apply_corrections(
         for k in range(values.shape[1]):
             if labels[k].lower() != "dq":
                 values[:, k] = values[:, k] / factor
+                y_touched = True
 
     # 3. Neutron R-scale, or background subtraction + y-offset.
     y_off = params.get("yOff", 0.0)
@@ -152,6 +208,7 @@ def apply_corrections(
         for k in range(values.shape[1]):
             if labels[k].lower() != "dq":
                 values[:, k] = values[:, k] * y_off
+                y_touched = True
     else:
         # An anchor-point baseline (GOTO #2) beats the polynomial/slope forms.
         bg_anchors = params.get("bgAnchors")
@@ -197,41 +254,92 @@ def apply_corrections(
         m_unit = params.get("momentUnit", "")
         if m_unit == "emu/g" and params.get("sampleMass", 0.0) > 0:
             values = values / params["sampleMass"]
+            y_touched = True
         elif m_unit in ("emu/cm³", "kA/m") and params.get("sampleVolume", 0.0) > 0:
             values = values / params["sampleVolume"]
+            y_touched = True
         elif m_unit == "A·m²":
             values = values * 1e-3
+            y_touched = True
 
     # 6. Smoothing.
     if params.get("smoothEnabled", False):
         win = max(1, _matlab_round(params.get("smoothWindow", 5)))
         values = smooth_data(values, method=str(params["smoothMethod"]).lower(), window=win)
+        y_touched = True
 
     # 7. Normalization.
     norm = params.get("normMethod", "None")
     if norm == "Range [0,1]":
         values = normalize(values, method="range")
+        y_touched = True
     elif norm == "Peak (max=1)":
         values = normalize(values, method="peak")
+        y_touched = True
     elif norm == "Z-score":
         values = normalize(values, method="zscore")
+        y_touched = True
     elif norm == "Area (integral=1)":
         for k in range(values.shape[1]):
             area = float(np.trapezoid(values[:, k], time))
             if area != 0:
                 values[:, k] = values[:, k] / area
+                y_touched = True
 
     # 8. Derivative / integral transforms.
     deriv = params.get("derivativeMode", "None")
     if deriv == "dY/dX":
         values = derivative(time, values, order=1)
+        y_touched = True
     elif deriv == "d²Y/dX²":
         values = derivative(time, values, order=2)
+        y_touched = True
     elif deriv == "∫Y dx":
         values = cumulative_integral(time, values)
+        y_touched = True
     elif deriv == "dlog/dlog":
         values = log_derivative(time, values)
+        y_touched = True
 
+    # `cat_levels` IS CARRIED FORWARD ONLY WHERE THE CODES SURVIVED (BUG-005).
+    #
+    # Every step above transforms EVERY channel unconditionally (`for k in
+    # range(values.shape[1])`, plus whole-matrix `smooth_data`/`normalize`/
+    # `derivative` calls). A categorical channel's values are level CODES
+    # (0..n-1); smoothing or differentiating them yields fractional numbers with
+    # no level, so keeping the table would make the output claim labels for
+    # values that no longer index it — worse than showing the raw numbers.
+    #
+    # That was why this dropped the table. But it dropped it UNCONDITIONALLY,
+    # including when the codes demonstrably did not move: an identity correction
+    # (every step off) or a pure row TRIM, which selects rows and never touches a
+    # value. `surviving_cat_levels` (see `quantized/cat_levels.py`) now decides
+    # per channel by COMPARING the numbers, so a table is kept exactly when it
+    # still describes the output and dropped otherwise. Evidence, not inference
+    # about which parameters are identities — which is also why it cannot change
+    # any existing golden output.
+    #
+    # STILL BOOKED as BUG-005: corrections should not TRANSFORM a categorical
+    # channel at all. That needs a channel mask threaded through every step above
+    # and carries real golden-parity regression risk, so it is not faked here.
+    metadata = (
+        dict(data.metadata)
+        if kept_rows is None
+        else slice_row_sidecars(data.metadata, kept_rows)
+    )
+    surviving = (
+        None
+        if y_touched
+        else surviving_cat_levels(data.cat_levels, values_in, values, kept_rows)
+    )
     return DataStruct.create(
-        time, values, labels=labels, units=list(data.units), metadata=dict(data.metadata)
+        time,
+        values,
+        labels=labels,
+        units=list(data.units),
+        metadata=metadata,
+        cat_levels=surviving,
+        level_order=surviving_level_order(
+            data.level_order, surviving, np.array_equal(time, np.asarray(data.time, dtype=float))
+        ),
     )

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure.py

@@ -17,11 +17,16 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless: render to a buffer, never to a display
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402  (must follow matplotlib.use)
-import numpy as np
-from numpy.typing import ArrayLike, NDArray
+import numpy as np  # noqa: E402
+from numpy.typing import ArrayLike, NDArray  # noqa: E402
 
+from quantized.calc.figure_colorscatter import (  # noqa: E402
+    draw_color_scatter as _draw_color_scatter,
+)
+from quantized.calc.figure_greyscale import apply_greyscale  # noqa: E402
 from quantized.calc.figure_hitmap import collect_map as _collect_map_impl  # noqa: E402
 from quantized.calc.figure_labels import safe_mathtext_label  # noqa: E402
 from quantized.calc.figure_overrides import _apply_overrides, _validate_overrides  # noqa: E402
@@ -29,7 +34,7 @@ from quantized.calc.figure_scale import apply_axis_scale, resolve_axis_scale  #
 from quantized.calc.figure_styles import FigureStyle, figure_style  # noqa: E402
 from quantized.calc.figure_ticks import apply_tick_formats, apply_tick_steps  # noqa: E402
 
-from .figure_errorbars import apply_error_bars
+from .figure_errorbars import apply_error_bars  # noqa: E402
 
 __all__ = ["draw_series_axes", "render_figure", "style_rc"]
 
@@ -39,6 +44,10 @@ _LINESTYLE = {"solid": "-", "dashed": "--", "dotted": ":", "none": "none"}
 # per-series `step` ("pre"/"post"/"mid" — SeriesStyle.step / ExportSeriesStyle
 # .step) maps 1:1 onto matplotlib's own `Line2D.drawstyle` vocabulary.
 _DRAWSTYLE = {"pre": "steps-pre", "post": "steps-post", "mid": "steps-mid"}
+# 8 `MarkerShape` glyphs -> matplotlib codes; wire key `marker_shape` (sent by
+# `lib/exportStyles`; was hardcoded "o", so every shape exported as a circle).
+_MARKER = {"circle": "o", "square": "s", "triangle": "^", "downtriangle": "v",
+           "diamond": "D", "plus": "+", "cross": "x", "star": "*"}
 # Fixed fill translucency for MAIN #13 (fill under/between curves) — matches
 # the screen side's `uplotFill.ts` FILL_ALPHA_PCT (25%) so an exported figure
 # reads the same as its on-screen counterpart.
@@ -56,7 +65,7 @@ def _plot_kwargs(
     silently ignored (no ``drawstyle``/``linestyle`` key added) rather than
     raising -- same degrade-gracefully contract as every other style field
     here (see ``calc.plotting.resolve_style_channels``'s doc: "an export must
-    never 500 on a bad style hint")."""
+    never 500 on a bad style hint") -- ``marker_shape`` included."""
     kw: dict[str, Any] = {"linewidth": default_lw}
     if not spec:
         return kw
@@ -73,7 +82,8 @@ def _plot_kwargs(
     if step in _DRAWSTYLE:
         kw["drawstyle"] = _DRAWSTYLE[step]
     if spec.get("marker"):
-        kw["marker"] = "o"
+        shape = spec.get("marker_shape")
+        kw["marker"] = _MARKER.get(shape, "o") if isinstance(shape, str) else "o"
         kw["markersize"] = spec.get("marker_size") or default_marker_size
     return kw
 
@@ -110,33 +120,6 @@ def _apply_fill(
                 ax.fill_between(xv[:n], yv[:n], other[:n], color=color, alpha=_FILL_ALPHA)
 
 
-def _draw_color_scatter(
-    fig: Any,
-    ax: Any,
-    xv: NDArray[np.float64],
-    yv: NDArray[np.float64],
-    label: str,
-    spec: Mapping[str, Any],
-    st: FigureStyle,
-) -> Any:
-    """Colour-mapped scatter (MAIN #14): each point coloured by a THIRD
-    channel's value -- ``spec["color_by"]``, already resolved by
-    ``calc.plotting.resolve_style_channels`` to a concrete per-row array (this
-    module never sees a raw channel index). Replaces the normal line draw
-    entirely for this series -- screen-side parity: ``uplotOpts.ts`` hides the
-    native line/points the same way whenever a series' ``colorBy`` is set.
-    Adds a colourbar so the mapping is legible. Returns the ``PathCollection``
-    artist (for the figure-hitmap element collector)."""
-    z = np.asarray(spec["color_by"], dtype=float)
-    n = min(len(xv), len(yv), len(z))
-    size = float(spec.get("marker_size") or st.marker_size) ** 2
-    sc = ax.scatter(
-        xv[:n], yv[:n], c=z[:n], cmap=str(spec.get("colormap") or "viridis"), s=size, label=label
-    )
-    fig.colorbar(sc, ax=ax)
-    return sc
-
-
 def style_rc(st: FigureStyle, ov: Mapping[str, Any]) -> dict[str, Any]:
     """The rc-param dict a preset (+ optional font/tick overrides) resolves to.
 
@@ -297,6 +280,19 @@ def _render_impl(
     # preset's opaque background. Matters for pasting a figure onto a
     # coloured slide; ignored in practice by formats that have no alpha.
     transparent: bool = False,
+    # P3.3 print-safe export mode: overrides every series' colour to a
+    # position-based grey ramp and forces the dash/marker cycle (see
+    # `calc.figure_greyscale`'s module doc) -- applied uniformly to this
+    # function's own single-axes/y2/x-breaks paths (every one of them draws
+    # through `_plot_kwargs` off the SAME `series_styles` list mutated just
+    # below), so it also covers a `group_col`-resolved request (that path's
+    # `series_styles` is `None`, which `apply_greyscale` treats as "no
+    # explicit style on any series" and still ramps). Facets render through
+    # a completely separate module (`calc.figure_facets`) that never reaches
+    # `series_styles` at all -- this flag is a documented no-op there (see
+    # `routes.export_figures._render_facets_bytes`, which does not forward
+    # it) rather than silently doing nothing while looking wired.
+    greyscale: bool = False,
     overrides: Mapping[str, Any] | None = None,
     collect_map: bool = False,
     x_fmt: Mapping[str, Any] | None = None,
@@ -344,6 +340,10 @@ def _render_impl(
     ``figure_y2.render_with_secondary_axis``'s doc). Not compatible with
     ``x_breaks`` (raises ``ValueError``) -- a broken figure has several
     axes already and gains no coherent secondary-axis meaning.
+    ``greyscale`` (P3.3 print-safe export) rewrites ``series_styles`` via
+    :func:`quantized.calc.figure_greyscale.apply_greyscale` before any of
+    the branches below run -- see that function's doc for exactly what it
+    overrides and what it deliberately leaves alone.
     """
     if fmt not in _FORMATS:
         raise ValueError(f"fmt must be one of {_FORMATS}")
@@ -357,6 +357,8 @@ def _render_impl(
     y_label = safe_mathtext_label(y_label)
     y2_label = safe_mathtext_label(y2_label)
     series = [(safe_mathtext_label(label), y) for label, y in series]
+    if greyscale:
+        series_styles = apply_greyscale(series_styles, len(series))
     st = figure_style(style)
     ov = dict(overrides or {})
     _validate_overrides(ov)

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_break.py

@@ -33,6 +33,7 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402
 import numpy as np  # noqa: E402

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_categorical.py

@@ -16,6 +16,7 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402
 import numpy as np  # noqa: E402

quantized_lab-0.26.0/src/quantized/calc/figure_colorscatter.py

@@ -0,0 +1,53 @@
+"""Colour-mapped scatter (MAIN #14) for the publication renderer.
+
+Split out of ``calc.figure`` purely to stay under the 500-line god-module
+ceiling (mirrors ``figure_break``/``figure_y2``/``figure_overrides`` — a
+self-contained draw branch pulled into its own module rather than trimmed).
+Pure layer: no fastapi/pydantic imports.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from quantized.calc.figure_styles import FigureStyle
+
+__all__ = ["draw_color_scatter"]
+
+
+def draw_color_scatter(
+    fig: Any,
+    ax: Any,
+    xv: NDArray[np.float64],
+    yv: NDArray[np.float64],
+    label: str,
+    spec: Mapping[str, Any],
+    st: FigureStyle,
+) -> Any:
+    """Colour-mapped scatter: each point coloured by a THIRD channel's value
+    -- ``spec["color_by"]``, already resolved by
+    ``calc.plotting.resolve_style_channels`` to a concrete per-row array
+    (this module never sees a raw channel index). Replaces the normal line
+    draw entirely for this series -- screen-side parity: ``uplotOpts.ts``
+    hides the native line/points the same way whenever a series' ``colorBy``
+    is set. Adds a colourbar so the mapping is legible. Returns the
+    ``PathCollection`` artist (for the figure-hitmap element collector).
+
+    Deliberately left OUT of P3.3's greyscale export mode
+    (``calc.figure_greyscale.apply_greyscale`` passes a ``color_by`` spec
+    through unchanged): a colour-mapped scatter's colour IS the plotted
+    quantity, not a categorical series-to-series distinction, so forcing it
+    to grey would delete information rather than make the figure print-safe.
+    """
+    z = np.asarray(spec["color_by"], dtype=float)
+    n = min(len(xv), len(yv), len(z))
+    size = float(spec.get("marker_size") or st.marker_size) ** 2
+    sc = ax.scatter(
+        xv[:n], yv[:n], c=z[:n], cmap=str(spec.get("colormap") or "viridis"), s=size, label=label
+    )
+    fig.colorbar(sc, ax=ax)
+    return sc

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_corner.py

@@ -22,6 +22,7 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402
 import numpy as np  # noqa: E402

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_errorbars.py

@@ -83,7 +83,7 @@ def apply_error_bars(
             color = artist.get_color() if artist is not None else None
         except AttributeError:
             color = None  # a colour-mapped scatter has no single colour
-        ax.errorbar(
+        container = ax.errorbar(
             xv,
             yv,
             yerr=yerr,
@@ -94,3 +94,26 @@ def apply_error_bars(
             capsize=2,
             zorder=1,  # behind the series line, so data stays legible
         )
+        # matplotlib returns an ErrorbarContainer -- a tuple subclass of
+        # (data_line, caplines, barlinecols). A minimal axes stand-in (the
+        # unit tests' recording fake) may return None; treat anything that is
+        # not a 3-tuple as "no caps to restyle" rather than unpacking blindly.
+        caplines = container[1] if isinstance(container, tuple) and len(container) > 1 else ()
+        if color is not None:
+            # `ecolor=` above colours the bar lines and each cap's EDGE, but
+            # matplotlib's cap markers ('|'/'_') keep their default FACE
+            # colour (rcParams' C0) regardless -- passing markerfacecolor=
+            # to errorbar() itself is silently dropped for these marker
+            # styles, so the face has to be set on the returned cap Line2Ds
+            # directly. Otherwise a "print-safe" greyscale export still
+            # emits a chromatic `fill: #1f77b4` for every cap in vector
+            # output (PDF/SVG) -- invisible in a raster PNG only because the
+            # cap's degenerate fill path paints zero visible pixels there.
+            # This also corrects the ordinary COLOURED case: before this fix,
+            # every series' caps were filled with rcParams' C0 regardless of
+            # that series' own colour (e.g. series 2's caps rendered blue,
+            # not orange) in any coloured vector export -- a second, latent
+            # fix beyond the greyscale defect this was written for.
+            for cap in caplines:
+                cap.set_markerfacecolor(color)
+                cap.set_markeredgecolor(color)

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_facets.py

@@ -36,6 +36,7 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402
 import numpy as np  # noqa: E402

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_facets_map.py

@@ -31,6 +31,7 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless (defensive -- figure_facets already sets this)
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402
 import numpy as np  # noqa: E402

{quantized_lab-0.25.0 → quantized_lab-0.26.0}/src/quantized/calc/figure_field.py

@@ -15,6 +15,7 @@ from typing import Any
 import matplotlib
 
 matplotlib.use("Agg")  # headless
+matplotlib.rcParams["svg.fonttype"] = "none"  # editable SVG <text>, not glyph outlines
 
 import matplotlib.pyplot as plt  # noqa: E402
 import numpy as np  # noqa: E402

quantized_lab-0.26.0/src/quantized/calc/figure_greyscale.py

@@ -0,0 +1,159 @@
+"""Print-safe greyscale export mode (PRIMARY_SOFTWARE_AUDIT_PLAN P3.3).
+
+Pure layer: a series count in -> grey ``#rrggbb`` hex strings out, plus a
+style-list transform built on top of it. No matplotlib/fastapi/pydantic
+import — a plain colour-space computation, unit-testable without a
+renderer, and importable from ``calc.figure``/``calc.figure_y2``/
+``calc.figure_break`` (every place a per-series style spec reaches
+``calc.figure._plot_kwargs``) without pulling anything heavy in.
+
+Why not just convert each series' OWN colour to a grey via an ordinary
+relative-luminance conversion (the "obvious" approach every image editor's
+"desaturate" filter uses)? Because two series that differ only in HUE, not
+lightness — exactly the case a categorical colour palette is built to keep
+visually distinct — can have nearly identical relative luminance (a
+saturated red and a saturated green both sit near the middle of the
+luminance range). A per-colour conversion then collapses them to
+indistinguishable greys, defeating the entire point of a "print-safe" mode:
+a reader photocopying the figure would see one curve where the screen showed
+two. So every series instead gets an EVENLY SPACED grey by its DISPLAY
+POSITION alone — independent of whatever colour it would otherwise draw —
+spanning CIE L* (perceptual lightness, not raw sRGB value, so the steps
+LOOK evenly spaced rather than merely being evenly spaced numbers) from
+`L_MIN` to `L_MAX`. That guarantees a minimum perceptual step between any
+two adjacent series regardless of how close their original hues were.
+
+Grey alone still runs out of room past a handful of series (L* has far less
+usable range than hue does), so :func:`apply_greyscale` also forces the
+dash cycle (and, for a series that already draws a marker, the marker-shape
+cycle) by the SAME display position — the export-side half of the P3.3 auto
+dash/marker cycle the frontend already ships
+(``frontend/src/lib/seriesStyleCycle.ts``). `LINE_CYCLE`/`MARKER_SHAPES`
+below are that module's `AUTO_DASH_CYCLE`/`AUTO_MARKER_CYCLE`, copied
+verbatim — KEEP IN SYNC WITH `frontend/src/lib/seriesStyleCycle.ts`; a test
+(`tests/test_calc_figure_greyscale.py`) pins the two lists equal by reading
+that file's source, so drift between them fails the suite rather than
+silently disagreeing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+__all__ = ["L_MIN", "L_MAX", "LINE_CYCLE", "MARKER_SHAPES", "greyscale_ramp", "apply_greyscale"]
+
+# CIE L* target range for the grey ramp. Kept well inside [0, 100]: L*=0 is
+# true black (indistinguishable from a heavy grid line or the axis box) and
+# L*=100 is true white (invisible against the figure's own white background),
+# so both ends are pulled in to stay legible against the preset's own
+# spines/grid/background, which greyscale mode leaves untouched.
+L_MIN = 15.0
+L_MAX = 70.0
+
+# The CIE L*/Y* piecewise-linear threshold (6/29), used by both directions
+# of the standard CIE L* <-> relative-luminance conversion below.
+_DELTA = 6.0 / 29.0
+
+# Dash cycle for LINES, by series display position — verbatim copy of
+# frontend/src/lib/seriesStyleCycle.ts's `AUTO_DASH_CYCLE` (three entries:
+# every `LineStyle` value, which is also every value
+# `calc.figure._LINESTYLE` accepts). "solid" first so a single-series figure
+# (or a series with an explicit line already) is unaffected.
+LINE_CYCLE: tuple[str, ...] = ("solid", "dashed", "dotted")
+
+# Marker-glyph cycle for series that already draw a marker, by display
+# position — verbatim copy of `AUTO_MARKER_CYCLE` (all eight `MarkerShape`
+# members, closed glyphs first, matching `calc.figure._MARKER`'s own table).
+MARKER_SHAPES: tuple[str, ...] = (
+    "circle", "square", "triangle", "diamond",
+    "downtriangle", "plus", "cross", "star",
+)
+
+
+def _y_from_lstar(lstar: float) -> float:
+    """Inverse CIE L* -> relative luminance Y (D65 white point, Y=1)."""
+    fy = (lstar + 16.0) / 116.0
+    if fy > _DELTA:
+        return fy**3
+    return 3.0 * _DELTA**2 * (fy - 4.0 / 29.0)
+
+
+def _srgb_channel_from_linear(y: float) -> int:
+    """Inverse sRGB gamma: a linear relative luminance -> an 8-bit channel
+    (0-255). Used with r=g=b=this value, since an achromatic pixel's three
+    channels are identical and therefore each equal to the whole triple's
+    relative luminance."""
+    y = min(1.0, max(0.0, y))
+    s = y * 12.92 if y <= 0.0031308 else 1.055 * (y ** (1.0 / 2.4)) - 0.055
+    return round(min(1.0, max(0.0, s)) * 255)
+
+
+def _hex_from_lstar(lstar: float) -> str:
+    v = _srgb_channel_from_linear(_y_from_lstar(lstar))
+    return f"#{v:02x}{v:02x}{v:02x}"
+
+
+def greyscale_ramp(n: int, *, l_min: float = L_MIN, l_max: float = L_MAX) -> list[str]:
+    """``n`` evenly spaced greys (``#rrggbb``), one per series DISPLAY
+    POSITION (index ``0..n-1``), spanning CIE L* ``l_min..l_max`` ascending —
+    position 0 is the darkest, position ``n-1`` the lightest. Guarantees a
+    minimum step of ``(l_max - l_min) / (n - 1)`` in L* between any two
+    positions (every pair, not just adjacent ones, since the ramp is
+    monotonic) — independent of any actual series colour; see the module
+    header for why. ``n <= 0`` returns ``[]``; ``n == 1`` returns the ramp's
+    midpoint (there is no "adjacent series" to separate from)."""
+    if n <= 0:
+        return []
+    if n == 1:
+        return [_hex_from_lstar((l_min + l_max) / 2.0)]
+    step = (l_max - l_min) / (n - 1)
+    return [_hex_from_lstar(l_min + step * i) for i in range(n)]
+
+
+def apply_greyscale(
+    styles: Sequence[Mapping[str, Any] | None] | None,
+    n: int,
+) -> list[dict[str, Any]]:
+    """Return a NEW list of ``n`` style specs (never mutates ``styles``) with
+    every series' colour overridden to :func:`greyscale_ramp`'s grey at its
+    display position, and the dash/marker cycle FORCED by that same
+    position — a grey ramp alone runs out of separable steps well before
+    ``n`` gets large, so greyscale mode does not rely on it alone. Explicit
+    per-series choices still win, matching the frontend cycle's own
+    contract (`seriesStyleCycle.resolveSeriesStyle`'s doc): a series with an
+    explicit ``line`` keeps it, and a series with an explicit
+    ``marker_shape`` keeps that too. The marker SHAPE is cycled only for a
+    series that already draws a marker (``spec["marker"]`` true) — greyscale
+    does not turn markers on for a series that did not request one, the same
+    restraint the frontend cycle applies (a plot with no markers at all
+    should not suddenly grow eight circles/squares/triangles).
+
+    A ``color_by`` (MAIN #14 colour-mapped scatter) series is passed through
+    UNCHANGED, colourmap included: greyscale here targets the CATEGORICAL
+    series-to-series distinction a palette exists for, not a scatter whose
+    colour is itself the plotted quantity — forcing that to grey would
+    delete the information the plot exists to show, not print-safe it. A
+    ``fill``/``vs`` reference is preserved verbatim; the fill it produces
+    inherits the (now grey) line colour automatically, same as before this
+    function existed.
+
+    ``styles`` entries beyond ``n`` are ignored; a missing/short list is
+    treated as an all-``None`` list of length ``n`` (matching every other
+    caller's ``series_styles[i] if series_styles and i < len(series_styles)
+    else None`` convention)."""
+    ramp = greyscale_ramp(n)
+    out: list[dict[str, Any]] = []
+    for i in range(n):
+        raw = styles[i] if styles and i < len(styles) else None
+        spec: dict[str, Any] = dict(raw) if raw else {}
+        if spec.get("color_by") is not None:
+            out.append(spec)  # untouched -- see the doc above
+            continue
+        spec["color"] = ramp[i]
+        if not spec.get("line"):
+            spec["line"] = LINE_CYCLE[i % len(LINE_CYCLE)]
+        if spec.get("marker") and not spec.get("marker_shape"):
+            spec["marker_shape"] = MARKER_SHAPES[i % len(MARKER_SHAPES)]
+        out.append(spec)
+    return out