quantmet-tools 0.4.4__py3-none-any.whl

quantmet/stats.py

@@ -0,0 +1,368 @@
+"""Significance tools for geophysical time series and composites: false
+discovery rate, regression with AR(1) errors, the variance inflation of a
+mean of autocorrelated values, event-block bootstrap composites, and
+permutation / bootstrap tests for correlations and classifiers.
+
+Numerical notes that matter in practice:
+- FALSE DISCOVERY RATE, NOT PER-POINT 5 %. A map or section of p-values
+  tested point by point at 5 % shades 5 % of a pure-noise field, in
+  spatially coherent blobs that look like signal. Benjamini-Hochberg (as
+  recommended for field significance by Wilks 2016, BAMS, with
+  alpha_FDR = 0.10) controls the expected share of false discoveries and
+  stays valid under the positive spatial correlation of geophysical fields.
+  NaN p-values (masked points) are excluded from the count, not treated as
+  1: a land mask should not make the ocean test stricter.
+- AR(1) ERRORS (prais_winsten). Monthly or daily anomalies are persistent
+  (lag-1 autocorrelation 0.8-0.95 for stratospheric age of air), so OLS
+  standard errors are too small by a factor ~sqrt((1+rho)/(1-rho)). Prais-
+  Winsten GLS keeps the first observation (scaled by sqrt(1 - rho^2))
+  instead of dropping it as Cochrane-Orcutt does, and `start` marks rows
+  that begin a new contiguous segment -- after an excluded volcanic window,
+  say -- which are scaled like the first row instead of being differenced
+  against a row that is not their predecessor.
+- BARTLETT, NOT AR(1), FOR THE NOISE OF A MEAN (acf_inflation). The
+  variance of an n-day mean is var/n x (1 + 2 sum_k (1 - k/n) rho_k). An
+  AR(1) model fills that sum from rho_1 alone, which fails for oscillating
+  series: a daily index with rho_1 = 0.59 but a ~6-day oscillation
+  (rho_3 = -0.44, rho_6 = +0.31) has an AR(1) inflation of 3.9 and a
+  Bartlett-window inflation (L = 10) of ~1.3 -- the AR(1) model overstates
+  the noise of a 30-day mean about threefold. The Bartlett sum uses the
+  measured autocorrelations with weights 1 - k/(L+1).
+- RESAMPLE EVENTS, NOT DAYS (event_bootstrap). Days of one event (an MJO
+  phase passage, an SSW) are not independent; a day bootstrap understates
+  the composite's spread by the square root of the event length. Resampling
+  whole events with replacement, each carrying all of its days, keeps the
+  within-event correlation. The composite is the mean over resampled DAYS
+  (events weighted by their length), as the composite itself is.
+- FREEDMAN-LANE (partial_corr_test). To test x against y given covariates
+  Z, permute the residuals of the REDUCED model (y on Z), add them back to
+  its fitted values, and recompute the partial correlation. Permuting the
+  residuals of x and correlating them with those of y (Kennedy 1995)
+  ignores that the permuted residuals are no longer orthogonal to Z and is
+  anti-conservative in small samples with correlated covariates.
+
+Consolidated from the significance code of the stratosphere, MJO and
+age-of-air products on https://scorvec.com/stratosphere.html and
+https://scorvec.com/mjo.html.
+
+Requires: numpy, scipy (distributions, ranks).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = [
+    "fdr_adjust",
+    "benjamini_hochberg",
+    "prais_winsten",
+    "PraisWinsten",
+    "segment_starts",
+    "acf_inflation",
+    "label_events",
+    "event_bootstrap",
+    "pearson",
+    "residualize",
+    "partial_corr_test",
+    "compare_r",
+    "auc",
+]
+
+
+# --------------------------------------------------------------------------
+# False discovery rate
+# --------------------------------------------------------------------------
+def fdr_adjust(p) -> np.ndarray:
+    """Benjamini-Hochberg adjusted p-values (q-values), any shape; NaN stays
+    NaN and is excluded from the count. Same as
+    scipy.stats.false_discovery_control(p, method="bh") on the finite p."""
+    p = np.asarray(p, float)
+    out = np.full(p.shape, np.nan)
+    ok = np.isfinite(p)
+    q = p[ok]
+    n = q.size
+    if n == 0:
+        return out
+    o = np.argsort(q)
+    adj = q[o] * n / np.arange(1, n + 1)
+    adj = np.minimum.accumulate(adj[::-1])[::-1]
+    res = np.empty(n)
+    res[o] = np.clip(adj, 0, 1)
+    out[ok] = res
+    return out
+
+
+def benjamini_hochberg(p, alpha: float = 0.10) -> np.ndarray:
+    """Boolean mask (p's shape) of discoveries at false discovery rate alpha:
+    every finite p at or below the largest p_(i) with p_(i) <= alpha i / n."""
+    p = np.asarray(p, float)
+    ok = np.isfinite(p)
+    out = np.zeros(p.shape, bool)
+    s = np.sort(p[ok])
+    n = s.size
+    if n == 0:
+        return out
+    below = s <= alpha * np.arange(1, n + 1) / n
+    if below.any():
+        out = ok & (p <= s[np.flatnonzero(below).max()])
+    return out
+
+
+# --------------------------------------------------------------------------
+# Regression with AR(1) errors
+# --------------------------------------------------------------------------
+@dataclass
+class PraisWinsten:
+    """beta (k, m), se (k, m), rho (m,), dof; m = number of series."""
+
+    beta: np.ndarray
+    se: np.ndarray
+    rho: np.ndarray
+    dof: int
+
+
+def segment_starts(keep) -> np.ndarray:
+    """For the retained rows of a boolean mask over a regular time axis:
+    True where the previous time step was not retained (a new segment)."""
+    idx = np.flatnonzero(np.asarray(keep, bool))
+    return np.r_[True, np.diff(idx) > 1] if idx.size else np.zeros(0, bool)
+
+
+def prais_winsten(y, X, start=None, iters: int = 2, rho_max: float = 0.97) -> PraisWinsten:
+    """GLS with AR(1) errors (Prais-Winsten), iterated `iters` times.
+
+    y     : (n,) or (n, m) -- m series sharing one design
+    X     : (n, k) design matrix (include the intercept column yourself)
+    start : (n,) bool, rows that begin a contiguous segment (row 0 always
+            does); they are scaled by sqrt(1 - rho^2) like the first row
+            instead of being quasi-differenced. See segment_starts.
+    rho is estimated from residual pairs within segments only and clipped to
+    +-rho_max. se is the GLS standard error with dof = n - k."""
+    y = np.asarray(y, float)
+    one = y.ndim == 1
+    Y = y[:, None] if one else y
+    X = np.asarray(X, float)
+    n, k = X.shape
+    st = np.zeros(n, bool) if start is None else np.asarray(start, bool).copy()
+    st[0] = True
+    pair = ~st[1:]
+    nx = np.flatnonzero(~st)
+    beta = np.linalg.lstsq(X, Y, rcond=None)[0]
+    rho = np.zeros(Y.shape[1])
+    se = np.zeros_like(beta)
+    for _ in range(max(1, iters)):
+        r = Y - X @ beta
+        num = (r[1:][pair] * r[:-1][pair]).sum(0)
+        den = (r[:-1][pair] ** 2).sum(0)
+        rho = np.clip(np.divide(num, den, out=np.zeros_like(num), where=den > 0), -rho_max, rho_max)
+        beta = np.empty((k, Y.shape[1]))
+        se = np.empty((k, Y.shape[1]))
+        for j in range(Y.shape[1]):
+            c = np.sqrt(1 - rho[j] ** 2)
+            ys = np.empty(n)
+            Xs = np.empty_like(X)
+            ys[st] = c * Y[st, j]
+            Xs[st] = c * X[st]
+            ys[nx] = Y[nx, j] - rho[j] * Y[nx - 1, j]
+            Xs[nx] = X[nx] - rho[j] * X[nx - 1]
+            b = np.linalg.lstsq(Xs, ys, rcond=None)[0]
+            e = ys - Xs @ b
+            s2 = (e @ e) / (n - k)
+            beta[:, j] = b
+            se[:, j] = np.sqrt(np.diag(s2 * np.linalg.inv(Xs.T @ Xs)))
+    if one:
+        return PraisWinsten(beta[:, 0], se[:, 0], rho[:1], n - k)
+    return PraisWinsten(beta, se, rho, n - k)
+
+
+# --------------------------------------------------------------------------
+# Autocorrelation
+# --------------------------------------------------------------------------
+def acf_inflation(res, times=None, lags: int = 10, clip=(1.0, None)) -> np.ndarray:
+    """Variance inflation of a mean of autocorrelated values,
+    1 + 2 sum_{k=1..L} (1 - k/(L+1)) rho_k (Bartlett window, L = lags),
+    per series along axis 0 of `res`.
+
+    times : optional datetime64-like array (one per row); the rows are then
+            placed on a daily grid with NaN gaps, so the lags are in days
+            even when some days are missing. None: rows are consecutive.
+    clip  : (lo, hi) bounds on the result (None = open)."""
+    R = np.asarray(res, float)
+    if times is not None:
+        d = np.asarray(times, dtype="datetime64[D]")
+        k = (d - d.min()).astype(int)
+        full = np.full((k.max() + 1, *R.shape[1:]), np.nan)
+        full[k] = R
+        R = full
+    R = R - np.nanmean(R, 0)
+    v = np.nanmean(R * R, 0)
+    infl = np.ones(R.shape[1:])
+    for k in range(1, lags + 1):
+        rk = np.nanmean(R[k:] * R[:-k], 0) / v
+        infl = infl + 2 * (1 - k / (lags + 1)) * np.nan_to_num(rk)
+    lo, hi = clip
+    return np.clip(infl, lo, hi) if (lo is not None or hi is not None) else infl
+
+
+# --------------------------------------------------------------------------
+# Composites
+# --------------------------------------------------------------------------
+def label_events(key, active) -> np.ndarray:
+    """Event id per time step: a run of consecutive active steps with the
+    same key (e.g. the MJO phase) is one event; -1 where inactive."""
+    key = np.asarray(key)
+    active = np.asarray(active, bool)
+    ev = np.full(key.shape[0], -1)
+    k = -1
+    for i in range(key.shape[0]):
+        if active[i]:
+            if i == 0 or not active[i - 1] or key[i] != key[i - 1]:
+                k += 1
+            ev[i] = k
+    return ev
+
+
+def event_bootstrap(X, events, nboot: int = 1000, rng=None, return_samples: bool = False):
+    """Composite mean of X (ndays, ...) over its rows and its standard error
+    from an EVENT bootstrap: events (one id per row) are resampled with
+    replacement and carry all their rows. NaN in X is skipped per cell.
+
+    Returns (mean, se), plus the (nboot, ...) bootstrap means if
+    return_samples. se is NaN with fewer than two events."""
+    X = np.asarray(X, float)
+    ev = np.asarray(events)
+    if ev.shape[0] != X.shape[0]:
+        raise ValueError("one event id per row of X")
+    rng = np.random.default_rng(rng)
+    flat = X.reshape(X.shape[0], -1)
+    ok = np.isfinite(flat)
+    with np.errstate(invalid="ignore"):
+        mean = np.where(ok.any(0), np.nansum(flat, 0) / ok.sum(0), np.nan)
+    ue, inv = np.unique(ev, return_inverse=True)
+    ne = ue.size
+    shape = X.shape[1:]
+    if ne < 2:
+        nan = np.full(shape, np.nan)
+        return (mean.reshape(shape), nan) + ((np.full((0, *shape), np.nan),) if return_samples else ())
+    S = np.zeros((ne, flat.shape[1]))
+    C = np.zeros((ne, flat.shape[1]))
+    np.add.at(S, inv, np.where(ok, flat, 0.0))
+    np.add.at(C, inv, ok.astype(float))
+    R = rng.integers(0, ne, size=(nboot, ne))
+    W = np.zeros((nboot, ne))
+    np.add.at(W, (np.repeat(np.arange(nboot), ne), R.ravel()), 1.0)
+    den = W @ C
+    with np.errstate(invalid="ignore", divide="ignore"):
+        bm = (W @ S) / np.where(den > 0, den, np.nan)
+    se = np.nanstd(bm, axis=0)
+    out = (mean.reshape(shape), se.reshape(shape))
+    return out + ((bm.reshape((nboot, *shape)),) if return_samples else ())
+
+
+# --------------------------------------------------------------------------
+# Correlation tests
+# --------------------------------------------------------------------------
+def pearson(x, y) -> float:
+    x = np.asarray(x, float) - np.mean(x)
+    y = np.asarray(y, float) - np.mean(y)
+    return float((x * y).sum() / np.sqrt((x * x).sum() * (y * y).sum()))
+
+
+def _design(covs, n):
+    cols = [np.ones(n)] + [np.asarray(c, float) for c in (covs or [])]
+    return np.column_stack(cols)
+
+
+def residualize(y, covs):
+    """Residual of y after OLS on an intercept and the covariates."""
+    y = np.asarray(y, float)
+    Z = _design(covs, y.size)
+    return y - Z @ np.linalg.lstsq(Z, y, rcond=None)[0]
+
+
+def partial_corr_test(x, y, covs=(), nperm: int = 9999, nboot: int = 9999, rng=None) -> dict:
+    """Partial correlation of x with y given covariates, with
+
+    p_perm : two-sided Freedman-Lane permutation p (reduced-model
+             residuals of y permuted, added back to its fitted values)
+    ci     : 95 % bootstrap interval (rows resampled, covariates refit)
+    p_F    : nested-OLS F-test p for adding x to the covariates
+    dR2    : the R^2 that x adds.
+    """
+    from scipy import stats
+
+    rng = np.random.default_rng(rng)
+    x = np.asarray(x, float)
+    y = np.asarray(y, float)
+    n = x.size
+    covs = [np.asarray(c, float) for c in covs]
+    Z = _design(covs, n)
+    Hz = Z @ np.linalg.pinv(Z)  # hat matrix of the reduced model
+    rx = x - Hz @ x
+    yfit = Hz @ y
+    ry = y - yfit
+    r = pearson(rx, ry)
+    count = 0
+    for _ in range(nperm):
+        ys = yfit + rng.permutation(ry)
+        rs = pearson(rx, ys - Hz @ ys)
+        count += abs(rs) >= abs(r) - 1e-12
+    p_perm = (count + 1) / (nperm + 1)
+    bs = []
+    for _ in range(nboot):
+        i = rng.integers(0, n, n)
+        a = residualize(x[i], [c[i] for c in covs])
+        b = residualize(y[i], [c[i] for c in covs])
+        if a.std() > 0 and b.std() > 0:
+            bs.append(pearson(a, b))
+    k = len(covs)
+    rss0 = (ry**2).sum()
+    rss1 = (residualize(y, [*covs, x]) ** 2).sum()
+    F = (rss0 - rss1) / (rss1 / (n - k - 2))
+    return {
+        "r": r,
+        "p_perm": float(p_perm),
+        "ci": (float(np.percentile(bs, 2.5)), float(np.percentile(bs, 97.5))),
+        "p_F": float(stats.f.sf(F, 1, n - k - 2)),
+        "dR2": float((rss0 - rss1) / ((y - y.mean()) ** 2).sum()),
+        "n": n,
+    }
+
+
+def compare_r(x1, x2, y, nboot: int = 9999, rng=None) -> dict:
+    """Is x1 a better linear predictor of y than x2? d = |r(x1, y)| -
+    |r(x2, y)| with a paired bootstrap (the same resampled rows for both, so
+    their correlation is respected): 95 % interval and p = share of
+    resamples with d <= 0 (one-sided, x1 not better)."""
+    rng = np.random.default_rng(rng)
+    x1, x2, y = (np.asarray(a, float) for a in (x1, x2, y))
+    d0 = abs(pearson(x1, y)) - abs(pearson(x2, y))
+    n = y.size
+    ds = np.empty(nboot)
+    for b in range(nboot):
+        i = rng.integers(0, n, n)
+        ds[b] = abs(pearson(x1[i], y[i])) - abs(pearson(x2[i], y[i]))
+    ds = ds[np.isfinite(ds)]
+    return {
+        "diff_abs_r": float(d0),
+        "ci": (float(np.percentile(ds, 2.5)), float(np.percentile(ds, 97.5))),
+        "p_not_better": float(np.mean(ds <= 0)),
+    }
+
+
+def auc(score, label) -> float:
+    """Area under the ROC curve of `score` for binary `label` (1 = event):
+    the Mann-Whitney probability that an event outscores a non-event, ties
+    counted half (average ranks)."""
+    from scipy.stats import rankdata
+
+    score = np.asarray(score, float)
+    label = np.asarray(label).astype(bool)
+    n1 = label.sum()
+    n0 = label.size - n1
+    if n1 == 0 or n0 == 0:
+        return float("nan")
+    r = rankdata(score)
+    return float((r[label].sum() - n1 * (n1 + 1) / 2) / (n1 * n0))

quantmet/tc.py

@@ -0,0 +1,320 @@
+"""Tropical cyclones in ensemble forecasts: ECMWF track decoding, recurvature, the outflow-jet interaction metric, and
+Hart's cyclone phase space.
+
+Tracks. ECMWF disseminates its tropical-cyclone tracker output as BUFR (open data: ``...-enfo-tf.bufr`` for the
+ensembles, ``...-oper-tf.bufr`` for the deterministic runs). One message per storm, one subset per ensemble member;
+the ``ensembleForecastType`` is 1 for the unperturbed control, 4 for perturbed members, 0 for the high-resolution
+deterministic run carried in the same file (excluded here). The analysis position is ``#2#latitude`` (falling back to
+the observed ``#1#latitude``); step i of the delayed replication is ``#i#timePeriod`` with the centre at
+``#(2i+2)#latitude`` and MSLP / max wind at ``#(i+1)#``. The tracker also repeats named storms under placeholder
+genesis ids (70-99 + basin letter); de-duplicate by position if you merge them.
+
+Recurvature: the lead where the storm's 24-h zonal motion turns from westward (<= -1 m/s) to eastward (>= +2 m/s).
+A storm heading north or east from the start has none (it never had a westward phase in the forecast).
+
+Outflow metric (Archambault, Bosart, Keyser & Cordeira 2013, MWR 141; Archambault et al. 2015, MWR 143): negative PV
+advection by the irrotational wind, -v_chi . grad(PV), in the 300-200 hPa layer. The divergent outflow of a recurving
+storm pushes low-PV air poleward against the PV gradient at the jet, building the downstream ridge. ``outflow_index``
+is the area mean of the negative part within 500 km of the centre, sign flipped (PVU/day; 0 = no interaction).
+Numerics: v_chi from a spherical-harmonic inversion (quantmet.helmholtz) is smooth by construction, while the PV
+gradient on a 0.25 deg grid is grid-noisy -- smooth PV (~1 deg) before differentiating, or the contours speckle.
+
+Hart (2003, MWR 131) phase space, within 500 km of the centre:
+  B     = (Z_top - Z_bottom) thickness right of the storm motion minus left (m, NH sign; negate in the SH).
+          |B| ~ 0 thermally symmetric (tropical); B > 10 m marks extratropical-transition ONSET (Evans & Hart 2003).
+  -VT_L = d(dZ)/d(ln p) over 900-600 hPa, dZ = Zmax - Zmin in the disc; > 0 warm core, < 0 cold core.
+  -VT_U = the same over 600-300 hPa.  ET is COMPLETE when -VT_L turns negative after onset.
+Hart used 25 hPa levels; with fewer levels (open data: 925/850/700/600/500/400/300) the fit is coarser -- say so.
+Parameters are conventionally smoothed with a 24-h running mean.
+
+Powers the tropical-cyclone cards at https://scorvec.com/circulation.html.
+
+Requires: numpy; eccodes for ``decode_tracks``; pyshtools + xarray for ``irrotational_on_grid``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .constants import A_EARTH
+
+MISSING = -1e99
+__all__ = [
+    "decode_tracks",
+    "at",
+    "great_circle_km",
+    "within",
+    "recurvature",
+    "irrotational_on_grid",
+    "pv_advection",
+    "outflow_index",
+    "hart_parameters",
+    "phase_series",
+    "et_times",
+]
+
+
+# ── tracks ────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+
+def decode_tracks(path) -> list[dict]:
+    """All storms in an ECMWF tf BUFR file: [{id, name, named, tracks: {member: track}}]; member 0 = control,
+    1..N perturbed; track = dict(steps (h), lat, lon (-180..180), pmsl (hPa), wind (m/s)). The deterministic subset
+    (ensembleForecastType 0) is excluded."""
+    import eccodes as ec
+
+    out = []
+    with open(path, "rb") as f:
+        while True:
+            h = ec.codes_bufr_new_from_file(f)
+            if h is None:
+                break
+            try:
+                ec.codes_set(h, "unpack", 1)
+                sid = ec.codes_get(h, "#1#stormIdentifier").strip()
+                name = ec.codes_get(h, "#1#longStormName").strip()
+                ft = np.atleast_1d(ec.codes_get_array(h, "#1#ensembleForecastType"))
+                mem = np.atleast_1d(ec.codes_get_array(h, "#1#ensembleMemberNumber"))
+                n = len(ft)
+
+                def arr(key, h=h, n=n):
+                    a = np.atleast_1d(ec.codes_get_array(h, key)).astype(float)
+                    return np.repeat(a, n) if a.size == 1 else a
+
+                rep = ec.codes_get(h, "#1#delayedDescriptorReplicationFactor")
+                a_la, a_lo = arr("#2#latitude"), arr("#2#longitude")
+                o_la, o_lo = arr("#1#latitude"), arr("#1#longitude")
+                a_la = np.where(a_la > MISSING, a_la, o_la)
+                a_lo = np.where(a_lo > MISSING, a_lo, o_lo)
+                cols = [(np.zeros(n), a_la, a_lo, arr("#1#pressureReducedToMeanSeaLevel"), arr("#1#windSpeedAt10M"))]
+                cols.extend(
+                    (
+                        arr(f"#{i}#timePeriod"),
+                        arr(f"#{2 * i + 2}#latitude"),
+                        arr(f"#{2 * i + 2}#longitude"),
+                        arr(f"#{i + 1}#pressureReducedToMeanSeaLevel"),
+                        arr(f"#{i + 1}#windSpeedAt10M"),
+                    )
+                    for i in range(1, rep + 1)
+                )
+                tracks = {}
+                for j in range(n):
+                    if ft[j] not in (1, 4):
+                        continue
+                    rows = [
+                        (c[0][j], c[1][j], c[2][j], c[3][j], c[4][j])
+                        for c in cols
+                        if c[1][j] > MISSING and c[0][j] > MISSING
+                    ]
+                    if not rows:
+                        continue
+                    st, la, lo, p, w = (np.array(x, float) for x in zip(*rows))
+                    m = 0 if ft[j] == 1 else int(mem[j])
+                    tracks[m] = dict(
+                        steps=st.astype(int),
+                        lat=la,
+                        lon=(lo + 180) % 360 - 180,
+                        pmsl=np.where(p > MISSING, p / 100.0, np.nan),
+                        wind=np.where(w > MISSING, w, np.nan),
+                    )
+                if tracks:
+                    named = not (sid[:2].isdigit() and int(sid[:2]) >= 70)
+                    out.append(dict(id=sid, name=name, named=named, tracks=tracks))
+            finally:
+                ec.codes_release(h)
+    return out
+
+
+def at(track: dict, h: int):
+    """(lat, lon) of the track at lead h, or None."""
+    k = np.where(np.asarray(track["steps"]) == h)[0]
+    return (float(track["lat"][k[0]]), float(track["lon"][k[0]])) if len(k) else None
+
+
+def great_circle_km(la1, lo1, la2, lo2):
+    p1, p2, dl = np.deg2rad(la1), np.deg2rad(la2), np.deg2rad(np.asarray(lo2) - np.asarray(lo1))
+    c = np.sin(p1) * np.sin(p2) + np.cos(p1) * np.cos(p2) * np.cos(dl)
+    return A_EARTH / 1000 * np.arccos(np.clip(c, -1, 1))
+
+
+def within(lat, lon, clat, clon, r_km) -> np.ndarray:
+    """(lat, lon) boolean mask of grid points within r_km of (clat, clon)."""
+    return great_circle_km(np.asarray(lat, float)[:, None], np.asarray(lon, float)[None, :], clat, clon) <= r_km
+
+
+def recurvature(track: dict, west: float = -1.0, east: float = 2.0):
+    """Lead (h) of the turn: the last point with no eastward motion (24-h zonal motion <= 0) before the motion first
+    reaches >= east m/s, for a track that moved westward (<= west m/s) earlier; None if it never did or never turns
+    east. Needs steps every 12 h or finer."""
+    st = np.asarray(track["steps"], float)
+    la = np.asarray(track["lat"], float)
+    lo = np.rad2deg(np.unwrap(np.deg2rad(np.asarray(track["lon"], float))))
+    if len(st) < 5:
+        return None
+    u = np.full(len(st), np.nan)
+    for k in range(len(st)):
+        a = np.where(np.abs(st - (st[k] - 12)) < 1e-6)[0]
+        b = np.where(np.abs(st - (st[k] + 12)) < 1e-6)[0]
+        if len(a) and len(b):
+            u[k] = (lo[b[0]] - lo[a[0]]) * 111.2e3 * np.cos(np.deg2rad(la[k])) / 86400.0
+    w = np.where(u <= west)[0]
+    if not len(w):
+        return None
+    e = np.where((u >= east) & (np.arange(len(u)) > w[0]))[0]
+    if not len(e):
+        return None
+    k0 = int(np.where((u <= 0) & (np.arange(len(u)) < e[0]))[0][-1])
+    return int(st[k0])
+
+
+# ── outflow metric ────────────────────────────────────────────────────────────────────────────────────────────────
+
+
+def irrotational_on_grid(u2d, v2d, lat, lon, lmax: int = 106):
+    """(u_chi, v_chi) from global (lat, lon) xarray DataArrays u2d, v2d (dims latitude/longitude), interpolated to the
+    target (lat, lon) grid (degrees; lon in 0..360). Uses quantmet.helmholtz (spherical-harmonic inversion, T lmax)."""
+    import xarray as xr
+    from .helmholtz import irrotational_wind, velocity_potential
+
+    chi, dlat, dlon_ = velocity_potential(u2d, v2d, lmax=lmax)
+    uc, vc = irrotational_wind(chi, dlat, dlon_)
+    dl = np.asarray(dlon_, float)
+    if dl[-1] < 360.0 - 1e-6:
+        dl = np.r_[dl, dl[0] + 360.0]
+        uc = np.concatenate([uc, uc[:, :1]], axis=1)
+        vc = np.concatenate([vc, vc[:, :1]], axis=1)
+    dla = np.asarray(dlat, float)
+    keep = np.r_[True, np.diff(dla) != 0]
+    U = xr.DataArray(uc[keep], dims=("lat", "lon"), coords={"lat": dla[keep], "lon": dl}).sortby("lat")
+    V = xr.DataArray(vc[keep], dims=("lat", "lon"), coords={"lat": dla[keep], "lon": dl}).sortby("lat")
+    tgt = dict(
+        lat=xr.DataArray(np.asarray(lat, float), dims="y"), lon=xr.DataArray(np.asarray(lon, float) % 360, dims="x")
+    )
+    return U.interp(**tgt).values, V.interp(**tgt).values
+
+
+def pv_advection(uchi, vchi, pv_layer, lat, lon, sigma_deg: float = 1.0) -> np.ndarray:
+    """-v_chi . grad(PV) in PVU/day on a regular (lat, lon) grid (degrees); PV in PVU, Gaussian-smoothed by sigma_deg
+    first (0 = no smoothing). Longitude periodic."""
+    from scipy.ndimage import gaussian_filter
+
+    lat = np.asarray(lat, float)
+    lon = np.asarray(lon, float)
+    pv = np.nan_to_num(np.asarray(pv_layer, float), nan=0.0)
+    if sigma_deg > 0:
+        n = sigma_deg / abs(lat[1] - lat[0])
+        pv = gaussian_filter(pv, sigma=(n, n), mode=("nearest", "wrap"))
+    phi = np.deg2rad(lat)
+    lam = np.deg2rad(lon)
+    cosphi = np.clip(np.cos(phi), 1e-3, None)[:, None]
+    dpdx = (np.roll(pv, -1, -1) - np.roll(pv, 1, -1)) / (2 * (lam[1] - lam[0])) / (A_EARTH * cosphi)
+    dpdy = np.gradient(pv, phi, axis=0) / A_EARTH
+    return -(uchi * dpdx + vchi * dpdy) * 86400.0
+
+
+def outflow_index(adv, lat, lon, clat, clon, r_km: float = 500.0) -> float:
+    """Area (cos lat) mean of max(-adv, 0) within r_km of (clat, clon), PVU/day."""
+    lat = np.asarray(lat, float)
+    lon = np.asarray(lon, float)
+    j = np.where(np.abs(lat - clat) <= r_km / 111.0 + 0.5)[0]
+    if not len(j):
+        return np.nan
+    m = within(lat[j], lon, clat, clon, r_km)
+    if not m.any():
+        return np.nan
+    w = np.broadcast_to(np.cos(np.deg2rad(lat[j]))[:, None], m.shape)[m]
+    return float(np.sum(np.maximum(-np.asarray(adv)[j][m], 0) * w) / np.sum(w))
+
+
+# ── Hart phase space ──────────────────────────────────────────────────────────────────────────────────────────────
+
+
+def _slope(dz, levs):
+    return float(np.polyfit(np.log(np.asarray(levs, float)), np.asarray(dz, float), 1)[0])
+
+
+def hart_parameters(
+    z,
+    levs,
+    lat,
+    lon,
+    clat,
+    clon,
+    motion_deg,
+    r_km: float = 500.0,
+    low=(900, 850, 800, 750, 700, 650, 600),
+    upp=(600, 550, 500, 450, 400, 350, 300),
+    thick=(600, 900),
+) -> dict:
+    """B, -VT_L, -VT_U (m) for one time.
+
+    z : geopotential HEIGHT (m), (lev, lat, lon); levs : hPa for axis 0; motion_deg : storm heading, degrees clockwise
+    from north. ``low``/``upp``/``thick`` are matched to the available levels (missing ones are dropped; at least two
+    per layer are needed). Southern-hemisphere storms: negate B (Hart's convention keeps B > 0 = frontal)."""
+    levs = [int(np.rint(x)) for x in levs]
+    low = [p for p in low if p in levs]
+    upp = [p for p in upp if p in levs]
+    if len(low) < 2 or len(upp) < 2:
+        raise ValueError("need at least two levels in each layer")
+    top, bot = thick
+    if top not in levs or bot not in levs:
+        bot = max(low)
+        top = min(low)
+    lat = np.asarray(lat, float)
+    lon = np.asarray(lon, float)
+    dl = r_km / 111.0 + 0.5
+    j = np.where(np.abs(lat - clat) <= dl)[0]
+    dlon = ((lon - clon + 180) % 360) - 180
+    i = np.where(np.abs(dlon) <= dl / max(np.cos(np.deg2rad(min(abs(clat) + dl, 80))), 0.2))[0]
+    la = np.deg2rad(lat[j])[:, None]
+    lo = np.deg2rad(lon[i])[None, :]
+    c0, l0 = np.deg2rad(clat), np.deg2rad(clon)
+    m = great_circle_km(lat[j][:, None], lon[i][None, :], clat, clon) <= r_km
+    brg = np.arctan2(np.sin(lo - l0) * np.cos(la), np.cos(c0) * np.sin(la) - np.sin(c0) * np.cos(la) * np.cos(lo - l0))
+    rel = ((brg - np.deg2rad(motion_deg) + np.pi) % (2 * np.pi)) - np.pi
+    right, left = m & (rel > 0) & (rel < np.pi), m & (rel < 0) & (rel > -np.pi)
+    Z = np.asarray(z, float)[:, j][:, :, i]
+    th = Z[levs.index(top)] - Z[levs.index(bot)]
+    B = float(th[right].mean() - th[left].mean()) if right.any() and left.any() else np.nan
+    dz = {p: float(Z[levs.index(p)][m].max() - Z[levs.index(p)][m].min()) for p in set(low) | set(upp)}
+    return dict(B=B, VTL=_slope([dz[p] for p in low], low), VTU=_slope([dz[p] for p in upp], upp))
+
+
+def phase_series(z_steps, levs, lat, lon, track: dict, steps, smooth_h: float = 24.0, **kw) -> dict:
+    """Hart parameters along a track: z_steps (step, lev, lat, lon) at the given steps (h). Storm motion from the
+    neighbouring track points; a ``smooth_h`` running mean (Hart: 24 h). Returns lists h, lat, lon, B, VTL, VTU."""
+    out = {"h": [], "lat": [], "lon": [], "B": [], "VTL": [], "VTU": []}
+    ts = np.asarray(track["steps"])
+    for k, h in enumerate(steps):
+        pos = at(track, int(h))
+        if pos is None:
+            continue
+        kk = np.where(ts == h)[0][0]
+        a, b = max(kk - 1, 0), min(kk + 1, len(ts) - 1)
+        if a == b:
+            continue
+        dlo = ((track["lon"][b] - track["lon"][a] + 180) % 360) - 180
+        mot = np.rad2deg(
+            np.arctan2(np.deg2rad(dlo) * np.cos(np.deg2rad(pos[0])), np.deg2rad(track["lat"][b] - track["lat"][a]))
+        )
+        r = hart_parameters(z_steps[k], levs, lat, lon, pos[0], pos[1], mot, **kw)
+        if pos[0] < 0:
+            r["B"] = -r["B"]
+        out["h"].append(int(h))
+        out["lat"].append(pos[0])
+        out["lon"].append(pos[1])
+        for key in ("B", "VTL", "VTU"):
+            out[key].append(r[key])
+    if smooth_h:
+        hh = np.array(out["h"], float)
+        for key in ("B", "VTL", "VTU"):
+            v = np.array(out[key], float)
+            out[key] = [float(np.nanmean(v[np.abs(hh - x) <= smooth_h / 2])) for x in hh]
+    return out
+
+
+def et_times(series: dict, b_onset: float = 10.0):
+    """Evans & Hart (2003): onset = first B > b_onset; completion = first -VT_L < 0 at or after onset."""
+    onset = next((h for h, b in zip(series["h"], series["B"]) if b > b_onset), None)
+    comp = next((h for h, v in zip(series["h"], series["VTL"]) if v < 0 and (onset is None or h >= onset)), None)
+    return onset, comp