microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/processing/chi_combine.py

@@ -0,0 +1,300 @@
+# May-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Multi-probe chi combining (mk_chi_mean).
+
+Mirrors :func:`odas_tpw.processing.epsilon_combine.mk_epsilon_mean` for
+chi: splits the 2-D ``chi(probe, time)`` from get_chi into per-probe
+1-D ``chi_1``, ``chi_2``, ... variables, then combines them into
+``chiMean`` (geometric mean of surviving probes) and ``chiLnSigma``
+(expected ``sigma_ln(chi)``) using the same variance / 95% CI
+machinery as the epsilon path. The 1-D split is what lets the depth
+binner pick chi up; without it chi vanishes between chi_NN/ and
+chi_combo_NN/.
+
+The variance model is Lueck-style ``5.5 / (1 + (L_hat/4)^(7/9))``
+borrowed from the dissipation pipeline. For chi this is a reasonable
+first-order estimate when the FFT segments are long compared to the
+Batchelor scale, but the chi-specific theoretical variance differs
+from the shear case; refine here if a chi-tuned model becomes
+available. The eq (18) spectral-truncation input, however, IS
+chi-specific: ``L_hat`` is multiplied by ``V_f**0.75`` using the
+Batchelor gradient-variance-resolved fraction stored as ``var_resolved``
+(chi.py::_batchelor_resolved_fraction), not the Nasmyth shear V_f
+(issue #104 U4-F1).
+"""
+
+import warnings
+
+import numpy as np
+import xarray as xr
+
+
+def _probe_sort_key(name: str) -> tuple[int, str]:
+    """Order probe variables by their trailing integer so chi_2 sorts before
+    chi_10 (plain lexicographic order puts chi_10 first). Names without a
+    numeric suffix sort last, by name (#24)."""
+    suffix = name.rsplit("_", 1)[-1]
+    return (int(suffix), "") if suffix.isdigit() else (2**31, name)
+
+
+def _stack_probe_var(ds: xr.Dataset, var: str, n_probe: int) -> np.ndarray | None:
+    """Stack a per-probe ``(probe, time)`` variable into ``(time, n_probe)``,
+    column-aligned with the chi probes; ``None`` when the variable or a matching
+    ``probe`` dim is absent.
+
+    The perturb pipeline always feeds ``chi(probe, time)`` (no pre-existing
+    ``chi_N``), so column ``i`` corresponds to probe index ``i`` (both from the
+    same ``probe`` dim).  Older / hand-built datasets that supply per-probe
+    ``chi_N`` as 1-D vars WITHOUT a matching ``probe`` dim return ``None`` here,
+    so the spectral QC is skipped rather than misaligned.
+    """
+    if var in ds and "probe" in ds[var].dims and ds.sizes.get("probe", 0) == n_probe:
+        return np.column_stack([ds[var].isel(probe=i).values for i in range(n_probe)])
+    return None
+
+
+def mk_chi_mean(
+    ds: xr.Dataset,
+    chi_minimum: float = 1e-13,
+    fom_limit: float | None = None,
+    k_max_ratio_min: float | None = None,
+) -> xr.Dataset:
+    """Combine per-probe chi into a mean estimate with CI filtering.
+
+    Steps (mirroring :func:`mk_epsilon_mean`):
+
+      1. If only ``chi(probe, time)`` is present, split into 1-D
+         ``chi_1``, ``chi_2``, ...
+      2. Floor small values (``<= chi_minimum``) to NaN.
+      3. Kolmogorov length ``L_K = (nu^3 / epsilon_T)^(1/4)`` when
+         ``epsilon_T`` is available, else fall back to the chi values
+         themselves so the CI machinery still has something to work
+         with.
+      4. Physical segment length ``L = speed * diss_length / fs``.
+      5. ``var_ln_chi = 5.5 / (1 + (L_hat/4)^(7/9))``; same Lueck-style
+         expression used for epsilon.
+      6. 95% CI range ``1.96 * sqrt(2) * mean(sigma_ln_chi)``.
+      7. Iteratively remove the probe FURTHEST from the cross-probe
+         ln-mean (symmetric — a low outlier is dropped as readily as a
+         high one) on rows whose min/max log-spread exceeds the CI range;
+         requires >= 3 probes and never prunes below 2 survivors.
+      8. ``chiMean`` = geometric mean of surviving probes; ``chiLnSigma``
+         = mean ``sigma_ln_chi`` across probes.
+
+    Parameters
+    ----------
+    ds : xr.Dataset
+        Dataset from ``get_chi``. Should contain ``chi(probe, time)`` or
+        per-probe ``chi_1``, ``chi_2``, ... 1-D vars; ``speed`` and
+        ``nu`` along ``time``; ``diss_length`` / ``fs_fast`` as scalar
+        attributes or variables; optionally ``epsilon_T(probe, time)``
+        for the Kolmogorov length term.
+    chi_minimum : float
+        Floor — values at or below are set to NaN.
+    fom_limit : float or None
+        Two-sided figure-of-merit band ``[1/fom_limit, fom_limit]`` for the soft
+        spectral QC.  ``None`` (default) disables the QC entirely (backward
+        compatible). Supply together with ``k_max_ratio_min``.
+    k_max_ratio_min : float or None
+        Minimum ``K_max/kB`` spectral-resolution ratio for the soft spectral QC.
+        ``None`` disables the QC. When both limits are set and per-probe
+        ``fom`` / ``K_max_ratio`` are present, probes failing the band or the
+        resolution floor are dropped from ``chiMean`` *unless* no probe in the
+        window passes, in which case all are kept (no window is dropped).
+
+    Returns
+    -------
+    xr.Dataset
+        Input dataset with ``chi_1``, ``chi_2``, ... promoted to 1-D
+        vars (when only ``chi`` was 2-D), plus ``chiMean`` and
+        ``chiLnSigma`` added.
+    """
+    ds = ds.copy()
+
+    probe_names = sorted(
+        (str(k) for k in ds.data_vars if str(k).startswith("chi_")),
+        key=_probe_sort_key,
+    )
+
+    if not probe_names and "chi" in ds and "probe" in ds.dims:
+        for i in range(ds.sizes["probe"]):
+            name = f"chi_{i + 1}"
+            ds[name] = ds["chi"].isel(probe=i)
+            probe_names.append(name)
+
+    if not probe_names:
+        warnings.warn("No per-probe chi variables (chi_1, chi_2, ...) found")
+        return ds
+
+    n_time = ds.sizes.get("time", 0)
+    if n_time == 0:
+        return ds
+
+    chi = np.column_stack([ds[name].values.copy() for name in probe_names])
+
+    chi[chi <= chi_minimum] = np.nan
+
+    # Soft spectral QC (issue #104 U3-C2): when fom/K_max_ratio limits are supplied
+    # and the per-probe fom / K_max_ratio arrays are present, prefer the probes
+    # inside the two-sided fom band with sufficient spectral resolution — the SAME
+    # thresholds `_compute_chi_final` uses for the rsi chi_final, so the perturb
+    # chiMean (and the K_T / Gamma built from it) is filtered consistently with the
+    # rsi pipeline.  It is SOFT: if no probe in a window passes, that window's
+    # probes are all restored (no window is ever dropped), mirroring
+    # `_compute_chi_final`'s fallback.  For 2-probe Method-1 data the K_max_ratio
+    # floor is largely inert (both probes share the epsilon-derived kB, so they
+    # pass/fail together and the fallback keeps both) — the QC only re-weights
+    # windows where the probes genuinely disagree in fit quality.
+    qc_comment: str | None = None
+    if fom_limit is not None and k_max_ratio_min is not None:
+        n_probe = chi.shape[1]
+        fom = _stack_probe_var(ds, "fom", n_probe)
+        kmr = _stack_probe_var(ds, "K_max_ratio", n_probe)
+        if fom is not None and kmr is not None:
+            with np.errstate(invalid="ignore"):
+                passes = (
+                    np.isfinite(fom)
+                    & (fom <= fom_limit)
+                    & (fom >= 1.0 / fom_limit)
+                    & np.isfinite(kmr)
+                    & (kmr >= k_max_ratio_min)
+                )
+            finite_chi = np.isfinite(chi)
+            # Restrict the drop to windows where at least one probe passes QC AND
+            # still has a finite chi, so a window is never emptied.
+            any_pass = np.any(passes & finite_chi, axis=1)
+            drop = (~passes) & finite_chi & any_pass[:, np.newaxis]
+            chi[drop] = np.nan
+            qc_comment = (
+                f"soft spectral QC applied: probes preferred inside fom band "
+                f"[{1.0 / fom_limit:.4g}, {fom_limit:.4g}] with K_max_ratio >= "
+                f"{k_max_ratio_min:.4g}; windows with no passing probe keep all "
+                f"probes (no window dropped)"
+            )
+
+    # Lueck (2022) eq (18) truncation-correction input, mirroring mk_epsilon_mean
+    # (issue #104 U4-F1).  The chi diss product now stores a genuine Batchelor
+    # variance-resolved fraction (chi.py::_batchelor_resolved_fraction, written to
+    # `var_resolved` by chi_io) — the fraction of the model temperature-gradient
+    # variance within [K_min, K_max], WITHOUT the FP07 |H|^2 (the chi-side analog
+    # of the Nasmyth V_f, NOT the shear value).  When present it corrects
+    # chiLnSigma for spectral truncation; older products lacking it keep the plain
+    # L_hat (guarded no-op / backward compatible).
+    var_resolved = _stack_probe_var(ds, "var_resolved", chi.shape[1])
+
+    speed = ds["speed"].values if "speed" in ds else np.ones(n_time)
+    nu = ds["nu"].values if "nu" in ds else np.full(n_time, 1e-6)
+
+    if "diss_length" in ds.attrs:
+        diss_length = float(ds.attrs["diss_length"])
+    elif "diss_length" in ds:
+        diss_length = float(ds["diss_length"].values)
+    else:
+        diss_length = 512.0
+
+    if "fs_fast" in ds.attrs:
+        fs = float(ds.attrs["fs_fast"])
+    elif "fs_fast" in ds:
+        fs = float(ds["fs_fast"].values)
+    else:
+        fs = 512.0
+
+    # Kolmogorov length: use epsilon_T(probe, time) when available; otherwise
+    # fall back to chi itself so L_hat / sigma still vary smoothly with the
+    # data.  The fallback is dimensionally invalid (chi is K^2/s, not W/kg),
+    # so the resulting sigma magnitudes are only nominal — in that case the
+    # CI-based probe removal below is DISABLED rather than discarding probes
+    # on a meaningless threshold.
+    have_eps_T = "epsilon_T" in ds and "probe" in ds["epsilon_T"].dims
+    if have_eps_T:
+        eps_T = np.column_stack(
+            [ds["epsilon_T"].isel(probe=i).values for i in range(ds.sizes["probe"])]
+        )
+    else:
+        eps_T = chi
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        L_K = (nu[:, np.newaxis] ** 3 / eps_T) ** 0.25
+
+    L = speed * diss_length / fs
+    L = L[:, np.newaxis]
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        L_hat = L / L_K
+        if var_resolved is not None:
+            # Lueck (2022) eq (18) L_hat_f = L_hat * V_f**0.75, using the Batchelor
+            # variance-resolved fraction stored by the chi path (see note above).
+            L_hat = L_hat * np.clip(var_resolved, 1e-6, 1.0) ** 0.75
+
+    with np.errstate(invalid="ignore"):
+        var_ln_chi = 5.5 / (1.0 + (L_hat / 4.0) ** (7.0 / 9.0))
+    sigma_ln_chi = np.sqrt(var_ln_chi)
+
+    mu_sigma = np.nanmean(sigma_ln_chi, axis=1)
+    CF95_range = 1.96 * np.sqrt(2.0) * mu_sigma
+
+    n_probes = chi.shape[1]
+    if not have_eps_T:
+        n_probes = 1  # skip the CI removal loop; sigma is only nominal
+        warnings.warn(
+            "epsilon_T not available: chiLnSigma is nominal (Kolmogorov "
+            "length fallback uses chi, which is dimensionally invalid); "
+            "CI-based probe removal disabled — all probes enter chiMean",
+            stacklevel=2,
+        )
+    # Drop the probe FURTHEST from the cross-probe ln-mean on each outside row
+    # (symmetric outlier rejection), and only with >= 3 probes where an outlier
+    # is identifiable -- mirrors the epsilon side. The old code always dropped
+    # the maximum, so a low junk probe survived and biased chiMean low; with 2
+    # probes it now keeps both (unbiased) rather than coin-flipping a drop.
+    if n_probes >= 3:
+        for _ in range(n_probes - 1):
+            with np.errstate(invalid="ignore", divide="ignore"):
+                ln_c = np.log(chi)
+                min_c = np.nanmin(chi, axis=1)
+                max_c = np.nanmax(chi, axis=1)
+                ratio = np.abs(np.log(max_c) - np.log(min_c))
+
+            # Skip rows already all-NaN (nanargmax raises on them). Also never
+            # prune below 2 surviving probes: with 2 left the pair is
+            # equidistant from its mean (no identifiable outlier) and the
+            # geometric mean is unbiased, so honor the documented "keep both"
+            # rule per-row, not just at the dataset level (#23/#49).
+            finite_count = np.sum(np.isfinite(chi), axis=1)
+            any_finite = finite_count > 0
+            outside = (ratio > CF95_range) & (finite_count > 2)
+            if not np.any(outside):
+                break
+
+            with np.errstate(invalid="ignore"):
+                ln_mean = np.nanmean(ln_c, axis=1, keepdims=True)
+                dev = np.abs(ln_c - ln_mean)
+            worst_idx = np.full(chi.shape[0], -1, dtype=np.int64)
+            worst_idx[any_finite] = np.nanargmax(dev[any_finite], axis=1)
+            for i in np.where(outside)[0]:
+                chi[i, worst_idx[i]] = np.nan
+
+    with np.errstate(invalid="ignore"):
+        chi_mean = np.exp(np.nanmean(np.log(chi), axis=1))
+
+    chi_mean_attrs = {"long_name": "combined chi (geometric mean)", "units": "K2 s-1"}
+    if qc_comment is not None:
+        chi_mean_attrs["comment"] = qc_comment
+    ds["chiMean"] = xr.DataArray(
+        chi_mean,
+        dims=["time"],
+        attrs=chi_mean_attrs,
+    )
+    sigma_attrs = {"long_name": "sigma of ln(chi)", "units": "1"}
+    if not have_eps_T:
+        sigma_attrs["comment"] = (
+            "NOMINAL: computed with chi substituted for epsilon_T in the "
+            "Kolmogorov length (dimensionally invalid); magnitudes are not "
+            "quantitative and were not used for probe selection"
+        )
+    ds["chiLnSigma"] = xr.DataArray(
+        mu_sigma,
+        dims=["time"],
+        attrs=sigma_attrs,
+    )
+
+    return ds

odas_tpw/processing/ct_align.py

@@ -0,0 +1,172 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""CT sensor alignment via cross-correlation.
+
+Aligns conductivity to temperature by finding the lag of maximum
+cross-correlation between diff(T) and diff(C), using a weighted median
+across profiles.
+
+Reference: Code/CT_align.m (70 lines)
+"""
+
+import numpy as np
+from scipy.signal import butter, correlate, lfilter
+
+
+def shift_edge_hold(x: np.ndarray, shift: int) -> np.ndarray:
+    """Shift *x* by *shift* samples, holding the edge value.
+
+    Unlike ``np.roll``, samples shifted past the array ends are filled
+    with the first/last value instead of wrapping around — wrapping
+    would splice one end of the record into the other.
+    """
+    if shift == 0:
+        return x.copy()
+    out = np.empty_like(x)
+    if shift > 0:
+        out[:shift] = x[0]
+        out[shift:] = x[:-shift]
+    else:
+        out[shift:] = x[-1]
+        out[:shift] = x[-shift:]
+    return out
+
+
+def _repair_nonfinite(
+    seg: np.ndarray,
+    min_finite: int = 10,
+    max_nonfinite_frac: float = 0.25,
+) -> np.ndarray | None:
+    """Linearly interpolate isolated non-finite samples in a profile segment.
+
+    Returns a repaired copy, or ``None`` when too little finite data remains
+    (fewer than *min_finite* finite samples, or the non-finite fraction exceeds
+    *max_nonfinite_frac*) to carry useful alignment information. A fully-finite
+    segment is returned unchanged.
+    """
+    finite = np.isfinite(seg)
+    if finite.all():
+        return seg
+    n_finite = int(finite.sum())
+    if n_finite < min_finite or (len(seg) - n_finite) > max_nonfinite_frac * len(seg):
+        return None
+    idx = np.arange(len(seg))
+    repaired = seg.copy()
+    # np.interp clamps to the edge finite values for leading/trailing gaps.
+    repaired[~finite] = np.interp(idx[~finite], idx[finite], seg[finite])
+    return repaired
+
+
+def ct_align(
+    T: np.ndarray,
+    C: np.ndarray,
+    fs: float,
+    profiles: list[tuple[int, int]],
+    max_lag_seconds: float = 5.0,
+) -> tuple[np.ndarray, float]:
+    """Align conductivity to temperature by cross-correlation.
+
+    Parameters
+    ----------
+    T : ndarray
+        Temperature array (slow rate).
+    C : ndarray
+        Conductivity array (slow rate).
+    fs : float
+        Sampling rate [Hz].
+    profiles : list of (start, end) tuples
+        Profile indices into slow-rate arrays.
+    max_lag_seconds : float
+        Maximum lag to search [s].
+
+    Returns
+    -------
+    C_aligned : ndarray
+        Shifted conductivity array.
+    lag_seconds : float
+        Applied lag in seconds.
+    """
+    if not profiles:
+        return C.copy(), 0.0
+
+    max_lag_samples = round(max_lag_seconds * fs)
+    fc = min(4.0, fs / 2.0 * 0.99)
+    bb, aa = butter(2, fc / (fs / 2.0))
+
+    per_profile = []
+    for s, e in profiles:
+        seg_T = T[s : e + 1]
+        seg_C = C[s : e + 1]
+        if len(seg_T) < 10:
+            continue
+
+        # Audit over-discard fix: convert_jac_c emits NaN for *isolated* corrupt
+        # conductivity samples (v_part==0 bit errors), not whole-segment
+        # corruption. The earlier guard skipped the ENTIRE profile on any single
+        # non-finite sample, silently forfeiting that cast's alignment whenever
+        # every profile carried one transient bad sample. Instead, linearly
+        # interpolate the few non-finite points (so the IIR lfilter cannot smear
+        # a NaN across the segment and drive a maximally-wrong lag), and only
+        # skip when too little finite data remains to carry alignment info.
+        rep_T = _repair_nonfinite(seg_T)
+        rep_C = _repair_nonfinite(seg_C)
+        if rep_T is None or rep_C is None:
+            continue
+        seg_T, seg_C = rep_T, rep_C
+
+        dx = lfilter(bb, aa, np.diff(seg_T) - np.mean(np.diff(seg_T)))
+        dy = lfilter(bb, aa, np.diff(seg_C) - np.mean(np.diff(seg_C)))
+
+        corr = correlate(dx, dy, mode="full")
+        norm = np.sqrt(np.sum(dx**2) * np.sum(dy**2))
+        if not np.isfinite(norm) or norm <= 0:
+            # A flatlined/constant T or C segment (norm == 0) carries no
+            # alignment information. Skip it: leaving it in would make
+            # argmax(|corr|) of an all-zero correlation pick index 0, i.e. the
+            # most-negative lag (-max_lag_seconds), a maximally-wrong estimate.
+            continue
+        corr = corr / norm
+
+        n = len(dx)
+        lags = np.arange(-(n - 1), n)
+
+        mask = np.abs(lags) <= max_lag_samples
+        corr = corr[mask]
+        lags = lags[mask]
+
+        idx = np.argmax(np.abs(corr))
+        lag = lags[idx]
+        max_corr = np.abs(corr[idx])
+        n_samples = e - s + 1
+
+        per_profile.append(
+            {
+                "lag": lag / fs,
+                "max_corr": max_corr,
+                "n_samples": n_samples,
+            }
+        )
+
+    if not per_profile:
+        return C.copy(), 0.0
+
+    # Weighted median: smallest lag whose cumulative weight reaches half the
+    # total. searchsorted gives the true (lower) weighted median; the old
+    # argmin(|cum_w - total/2|) picked the entry *closest* to the midpoint,
+    # which is biased toward the pre-crossing entry for skewed weights.
+    per_profile.sort(key=lambda x: x["lag"])
+    weights = np.array([p["max_corr"] * p["n_samples"] for p in per_profile])
+    cum_w = np.cumsum(weights)
+    total = float(cum_w[-1])
+    if not np.isfinite(total) or total <= 0:
+        # No usable correlation across any profile -> apply no shift.
+        return C.copy(), 0.0
+    mid_idx = int(np.searchsorted(cum_w, total / 2.0))
+    mid_idx = min(mid_idx, len(per_profile) - 1)
+    median_lag = per_profile[mid_idx]["lag"]
+
+    i_shift = round(median_lag * fs)
+    # Edge-hold instead of np.roll: wrapping would splice the start of
+    # the record into the end (ODAS trims instead).
+    C_aligned = shift_edge_hold(C, i_shift)
+
+    return C_aligned, median_lag

odas_tpw/processing/epsilon_combine.py

@@ -0,0 +1,210 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Multi-probe epsilon combining (mk_epsilon_mean).
+
+Combines dissipation estimates from multiple shear probes using
+the expected variance of ln(epsilon), iteratively removing probes
+outside the 95% confidence interval, then computing the geometric mean.
+
+Reference: Code/calc_diss_shear.m lines 238-299
+"""
+
+import warnings
+
+import numpy as np
+import xarray as xr
+
+
+def _probe_sort_key(name: str) -> tuple[int, str]:
+    """Order probe variables by their trailing integer so e_2 sorts before e_10
+    (plain lexicographic order puts e_10 first). Names without a numeric suffix
+    sort last, by name (#24)."""
+    suffix = name.rsplit("_", 1)[-1]
+    return (int(suffix), "") if suffix.isdigit() else (2**31, name)
+
+
+def mk_epsilon_mean(
+    ds: xr.Dataset,
+    epsilon_minimum: float = 1e-13,
+) -> xr.Dataset:
+    """Combine per-probe epsilon into a mean estimate with CI filtering.
+
+    Port of Matlab ``mk_epsilon_mean``:
+      1. Floor small values to NaN
+      2. Kolmogorov length: L_K = (nu^3 / epsilon)^(1/4)
+      3. Physical length: L = speed * diss_length / fs
+      4. Normalized: L_hat = L / L_K
+      5. var_ln_epsilon = 5.5 / (1 + (L_hat/4)^(7/9))
+      6. 95% CI range: 1.96 * sqrt(2) * mean(sigma_ln_epsilon)
+      7. Iteratively remove probes outside CI
+      8. Geometric mean of surviving probes
+
+    Parameters
+    ----------
+    ds : xr.Dataset
+        Dataset from ``get_diss``.  Must contain:
+        - ``e_1``, ``e_2``, ... (per-probe epsilon, 1D along 'time')
+        - ``speed`` (1D along 'time')
+        - ``nu`` (1D along 'time')
+        - ``diss_length`` (scalar attribute or variable)
+        - ``fs_fast`` (scalar attribute)
+    epsilon_minimum : float
+        Floor: values <= this are set to NaN.
+
+    Returns
+    -------
+    xr.Dataset
+        Input dataset with ``epsilonMean`` and ``epsilonLnSigma`` added.
+    """
+    ds = ds.copy()
+
+    # Find epsilon probe variables — either separate e_1/e_2/... or 2D epsilon(probe, time)
+    probe_names = sorted(
+        (str(k) for k in ds.data_vars if str(k).startswith("e_")),
+        key=_probe_sort_key,
+    )
+
+    if not probe_names and "epsilon" in ds and "probe" in ds.dims:
+        # Split 2D epsilon(probe, time) into per-probe variables
+        for i in range(ds.sizes["probe"]):
+            name = f"e_{i + 1}"
+            ds[name] = ds["epsilon"].isel(probe=i)
+            probe_names.append(name)
+
+    if not probe_names:
+        warnings.warn("No per-probe epsilon variables (e_1, e_2, ...) found")
+        return ds
+
+    n_time = ds.sizes.get("time", 0)
+    if n_time == 0:
+        return ds
+
+    # Stack epsilon into 2D array [time x probes]
+    epsilon = np.column_stack([ds[name].values.copy() for name in probe_names])
+
+    # Floor small values
+    epsilon[epsilon <= epsilon_minimum] = np.nan
+
+    # Lueck (2022) eq (18) spectral-truncation correction input: the fraction of
+    # Nasmyth variance resolved below K_max, per probe (issue #104 U4-F1). Written
+    # by the diss build as var_resolved(probe, time); older diss NetCDFs lack it,
+    # in which case we fall back to the plain L_hat below.
+    var_resolved = None
+    if (
+        "var_resolved" in ds
+        and "probe" in ds["var_resolved"].dims
+        and ds.sizes.get("probe", 0) == len(probe_names)
+    ):
+        var_resolved = np.column_stack(
+            [ds["var_resolved"].isel(probe=i).values for i in range(len(probe_names))]
+        )
+
+    # Get parameters
+    speed = ds["speed"].values if "speed" in ds else np.ones(n_time)
+    nu = ds["nu"].values if "nu" in ds else np.full(n_time, 1e-6)
+
+    if "diss_length" in ds.attrs:
+        diss_length = float(ds.attrs["diss_length"])
+    elif "diss_length" in ds:
+        diss_length = float(ds["diss_length"].values)
+    else:
+        diss_length = 512.0
+
+    if "fs_fast" in ds.attrs:
+        fs = float(ds.attrs["fs_fast"])
+    elif "fs_fast" in ds:
+        fs = float(ds["fs_fast"].values)
+    else:
+        fs = 512.0
+
+    # Kolmogorov length
+    with np.errstate(invalid="ignore", divide="ignore"):
+        L_K = (nu[:, np.newaxis] ** 3 / epsilon) ** 0.25
+
+    # Physical length of the data segment
+    L = speed * diss_length / fs  # [time]
+    L = L[:, np.newaxis]  # [time x 1]
+
+    # Normalized length
+    with np.errstate(invalid="ignore", divide="ignore"):
+        L_hat = L / L_K
+        if var_resolved is not None:
+            # Lueck (2022) Part I eq (18): truncating the spectrum at K_max
+            # reduces the dof by V_f**(3/4), so reduce the nondimensional
+            # averaging length accordingly (L_hat_f = L_hat * V_f**0.75).
+            # Clip the floor so a zero/near-zero V_f cannot collapse L_hat.
+            L_hat = L_hat * np.clip(var_resolved, 1e-6, 1.0) ** 0.75
+
+    # Variance of ln(epsilon)
+    with np.errstate(invalid="ignore"):
+        var_ln_epsilon = 5.5 / (1.0 + (L_hat / 4.0) ** (7.0 / 9.0))
+    sigma_ln_epsilon = np.sqrt(var_ln_epsilon)
+
+    # Mean sigma across probes
+    mu_sigma = np.nanmean(sigma_ln_epsilon, axis=1)  # [time]
+    CF95_range = 1.96 * np.sqrt(2.0) * mu_sigma  # [time]
+
+    # Iterative removal of probes outside the 95% CI. With >= 3 probes we can
+    # identify an outlier and drop the probe whose ln(epsilon) is FURTHEST from
+    # the cross-probe ln-mean (the Lueck/Rockland mk_diss_mean rule), rejecting
+    # low and high outliers symmetrically. The old code unconditionally NaN'd
+    # the MAXIMUM probe, so a low junk probe always survived and biased
+    # epsilonMean low. With only 2 disagreeing probes there is no identifiable
+    # outlier (both are equidistant from their mean), so we KEEP BOTH rather
+    # than coin-flip a drop -- the geometric mean of the pair is unbiased,
+    # whereas always-drop-max systematically kept the lower probe.
+    n_probes = epsilon.shape[1]
+    if n_probes >= 3:
+        for _ in range(n_probes - 1):
+            with np.errstate(invalid="ignore", divide="ignore"):
+                ln_e = np.log(epsilon)
+                min_e = np.nanmin(epsilon, axis=1)
+                max_e = np.nanmax(epsilon, axis=1)
+                ratio = np.abs(np.log(max_e) - np.log(min_e))
+
+            # Skip rows already all-NaN (nanargmax raises on them). Also never
+            # prune below 2 surviving probes: with 2 left the pair is
+            # equidistant from its mean (no identifiable outlier) and the
+            # geometric mean is unbiased, so honor the documented "keep both"
+            # rule per-row, not just at the dataset level (#23/#49).
+            finite_count = np.sum(np.isfinite(epsilon), axis=1)
+            any_finite = finite_count > 0
+            outside = (ratio > CF95_range) & (finite_count > 2)
+            if not np.any(outside):
+                break
+
+            # Drop the probe furthest from the cross-probe ln-mean on each
+            # outside row (symmetric: a low outlier is as removable as a high).
+            with np.errstate(invalid="ignore"):
+                ln_mean = np.nanmean(ln_e, axis=1, keepdims=True)
+                dev = np.abs(ln_e - ln_mean)
+            worst_idx = np.full(epsilon.shape[0], -1, dtype=np.int64)
+            worst_idx[any_finite] = np.nanargmax(dev[any_finite], axis=1)
+            for i in np.where(outside)[0]:
+                epsilon[i, worst_idx[i]] = np.nan
+
+    # Geometric mean of surviving probes
+    with np.errstate(invalid="ignore"):
+        epsilon_mean = np.exp(np.nanmean(np.log(epsilon), axis=1))
+
+    ds["epsilonMean"] = xr.DataArray(
+        epsilon_mean,
+        dims=["time"],
+        attrs={"long_name": "combined epsilon (geometric mean)", "units": "W/kg"},
+    )
+    ds["epsilonLnSigma"] = xr.DataArray(
+        mu_sigma,
+        dims=["time"],
+        attrs={
+            "long_name": "sigma of ln(epsilon)",
+            "units": "1",
+            "comment": (
+                "Expected single-probe sigma_ln(epsilon) (Lueck 2022 "
+                "variance model eq 11), averaged across probes — NOT the sigma "
+                "of the combined epsilonMean (no sqrt(n) reduction applied). "
+                "When var_resolved (V_f) is present the eq (18) spectral-"
+                "truncation correction L_hat_f = L_hat * V_f**0.75 is applied."
+            ),
+        },
+    )
+
+    return ds