microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/perturb/qc_rules.py

@@ -0,0 +1,373 @@
+# May-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Declarative internal QC rules.
+
+Evaluates simple range checks against the merged ``pf.channels`` and
+emits synthetic uint8 channels that drop into the same per-segment
+``compute_segment_drop`` machinery as hotel-injected QC channels.
+
+YAML schema (under the perturb config's ``qc:`` block):
+
+    qc:
+      rules:
+        speed_oor:                 # rule name = synthetic channel name
+          channel: speed_fast
+          min: 0.05                # any of {min, max, abs_max} can be set
+          max: 1.5
+          bit: 8                   # bit set in the uint8 output
+        pitch_oor:
+          channel: pitch           # pseudo-name → auto-pick from Incl_X/Y
+          abs_max: 45              # |angle| > 45 deg → flag
+          bit: 16
+        roll_oor:
+          channel: roll            # pseudo-name → "the other" inclinometer
+          abs_max: 10
+          bit: 32
+
+Behavior
+--------
+- A rule's ``channel`` is read from ``pf.channels``. Pseudo-names
+  ``"pitch"`` and ``"roll"`` auto-pick from ``Incl_X`` / ``Incl_Y`` by
+  amplitude — same heuristic as the flight-model speed; pitch is the
+  axis with the larger swing, roll is the other.
+- Missing channels are warned-and-skipped rather than fatal: one config
+  can target multiple instrument types where some channels don't exist.
+- Fast-rate channels are max-pooled to slow rate so the qc_gate can
+  uniformly consume bool-on-pf.t_slow arrays.
+- Each rule writes a ``uint8`` channel with the named bit set wherever
+  the condition is met, plus CF ``flag_meanings`` / ``flag_masks`` so
+  ``compute_segment_drop`` can lift them into the per-segment bitfield.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# Maximum bit value we accept (uint8 fits 8 distinct flags).
+_MAX_BIT = 1 << 7
+
+# Range rule keys (the original / default rule type).
+_RANGE_OPTION_KEYS = frozenset({
+    "type", "channel", "min", "max", "abs_max", "bit", "amplitude_quantile",
+})
+
+# pitch_w_consistency rule keys.
+_FLIGHT_CONSISTENCY_OPTION_KEYS = frozenset({
+    "type", "bit", "amplitude_quantile",
+    "pitch_min_deg", "W_min_dbar_per_s", "pitch_positive",
+})
+
+# Default low / high percentiles for inclinometer-axis amplitude detection.
+# 1..99 strips the outlier tails (e.g. surface tumbles or brief sensor
+# saturation spikes that can dominate ``nanmax - nanmin``) while still
+# capturing the bulk of the in-flight swing.
+_DEFAULT_AMPLITUDE_Q: tuple[float, float] = (1.0, 99.0)
+
+
+def _resolve_inclinometer_axis(
+    pf: Any,
+    want: str,
+    amplitude_q: tuple[float, float] = _DEFAULT_AMPLITUDE_Q,
+) -> str | None:
+    """Return ``Incl_X`` or ``Incl_Y`` (whichever is pitch / roll on this
+    instrument) by percentile-spread amplitude. ``None`` when neither
+    inclinometer is present.
+
+    The spread is the high minus the low percentile of each axis
+    (default 99-1). Percentiles keep brief outliers — e.g. a surface
+    tumble or sensor saturation that briefly drives one axis to
+    -90 deg — from masquerading as the high-amplitude flight axis.
+    Pitch is then the axis with the larger spread (the glider rotates
+    around its body axis during dive / climb cycles); the other axis
+    is roll.
+
+    Same heuristic is shared with :mod:`odas_tpw.perturb.speed`'s
+    flight model so a single deployment's QC and speed estimate agree
+    on which axis is which.
+    """
+    iX = pf.channels.get("Incl_X")
+    iY = pf.channels.get("Incl_Y")
+    if iX is None or iY is None:
+        return None
+    lo_q, hi_q = float(amplitude_q[0]), float(amplitude_q[1])
+    rx = float(np.nanpercentile(iX, hi_q) - np.nanpercentile(iX, lo_q))
+    ry = float(np.nanpercentile(iY, hi_q) - np.nanpercentile(iY, lo_q))
+    pitch_name, roll_name = ("Incl_X", "Incl_Y") if rx >= ry else ("Incl_Y", "Incl_X")
+    return pitch_name if want == "pitch" else roll_name
+
+
+def _coarsen_to_slow(flag: np.ndarray, ratio: int) -> np.ndarray:
+    """Max-pool a fast-rate boolean to slow rate. ``ratio = fs_fast/fs_slow``."""
+    n_slow = flag.size // ratio
+    if n_slow == 0:
+        return np.zeros(0, dtype=bool)
+    return np.asarray(flag[: n_slow * ratio].reshape(n_slow, ratio).any(axis=1))
+
+
+def _validate_bit(name: str, bit_val: int) -> None:
+    if bit_val < 1 or bit_val > _MAX_BIT or bit_val & (bit_val - 1):
+        raise ValueError(
+            f"qc.rules.{name}: 'bit' must be a power of 2 in 1..{_MAX_BIT}, "
+            f"got {bit_val}"
+        )
+
+
+def _validate_amplitude_q(name: str, aq) -> tuple[float, float]:
+    if (not hasattr(aq, "__len__") or len(aq) != 2
+            or not (0.0 <= float(aq[0]) < float(aq[1]) <= 100.0)):
+        raise ValueError(
+            f"qc.rules.{name}.amplitude_quantile: must be a pair "
+            f"[lo, hi] with 0 <= lo < hi <= 100, got {aq!r}"
+        )
+    return (float(aq[0]), float(aq[1]))
+
+
+def _evaluate_range(pf: Any, name: str, cfg: dict, n_slow: int,
+                    ratio: int) -> np.ndarray | None:
+    """Per-channel min/max/abs_max range check. Original / default rule type."""
+    ch_name = cfg.get("channel")
+    if not ch_name:
+        raise ValueError(f"qc.rules.{name}: 'channel' is required")
+
+    if ch_name in ("pitch", "roll"):
+        aq = cfg.get("amplitude_quantile") or _DEFAULT_AMPLITUDE_Q
+        aq = _validate_amplitude_q(name, aq)
+        resolved = _resolve_inclinometer_axis(pf, ch_name, aq)
+        if resolved is None:
+            logger.warning(
+                "qc.rules.%s: %r requires Incl_X and Incl_Y; skipping",
+                name, ch_name,
+            )
+            return None
+        actual = resolved
+    else:
+        actual = ch_name
+
+    if actual not in pf.channels:
+        logger.warning(
+            "qc.rules.%s: channel %r not on pf.channels; skipping",
+            name, actual,
+        )
+        return None
+
+    arr = np.asarray(pf.channels[actual], dtype=np.float64)
+    flag = np.zeros(arr.shape, dtype=bool)
+    if "min" in cfg:
+        flag |= arr < float(cfg["min"])
+    if "max" in cfg:
+        flag |= arr > float(cfg["max"])
+    if "abs_max" in cfg:
+        flag |= np.abs(arr) > float(cfg["abs_max"])
+    # NaN samples are flagged too — they're as bad as out-of-range for QC.
+    flag |= ~np.isfinite(arr)
+
+    # Coarsen fast-rate channels to slow so qc_gate consumes uniformly.
+    if actual in pf._fast_channels and arr.size != n_slow:
+        flag = _coarsen_to_slow(flag, ratio)
+    return np.asarray(flag, dtype=bool)
+
+
+def _evaluate_pitch_w_consistency(pf: Any, name: str, cfg: dict,
+                                  n_slow: int) -> np.ndarray | None:
+    """Flag samples where pitch direction and dP/dt sign disagree.
+
+    Healthy glide has nose-up + ascending or nose-down + descending; a
+    stalled glider can be pitched up while still sinking (or vice
+    versa) and shouldn't contribute turbulence estimates.
+
+    The check operates on:
+
+    - ``pitch``: auto-resolved Incl_Y / Incl_X.  The inclinometer sign
+      convention DOES matter here: the test assumes positive pitch =
+      nose-down unless ``pitch_positive`` says otherwise.
+    - ``W``: signed dP/dt at slow rate (positive = depth increasing =
+      sinking), computed from ``pf.channels["P"]`` with the same
+      smoothing as :func:`smooth_fall_rate` in the speed module.
+
+    Within ±``pitch_min_deg`` of level or ±``W_min_dbar_per_s`` of
+    stationary, samples are *not* flagged — too close to a sign-zero
+    crossing to call confidently.
+
+    ``pitch_positive`` resolves the mounting polarity:
+
+    - ``"auto"`` (default): infer from the deployment-wide majority sign
+      of pitch*W — steady flight dominates a healthy record, so the
+      majority sign identifies the consistent pairing.  The choice is
+      logged.
+    - ``"nose_down"``: positive pitch = nose-down (sign agreement with W
+      is healthy).
+    - ``"nose_up"``: positive pitch = nose-up (sign disagreement with W
+      is healthy) — e.g. an inclinometer mounted with opposite polarity.
+
+    YAML schema::
+
+        flight_consistency:
+          type: pitch_w_consistency
+          pitch_min_deg: 5.0
+          W_min_dbar_per_s: 0.02
+          pitch_positive: auto
+          bit: 64
+    """
+    from odas_tpw.scor160.profile import smooth_fall_rate
+
+    aq = cfg.get("amplitude_quantile") or _DEFAULT_AMPLITUDE_Q
+    aq = _validate_amplitude_q(name, aq)
+    pitch_name = _resolve_inclinometer_axis(pf, "pitch", aq)
+    if pitch_name is None:
+        logger.warning(
+            "qc.rules.%s: pitch_w_consistency requires Incl_X and Incl_Y; skipping",
+            name,
+        )
+        return None
+    if "P" not in pf.channels:
+        logger.warning(
+            "qc.rules.%s: pitch_w_consistency requires P; skipping",
+            name,
+        )
+        return None
+
+    pitch = np.asarray(pf.channels[pitch_name], dtype=np.float64)
+    P = np.asarray(pf.channels["P"], dtype=np.float64)
+    fs_slow = float(pf.fs_slow)
+    # smooth_fall_rate runs P through filtfilt, which has no NaN handling: a
+    # single non-finite pressure sample would smear NaN across the ENTIRE
+    # record's fall rate and flag the whole record (asymmetric with the
+    # per-sample range rule). Interpolate isolated gaps before filtering so W
+    # stays usable, and flag only the genuinely-bad samples locally below.
+    finite_P = np.isfinite(P)
+    if finite_P.any() and not finite_P.all():
+        idx = np.arange(P.size)
+        P_for_filter = P.copy()
+        P_for_filter[~finite_P] = np.interp(idx[~finite_P], idx[finite_P], P[finite_P])
+    else:
+        P_for_filter = P  # all-finite (no-op) or all-NaN (W stays NaN -> flagged)
+    W = smooth_fall_rate(P_for_filter, fs_slow)  # signed, dbar/s
+
+    pitch_min = float(cfg.get("pitch_min_deg", 5.0))
+    w_min = float(cfg.get("W_min_dbar_per_s", 0.02))
+
+    moving = (
+        (np.abs(pitch) >= pitch_min)
+        & (np.abs(W) >= w_min)
+        & np.isfinite(pitch)
+        & np.isfinite(W)
+    )
+
+    # Resolve the inclinometer mounting polarity: +1 means positive
+    # pitch = nose-down (pitch and W share sign in healthy flight).
+    polarity = str(cfg.get("pitch_positive", "auto")).lower()
+    if polarity == "nose_up":
+        sign = -1.0
+    elif polarity == "nose_down":
+        sign = 1.0
+    else:  # auto: majority sign of pitch*W — steady flight dominates
+        if np.any(moving):
+            med = float(np.median(np.sign(pitch[moving] * W[moving])))
+            sign = 1.0 if med >= 0 else -1.0
+        else:
+            sign = 1.0
+        logger.info(
+            "qc.rules.%s: auto-detected inclinometer polarity: positive pitch = %s",
+            name,
+            "nose-down" if sign > 0 else "nose-up",
+        )
+
+    # Signs disagree (after polarity correction) and both are clearly
+    # nonzero (outside the noise zone around level / stationary).
+    flag = (sign * pitch * W < 0) & moving
+    # Local non-finite flagging: a bad pitch or a bad raw pressure flags only
+    # its own sample (~finite_P, not the filtfilt-smeared ~isfinite(W)). The
+    # ~isfinite(W) term still catches the all-NaN-P case (W never recovers).
+    flag |= ~np.isfinite(pitch) | ~finite_P | ~np.isfinite(W)
+    return np.asarray(flag, dtype=bool)
+
+
+# Dispatch table. New rule types register here.
+_RULE_TYPES: dict[str, tuple[frozenset, Any]] = {
+    "range": (_RANGE_OPTION_KEYS, _evaluate_range),
+    "pitch_w_consistency": (
+        _FLIGHT_CONSISTENCY_OPTION_KEYS, _evaluate_pitch_w_consistency,
+    ),
+}
+
+
+def evaluate_rules(pf: Any, rules: dict[str, dict] | None) -> dict[str, np.ndarray]:
+    """Evaluate the rules block against ``pf.channels``.
+
+    Returns a dict ``{rule_name: uint8_array}`` keyed by the YAML rule
+    name. Each array sits on ``pf.t_slow`` with the rule's ``bit`` set
+    wherever its condition is met.
+
+    Rule type is selected via ``type:`` (default ``range`` for backwards
+    compat). See :data:`_RULE_TYPES` for registered evaluators.
+
+    Rules referencing a missing channel are warned-and-skipped (the
+    output dict simply omits them — downstream ``drop_from`` lookups
+    treat absent channels the same as channels containing only zeros).
+    """
+    if not rules:
+        return {}
+
+    out: dict[str, np.ndarray] = {}
+    ratio = max(1, round(float(pf.fs_fast) / float(pf.fs_slow)))
+    n_slow = len(pf.t_slow)
+
+    for name, raw in rules.items():
+        cfg = dict(raw or {})
+        rtype = str(cfg.get("type", "range"))
+        if rtype not in _RULE_TYPES:
+            raise ValueError(
+                f"qc.rules.{name}: unknown type {rtype!r}. "
+                f"Valid: {sorted(_RULE_TYPES)}"
+            )
+        valid_keys, evaluator = _RULE_TYPES[rtype]
+        unknown = set(cfg) - valid_keys
+        if unknown:
+            raise ValueError(
+                f"qc.rules.{name} (type={rtype}): unknown options {sorted(unknown)}. "
+                f"Valid: {sorted(valid_keys)}"
+            )
+        bit_val = int(cfg.get("bit", 1))
+        _validate_bit(name, bit_val)
+
+        if rtype == "range":
+            flag = evaluator(pf, name, cfg, n_slow, ratio)
+        else:
+            flag = evaluator(pf, name, cfg, n_slow)
+        if flag is None:
+            continue
+
+        if flag.size != n_slow:
+            # Pad / truncate to slow length — keeps qc_gate slicing valid.
+            if flag.size < n_slow:
+                pad = np.zeros(n_slow - flag.size, dtype=bool)
+                flag = np.concatenate((flag, pad))
+            else:
+                flag = flag[:n_slow]
+        out[name] = flag.astype(np.uint8) * np.uint8(bit_val)
+
+    return out
+
+
+def register_rule_channels(pf: Any, rule_arrays: dict[str, np.ndarray],
+                           rules: dict[str, dict]) -> None:
+    """Register evaluated rule arrays on ``pf`` so the qc_gate sees them.
+
+    Adds each rule's array to ``pf.channels`` and writes a
+    ``channel_info`` entry with CF ``flag_meanings`` / ``flag_masks``
+    that ``compute_segment_drop`` lifts into the per-segment bitfield.
+    """
+    for name, arr in rule_arrays.items():
+        bit_val = int(rules[name].get("bit", 1))
+        pf.channels[name] = arr
+        pf.channel_info[name] = {
+            "units": "",
+            "type": "qc_rule",
+            "name": name,
+            "flag_meanings": name,
+            "flag_masks": [bit_val],
+        }

odas_tpw/perturb/resolve.py

@@ -0,0 +1,306 @@
+# Jun-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Resolve perturb output directories from a config (read-only).
+
+Given a perturb config (the same YAML the pipeline ran), locate the
+``{stage}_NN`` output directory whose stored ``.params_sha256_*`` signature
+matches that config — so plotting can point at a config instead of guessing
+the newest versioned directory (which silently mixes products from different
+configs when several share an ``output_root``).
+
+Matching compares the canonical signature JSON section-by-section but **ignores
+``files.output_root``**: ``--output`` rewrites it at run time without
+normalization, so a run's stored signature can hold an output path the config
+YAML never contained, and recomputing the hash would never match — yet the
+output location has no bearing on the data. Everything else in ``files`` is
+kept, including ``p_file_root``/``p_file_pattern`` (they identify the input
+*dataset*, so two runs of different inputs into one ``output_root`` stay
+distinguishable) and ``trim``/``merge`` (they change the data). A run done with
+``--p-file-root`` therefore won't match by signature and falls back to the
+single-dir / drift path below.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import warnings
+from pathlib import Path
+
+from ruamel.yaml.error import YAMLError
+
+from odas_tpw.config_base import iter_stage_dirs
+from odas_tpw.perturb import config as _cfg
+
+# Everything load_config can raise for a bad --config: missing/unreadable
+# (OSError, incl. FileNotFoundError), unknown section/key (ValueError), or a
+# YAML syntax error (ruamel YAMLError — NOT an OSError/ValueError subclass).
+# A bad config is ALWAYS fatal; these are converted to a clean SystemExit
+# wherever a config is loaded, so the user never sees a raw traceback.
+_CONFIG_LOAD_ERRORS = (OSError, ValueError, YAMLError)
+
+# files key rewritten by --output at run time and irrelevant to the data;
+# excluded from the signature comparison. p_file_root/p_file_pattern are kept
+# (they identify the input dataset).
+_VOLATILE_FILES_KEYS = ("output_root",)
+
+
+class StageConflict(RuntimeError):
+    """The stage directory is ambiguous w.r.t. the config (multiple matches, or
+    no match with several candidates / under ``strict``).
+
+    Distinct from ``FileNotFoundError`` (the stage simply does not exist): a
+    conflict must surface even for an *optional* stage rather than silently
+    degrading, since it means the user's data is present but doesn't agree with
+    the config.
+    """
+
+
+def _strip_volatile(canon: dict) -> dict:
+    """Drop signature components that must not affect *plot-time* matching.
+
+    Plotting resolves a dir by **config**, independent of the run environment
+    (``files.output_root``) and of the processing-code version (``_engine``):
+    you plot data regardless of which code wrote it. The pipeline keeps both in
+    the hash so its output dirs stay code-aware; the resolver strips them so a
+    code update doesn't stop it matching dirs an older engine produced.
+    """
+    canon.pop("_engine", None)
+    files = canon.get("files")
+    if isinstance(files, dict):
+        for key in _VOLATILE_FILES_KEYS:
+            files.pop(key, None)
+    return canon
+
+
+def _want_signature(config: dict, stage: str) -> dict:
+    """The canonical signature *this* config would produce for *stage*."""
+    section, params, upstream = _cfg.stage_signature(stage, config)
+    return _strip_volatile(json.loads(_cfg.canonicalize(section, params, upstream)))
+
+
+def _read_signature(directory: Path) -> dict | None:
+    """The stored canonical signature of *directory*, or None if unreadable."""
+    sigs = sorted(directory.glob(".params_sha256_*"))
+    if not sigs:
+        return None
+    try:
+        return _strip_volatile(json.loads(sigs[0].read_text()))
+    except (OSError, ValueError):
+        return None
+
+
+def _describe(directory: Path) -> str:
+    """One-line note on a candidate dir's config, for error messages."""
+    sig = _read_signature(directory)
+    if sig is None:
+        return f"{directory.name} (no signature)"
+    bits = [
+        f"{sec}={json.dumps(sig[sec], sort_keys=True)}"
+        for sec in ("binning", "chi", "epsilon", "top_trim")
+        if sec in sig
+    ]
+    return f"{directory.name}" + (": " + "; ".join(bits) if bits else "")
+
+
+def stage_dir(
+    config: dict,
+    stage: str,
+    output_root: str | Path | None = None,
+    *,
+    strict: bool = False,
+    latest: bool = False,
+) -> Path:
+    """Return the ``{stage}_NN`` directory under *output_root* matching *config*.
+
+    *output_root* defaults to ``config["files"]["output_root"]``. Resolution:
+
+    - exact signature match → that directory;
+    - ``latest=True`` → the newest ``{stage}_NN`` regardless of config;
+    - no match, exactly one ``{stage}_NN`` exists → that one, with a warning
+      (the common "tweak config, re-plot" case — it cannot be a *different*
+      config's data, there is only one);
+    - no match, two or more exist → ``StageConflict`` listing each directory's
+      config (refuse to guess which is the caller's);
+    - multiple *exact* matches (a concurrent same-config run that raced for a
+      sequence number, or a hand-copied signature) → the newest, with a warning
+      (identical signature ⇒ identical config and inputs ⇒ equivalent data);
+    - ``strict=True`` → ``StageConflict`` on any non-exact match.
+
+    Raises ``ValueError`` for an unknown *stage*, ``FileNotFoundError`` when no
+    ``{stage}_NN`` directory exists at all (stage disabled or never run), and
+    ``StageConflict`` when the directory is ambiguous w.r.t. the config. Never
+    creates a directory.
+    """
+    if stage not in _cfg.STAGES:
+        raise ValueError(f"unknown stage {stage!r}; known: {sorted(_cfg.STAGES)}")
+    raw_root = output_root or (config.get("files") or {}).get("output_root") or "."
+    root = Path(
+        _cfg.expand_config_dir(raw_root, _cfg.config_dir_of(config))
+    ).expanduser()
+    candidates = iter_stage_dirs(root, stage)
+    if not candidates:
+        raise FileNotFoundError(
+            f"no {stage}_NN directory under {root} — the {stage} stage was never "
+            f"run here (or is disabled in the config)."
+        )
+    if latest:
+        return candidates[-1][1]
+
+    want = _want_signature(config, stage)
+    matches = [d for _, d in candidates if _read_signature(d) == want]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        # Multiple dirs carry the *same* canonical signature. The expected
+        # cause is two identical-config `perturb run`s racing to claim a
+        # sequence number under one output_root (one creates {stage}_00, the
+        # other loses the mkdir, advances, and writes the same signature into
+        # {stage}_01); output_root is stripped before comparison and nothing
+        # else differs, so those two were produced from the same config and
+        # inputs and their data is equivalent — picking the newest is safe and
+        # avoids needlessly locking the user out. A signature file is copied
+        # *text*, not a checksum of the dir's data, so a hand-copied signature
+        # into a dir with different data would also land here and is NOT
+        # guaranteed equivalent — hence we warn (listing the dirs) rather than
+        # resolve silently.
+        listing = ", ".join(d.name for d in matches)
+        warnings.warn(
+            f"{stage}: {len(matches)} directories under {root} share the given "
+            f"config's signature ({listing}) — same config and inputs, so using "
+            f"the newest ({matches[-1].name}).",
+            stacklevel=2,
+        )
+        return matches[-1]
+
+    if not strict and len(candidates) == 1:
+        only = candidates[0][1]
+        warnings.warn(
+            f"{stage}: config does not match {only.name}'s signature (config "
+            f"drift) but it is the only {stage} directory under {root} — using "
+            f"it. Pass strict=True / --strict to require an exact match.",
+            stacklevel=2,
+        )
+        return only
+
+    listing = "\n  ".join(_describe(d) for _, d in candidates)
+    reason = "config drift" if strict else "and none matches the given config"
+    raise StageConflict(
+        f"{len(candidates)} {stage}_NN directories under {root} {reason} — "
+        f"refusing to guess which is yours. Candidates:\n  {listing}\n"
+        f"Edit the config to match, re-run the pipeline, or force the newest "
+        f"with --latest."
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI glue for the existing plot subcommands
+# ---------------------------------------------------------------------------
+
+def add_resolve_args(p: argparse.ArgumentParser) -> None:
+    """Register ``--config``/``--latest``/``--strict`` on a plot subparser.
+
+    ``--root`` is registered separately (and is now optional); at least one of
+    ``--config``/``--root`` must be given (``--root`` may accompany ``--config``
+    to override the search location).
+    """
+    p.add_argument(
+        "--config", metavar="PERTURB.YAML",
+        help="perturb config; output directories are resolved from its hash "
+        "signatures instead of guessing the newest {stage}_NN.",
+    )
+    p.add_argument(
+        "--latest", action="store_true",
+        help="with --config, use the newest {stage}_NN even if no signature matches.",
+    )
+    p.add_argument(
+        "--strict", action="store_true",
+        help="with --config, error (don't fall back) when no signature matches.",
+    )
+
+
+def require_root(args: argparse.Namespace) -> str:
+    """The output root for a plot run: ``--root`` if given, else the
+    ``--config``'s ``files.output_root``.
+
+    Call once at the top of a subcommand's ``run`` to backfill ``args.root``
+    (used for titles, default output paths, and per-profile attr lookups) when
+    only ``--config`` was given. Raises ``SystemExit`` if neither is provided.
+    """
+    root = getattr(args, "root", None)
+    if root:
+        return str(root)
+    cfg_path = getattr(args, "config", None)
+    if cfg_path:
+        # require_root runs FIRST in every subcommand's run(), so a bad config
+        # must be cleanly fatal here too (not just in resolve_for_args) — else
+        # the user gets a raw traceback before resolve_for_args is ever reached.
+        try:
+            cfg = _cfg.load_config(cfg_path)
+        except _CONFIG_LOAD_ERRORS as exc:
+            raise SystemExit(str(exc)) from exc
+        out = (cfg.get("files") or {}).get("output_root")
+        if out:
+            return str(_cfg.expand_config_dir(out, _cfg.config_dir_of(cfg)))
+    raise SystemExit("one of --config or --root is required")
+
+
+def resolve_for_args(
+    args: argparse.Namespace,
+    stage: str,
+    *,
+    optional: bool = False,
+    conflict_ok: bool = False,
+) -> str | None:
+    """Resolve a stage directory from parsed plot args.
+
+    With ``--config``, resolve by signature; otherwise fall back to the legacy
+    newest-``{stage}_NN`` discovery. Returns ``None`` when an *optional* stage
+    is absent (so callers can degrade gracefully, e.g. eps-chi without a
+    per-profile ``chi`` dir, profiles' diagnostics overlay) — matching the
+    legacy ``latest_stage_dir`` behavior. A required stage that cannot be
+    resolved raises a clean ``SystemExit``.
+
+    *optional* makes a *missing* stage (no ``{stage}_NN``) degrade to None; by
+    default a config *conflict* (ambiguous/drift) still raises, even for an
+    optional stage, so the user's data is never silently dropped. *conflict_ok*
+    additionally degrades a conflict to None — for **cosmetic** lookups (e.g.
+    eps-chi's per-profile ``diss`` dir, used only for the title's processing
+    params) that must never fail the whole figure over which dir to caption it.
+    """
+    cfg_path = getattr(args, "config", None)
+    root = getattr(args, "root", None)
+    if cfg_path:
+        # Loading the config is separate from finding the stage dir: a
+        # missing/unreadable/malformed --config (e.g. a typo, or invalid YAML)
+        # is ALWAYS fatal and must never be mistaken for "this optional stage
+        # was not run". Only a FileNotFoundError from stage_dir (no {stage}_NN
+        # dir) degrades to None.
+        try:
+            config = _cfg.load_config(cfg_path)
+        except _CONFIG_LOAD_ERRORS as exc:
+            raise SystemExit(str(exc)) from exc
+        try:
+            return str(
+                stage_dir(
+                    config, stage, output_root=root,
+                    strict=getattr(args, "strict", False),
+                    latest=getattr(args, "latest", False),
+                )
+            )
+        except FileNotFoundError as exc:
+            if optional:  # stage simply absent -> degrade gracefully
+                return None
+            raise SystemExit(str(exc)) from exc
+        except StageConflict as exc:
+            if conflict_ok:  # cosmetic lookup: ambiguity is non-fatal
+                return None
+            # For a data stage a conflict must surface even when optional,
+            # rather than silently dropping the user's data.
+            raise SystemExit(str(exc)) from exc
+        except (ValueError, OSError) as exc:
+            raise SystemExit(str(exc)) from exc
+    if not root:
+        raise SystemExit("one of --config or --root is required")
+    from odas_tpw.perturb.plot import layout
+
+    return layout.latest_stage_dir(root, stage)