microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/perturb/seawater.py

@@ -0,0 +1,76 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Seawater properties via TEOS-10 (gsw).
+
+Reference: Code/add_seawater_properties.m
+"""
+
+import numpy as np
+import numpy.typing as npt
+
+
+def add_seawater_properties(
+    T: npt.ArrayLike,
+    C: npt.ArrayLike,
+    P: npt.ArrayLike,
+    lat: npt.ArrayLike,
+    lon: npt.ArrayLike,
+) -> dict[str, np.ndarray]:
+    """Compute seawater properties from T, C, P, lat, lon.
+
+    Parameters
+    ----------
+    T : array_like
+        In-situ temperature [degC] (from slow CT sensor, e.g. JAC_T).
+    C : array_like
+        Conductivity [mS/cm].
+    P : array_like
+        Pressure [dbar].
+    lat, lon : array_like
+        Latitude and longitude [degrees].
+
+    Returns
+    -------
+    dict with keys: SP, SA, CT, sigma0, rho, depth
+        SP = practical salinity [PSU]
+        SA = absolute salinity [g/kg]
+        CT = conservative temperature [degC]
+        sigma0 = potential density anomaly [kg/m^3]
+        rho = in-situ density - 1000 [kg/m^3]
+        depth = depth (positive downward) [m]
+    """
+    import gsw
+
+    # Fill masked cells with NaN (do NOT np.asarray a masked array — that drops
+    # the mask and exposes raw _FillValue, e.g. -999, as if it were real T/C/P).
+    def _filled(x):
+        return np.ma.filled(np.ma.asarray(x).astype(np.float64), np.nan)
+
+    T = _filled(T)
+    C = _filled(C)
+    P = _filled(P)
+    lat = _filled(lat)
+    lon = _filled(lon)
+
+    # Replace NaN lat/lon with 0 for gsw (matches Matlab default)
+    lat_safe = np.where(np.isnan(lat), 0.0, lat)
+    lon_safe = np.where(np.isnan(lon), 0.0, lon)
+
+    SP = gsw.SP_from_C(C, T, P)
+    SA = gsw.SA_from_SP(SP, P, lon_safe, lat_safe)
+    CT = gsw.CT_from_t(SA, T, P)
+    sigma0 = gsw.sigma0(SA, CT)
+    rho = gsw.rho(SA, CT, P) - 1000.0
+    # gsw.z_from_p returns height Z (m, <=0 below the surface); positive-down
+    # depth is -Z. Using -Z (not |Z|) keeps above-surface samples (P<0, e.g.
+    # deck calibrations) as negative depths instead of folding them back down.
+    z = gsw.z_from_p(P, lat_safe)
+    depth = -z
+
+    return {
+        "SP": np.asarray(SP),
+        "SA": np.asarray(SA),
+        "CT": np.asarray(CT),
+        "sigma0": np.asarray(sigma0),
+        "rho": np.asarray(rho),
+        "depth": np.asarray(depth),
+    }

odas_tpw/perturb/speed.py

@@ -0,0 +1,14 @@
+# May-2026, Pat Welch, pat@mousebrains.com
+"""Through-water speed for the perturb pipeline.
+
+The implementation now lives in :mod:`odas_tpw.rsi.speed` so the lower-level
+``rsi`` pipeline can share the exact same speed model (pressure / em / flight /
+constant) without a backwards dependency on ``perturb``. This module re-exports
+it for backward compatibility.
+"""
+
+from __future__ import annotations
+
+from odas_tpw.rsi.speed import compute_speed_for_pfile
+
+__all__ = ["compute_speed_for_pfile"]

odas_tpw/perturb/trim.py

@@ -0,0 +1,313 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Corrupt record trimming for .p files.
+
+If the last record is incomplete (fractional), copy only complete records
+to a new file.
+
+Reference: Code/trim_P_files.m
+"""
+
+import contextlib
+import json
+import os
+import struct
+import tempfile
+from pathlib import Path
+from typing import NamedTuple
+
+from odas_tpw.rsi.p_file import _H, HEADER_BYTES, HEADER_WORDS, _detect_endian
+
+
+class TrimResult(NamedTuple):
+    """Outcome of a single :func:`trim_p_file` call.
+
+    Attributes
+    ----------
+    dest : Path
+        The path downstream stages should read. For ``"trimmed"`` /
+        ``"skipped"`` this is the rewritten file under the trim directory;
+        for ``"referenced"`` it is the *original* source path, left in place.
+    action : str
+        One of:
+
+        * ``"trimmed"``    — a fractional final record was dropped; a new
+          truncated file was written to the trim directory.
+        * ``"referenced"`` — the file was already complete, so it is used
+          in place from its original location (no copy, no link).
+        * ``"skipped"``    — an up-to-date trimmed output already existed;
+          no work done.
+    bytes_removed : int
+        Bytes dropped from the incomplete final record. 0 unless
+        *action* is ``"trimmed"``.
+    record_size : int
+        The .p record size in bytes, read from the header. 0 when the file
+        was skipped (the header is not read on the skip path).
+    """
+
+    dest: Path
+    action: str
+    bytes_removed: int
+    record_size: int
+
+
+def trim_destination(source: Path, output_dir: Path, root: Path | str | None = None) -> Path:
+    """Return the trim output path for *source*.
+
+    When *root* is supplied and *source* lives underneath it, the relative
+    directory structure is preserved under *output_dir*.  This prevents files
+    such as ``SN001/cast.p`` and ``SN002/cast.p`` from overwriting each other.
+    """
+    source = Path(source)
+    output_dir = Path(output_dir)
+    if root is not None:
+        try:
+            rel = source.resolve().relative_to(Path(root).resolve())
+        except ValueError:
+            rel = Path(source.name)
+        return output_dir / rel
+    return output_dir / source.name
+
+
+# ---------------------------------------------------------------------------
+# Trim decision cache (incremental re-runs / slow mounts)
+# ---------------------------------------------------------------------------
+# A re-run otherwise re-opens and header-reads EVERY source .p to decide it
+# needs no trimming — cheap locally, but minutes over an SMB/network mount where
+# each open is a round-trip. The cache records, per source, a ``size + 2 s-mtime``
+# fingerprint and whether the file was complete (referenced) or trimmed, so an
+# unchanged file is decided from a single ``stat`` with no header read. Keyed on
+# the source's path *relative to the trim dir* (portable across machines/mounts),
+# and only trusted when its physical output is still present. ``force`` / a
+# changed fingerprint re-reads the header. mtime is binned to 2 s so the cache
+# survives a copy to exFAT (2 s mtime granularity) — the same file-identity model
+# as the per-file processing cache (pipeline._file_fingerprint). A same-size
+# header-geometry change (e.g. record_size) landing in the same 2 s mtime bin is
+# therefore not re-detected without ``force``; this is field-unreachable for raw
+# acquisition files.
+
+
+def _trim_fingerprint(source: Path) -> dict | None:
+    try:
+        st = source.stat()
+    except OSError:
+        return None
+    return {"size": st.st_size, "mtime_2s": int(st.st_mtime) // 2 * 2}
+
+
+def _trim_marker(cache_dir: Path, dest: Path, output_dir: Path) -> Path:
+    """Marker path mirroring the source's relative layout (collision-free,
+    portable). *dest* is ``trim_destination(source, output_dir, root)``."""
+    try:
+        rel = dest.relative_to(output_dir).as_posix()
+    except ValueError:
+        rel = dest.name
+    return cache_dir / "trim" / f"{rel}.json"
+
+
+def _trim_cache_lookup(
+    cache_dir: Path, source: Path, dest: Path, output_dir: Path
+) -> "TrimResult | None":
+    marker = _trim_marker(cache_dir, dest, output_dir)
+    # Any unreadable/malformed marker is a cache MISS, never a hard failure: the
+    # cache only accelerates the header-read decision, so a corrupted / manually
+    # edited / future-schema-bad payload must fall through to the real trim.
+    try:
+        data = json.loads(marker.read_text())
+        if not isinstance(data, dict) or data.get("fp") != _trim_fingerprint(source):
+            return None
+        if data.get("referenced"):
+            # Complete file, unchanged — reference the original, no header read.
+            return TrimResult(source, "referenced", 0, int(data.get("record_size", 0)))
+        # Previously trimmed — reuse the existing trimmed output only if it is
+        # still present AND the right size. The size check preserves the original
+        # guard against a truncated/corrupted/externally-replaced trimmed output
+        # (the source fingerprint matched, but the *output* could have moved).
+        if dest.stat().st_size == data.get("dest_size"):
+            return TrimResult(dest, "skipped", 0, 0)
+    except (OSError, ValueError, TypeError):
+        return None
+    return None
+
+
+def _trim_cache_store(
+    cache_dir: Path,
+    source: Path,
+    dest: Path,
+    output_dir: Path,
+    result: "TrimResult",
+    fp: dict | None,
+) -> None:
+    # ``fp`` is the source fingerprint snapshot taken BEFORE the trim read (see
+    # trim_p_file). Re-stat'ing the source here instead would fold in any records
+    # appended during the trim (live acquisition / an rsync completing mid-trim),
+    # so a later run would match the grown source against a short trimmed output
+    # and silently drop the appended records.
+    if fp is None:
+        return
+    marker = _trim_marker(cache_dir, dest, output_dir)
+    payload = {
+        "fp": fp,
+        "referenced": result.action == "referenced",
+        "record_size": result.record_size,
+    }
+    if result.action != "referenced":
+        # Record the trimmed output's size so a later run can verify it wasn't
+        # truncated/replaced before reusing it (see _trim_cache_lookup).
+        try:
+            payload["dest_size"] = dest.stat().st_size
+        except OSError:
+            return  # can't verify the output later -> don't cache it
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        tmp = marker.with_name(f"{marker.name}.{os.getpid()}.tmp")
+        tmp.write_text(json.dumps(payload))
+        os.replace(tmp, marker)
+    except OSError:
+        pass  # caching is best-effort; never fail a trim over a marker write
+
+
+def trim_p_file(
+    source: Path,
+    output_dir: Path,
+    root: Path | str | None = None,
+    *,
+    force: bool = False,
+    cache_dir: Path | None = None,
+) -> TrimResult:
+    """Trim an incomplete final record from a .p file, or reference it in place.
+
+    Complete files are *not* copied: the original is used in place
+    (``action="referenced"``) so the trim directory only ever holds files
+    that were genuinely truncated. This avoids duplicating large raw files
+    and needs no filesystem-specific support (hard/soft links, reflinks),
+    so it works identically on local disks, SMB/network mounts, and Windows.
+
+    Parameters
+    ----------
+    source : Path
+        Path to the original .p file.
+    output_dir : Path
+        Directory for any trimmed output file. Untouched for complete files.
+    root : Path, optional
+        Source root used to preserve relative paths under *output_dir*.
+    force : bool, keyword-only, default False
+        Re-trim even when an up-to-date trimmed output already exists. By
+        default an existing trimmed file at least as new as *source* is
+        reused (``action="skipped"``).
+
+    Returns
+    -------
+    TrimResult
+        See :class:`TrimResult`. ``dest`` is the original source for
+        ``"referenced"`` files and the trim-directory path otherwise.
+
+    Notes
+    -----
+    Skip guard (trimmed files only): the header is read every run, and a
+    trimmed output is reused only when its size equals the freshly-computed
+    trimmed size AND ``dest_mtime >= source_mtime`` (the trim-write path
+    stamps a "now" mtime newer than the older source). A source modified
+    after its trimmed output (newer mtime), repaired to completeness, or
+    given a changed header geometry therefore re-trims/re-references rather
+    than reusing a stale truncated copy. Complete files write nothing — they
+    are re-referenced each run at the cost of a single 128-byte header read.
+    """
+    dest = trim_destination(source, output_dir, root=root)
+
+    # Snapshot the source fingerprint BEFORE any read, so a source that grows
+    # during the trim (appended records) fails the fingerprint match on the next
+    # run and is re-trimmed, rather than matching against a short trimmed copy.
+    source_fp = _trim_fingerprint(source)
+
+    # Incremental skip: an unchanged source (fingerprint match) reuses last
+    # run's decision from a single stat — no per-file header read/open, which is
+    # what costs minutes over a slow mount. force_trim re-reads.
+    if not force and cache_dir is not None:
+        cached = _trim_cache_lookup(cache_dir, source, dest, output_dir)
+        if cached is not None:
+            return cached
+
+    def _finish(result: TrimResult) -> TrimResult:
+        if cache_dir is not None:
+            _trim_cache_store(cache_dir, source, dest, output_dir, result, source_fp)
+        return result
+
+    # Read the source header first (the same 128-byte read the 'referenced'
+    # path already pays) so the skip decision is content-aware rather than
+    # mtime-only. A previously-incomplete source that was later repaired (now
+    # complete, or with changed header geometry) but carries an equal/older
+    # mtime than the stale trimmed output must NOT be skipped.
+    with open(source, "rb") as f:
+        raw_hdr = f.read(HEADER_BYTES)
+        if len(raw_hdr) < HEADER_BYTES:
+            raise ValueError(f"{source.name}: file too small for header")
+
+        endian = _detect_endian(raw_hdr, source)
+        fmt = f"{endian}{HEADER_WORDS}H"
+        words = struct.unpack(fmt, raw_hdr)
+        header = {name: words[idx] for name, idx in _H.items()}
+
+        header_size = header["header_size"]
+        config_size = header["config_size"]
+        record_size = header["record_size"]
+
+        first_record_size = header_size + config_size
+
+        f.seek(0, 2)
+        file_size = f.tell()
+
+    data_bytes = file_size - first_record_size
+    if data_bytes < 0:
+        raise ValueError(f"{source.name}: file smaller than first record")
+
+    if record_size <= 0:
+        raise ValueError(f"{source.name}: invalid record_size={record_size}")
+
+    remainder = data_bytes % record_size
+    if remainder == 0:
+        # Complete file — reference the original in place, no copy. Reached
+        # also when a once-incomplete source has since been completed, so its
+        # stale trimmed output is deliberately not reused.
+        return _finish(TrimResult(source, "referenced", 0, record_size))
+
+    # Trim the fractional final record into the trim directory.
+    n_complete = data_bytes // record_size
+    trimmed_size = first_record_size + n_complete * record_size
+
+    # Skip-if-up-to-date: a prior run wrote this exact trimmed output and the
+    # source is unchanged. Require the dest SIZE to equal the freshly-computed
+    # trimmed size (so a repaired or geometry-changed source re-trims rather
+    # than reusing a stale truncated copy) on top of the nanosecond-mtime
+    # guard. The trim-write path stamps a "now" mtime, so dest_mtime >=
+    # source_mtime holds for an unchanged source.
+    if (
+        not force
+        and dest.exists()
+        and dest.stat().st_size == trimmed_size
+        and dest.stat().st_mtime_ns >= source.stat().st_mtime_ns
+    ):
+        return _finish(TrimResult(dest, "skipped", 0, 0))
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # Write to a temp file then atomically replace. If the dest resolves to the
+    # source (files already under <root>/trimmed/, or a basename collision),
+    # opening dest "wb" directly would truncate the source to 0 bytes BEFORE the
+    # read — destroying it. A separate temp fd + os.replace keeps the source
+    # intact until the atomic swap.
+    fd, tmp = tempfile.mkstemp(dir=str(dest.parent), prefix=".trim-", suffix=".tmp")
+    try:
+        with open(source, "rb") as src_f, os.fdopen(fd, "wb") as dst_f:
+            remaining = trimmed_size
+            while remaining > 0:
+                chunk = src_f.read(min(remaining, 1 << 20))
+                if not chunk:
+                    break
+                dst_f.write(chunk)
+                remaining -= len(chunk)
+        os.replace(tmp, dest)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+    return _finish(TrimResult(dest, "trimmed", remainder, record_size))

odas_tpw/processing/__init__.py

@@ -0,0 +1,62 @@
+# May-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Instrument-agnostic profile-level processing.
+
+Operates on raw numpy arrays (and a thin layer of xarray for
+mk_epsilon_mean) — no PFile, no NetCDF I/O, no perturb-specific config.
+Suitable for any vertical profiler whose pipeline can hand over the
+right arrays.
+
+- :func:`top_trim.compute_trim_depth` — depth where shear / acceleration
+  variance settles below a quantile threshold (prop-wash exit).
+- :func:`bottom.detect_bottom_crash` — depth where vibration spikes near
+  the deepest bin (seafloor impact).
+- :func:`ct_align.ct_align` — cross-correlate diff(T) vs diff(C) and
+  shift C by the median lag across profiles.
+- :func:`epsilon_combine.mk_epsilon_mean` — Lueck (2022) iterative 95% CI
+  geometric mean of multi-probe dissipation estimates.
+- :func:`chi_combine.mk_chi_mean` — same iterative 95% CI machinery for
+  multi-probe thermal-variance dissipation chi.
+- :func:`mixing.window_stratification` / :func:`mixing.mixing_coefficients`
+  — background N² and dT/dz per dissipation window, and the derived
+  mixing quantities K_T (Osborn-Cox), Gamma (Oakey), K_rho (Osborn).
+- :func:`thorpe.window_thorpe` / :func:`thorpe.patch_n2` — per-window
+  Thorpe displacements/scale L_T and the overturn-weighted "patch"
+  stratification (Smyth et al. 2001), plus Ozmidov/R_OT/Re_b/Cox helpers.
+"""
+
+from odas_tpw.processing.bottom import detect_bottom_crash
+from odas_tpw.processing.chi_combine import mk_chi_mean
+from odas_tpw.processing.ct_align import ct_align
+from odas_tpw.processing.epsilon_combine import mk_epsilon_mean
+from odas_tpw.processing.mixing import (
+    mixing_coefficients,
+    pair_nearest,
+    window_stratification,
+)
+from odas_tpw.processing.thorpe import (
+    cox_number,
+    ozmidov,
+    patch_n2,
+    r_ot,
+    reynolds_buoyancy,
+    window_thorpe,
+)
+from odas_tpw.processing.top_trim import compute_trim_depth, compute_trim_depths
+
+__all__ = [
+    "compute_trim_depth",
+    "compute_trim_depths",
+    "cox_number",
+    "ct_align",
+    "detect_bottom_crash",
+    "mixing_coefficients",
+    "mk_chi_mean",
+    "mk_epsilon_mean",
+    "ozmidov",
+    "pair_nearest",
+    "patch_n2",
+    "r_ot",
+    "reynolds_buoyancy",
+    "window_stratification",
+    "window_thorpe",
+]

odas_tpw/processing/bottom.py

@@ -0,0 +1,215 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Bottom-crash detection — find seafloor impact from a vibration signal.
+
+Caller supplies any number of fast-rate vibration channels as a dict
+(e.g. ``{"Ax": …, "Ay": …}`` for two-axis accel, or just
+``{"vibration": …}`` for a pre-computed RMS). The algorithm forms the
+elementwise root-sum-square magnitude across all supplied channels, bins
+its std by depth, and flags the deepest bin whose std exceeds
+``vibration_factor`` times the median — but only within a few bins of the
+deepest sampled depth, since a real seafloor strike is at the cast bottom.
+A supra-threshold spike far above the bottom is mid-column vibration, not a
+crash, and is reported via a warning rather than truncating the cast.
+
+Reference: Code/bottom_crash_profiles.m (currently a stub in Matlab)
+"""
+
+import warnings
+from collections.abc import Mapping
+
+import numpy as np
+import numpy.typing as npt
+
+
+def detect_bottom_crash(
+    depth_fast: npt.ArrayLike,
+    vibration_channels: Mapping[str, npt.ArrayLike],
+    fs: float,
+    *,
+    depth_window: float = 4.0,
+    depth_minimum: float = 10.0,
+    speed_factor: float = 0.3,
+    median_factor: float = 1.0,
+    vibration_frequency: int = 16,
+    vibration_factor: float = 4.0,
+    proximity_bins: int = 2,
+) -> float | None:
+    """Detect bottom crash from a set of vibration channels.
+
+    Parameters
+    ----------
+    depth_fast : array_like
+        Depth array (positive downward, fast rate) [m].
+    vibration_channels : mapping of name -> 1-D array
+        Fast-rate vibration / motion channels. Two-axis accel
+        ``{"Ax": …, "Ay": …}`` reproduces the historical 2-axis
+        magnitude. A single pre-aggregated channel
+        (e.g. ``{"vibration_rms": rms}``) is also fine. All arrays
+        must match ``depth_fast`` in length.
+    fs : float
+        Fast sampling rate [Hz].  Currently UNUSED — accepted for
+        backward compatibility; the algorithm operates on depth bins,
+        not time.
+    depth_window : float
+        Depth window for variance computation [m].
+    depth_minimum : float
+        Minimum depth to start searching [m].
+    speed_factor : float
+        Currently UNUSED — accepted for backward compatibility (the
+        speed-drop confirmation from the original MATLAB design is not
+        implemented).  Tuning it has no effect.
+    median_factor : float
+        Currently UNUSED — accepted for backward compatibility.
+        Tuning it has no effect.
+    vibration_frequency : int
+        Currently UNUSED — accepted for backward compatibility.
+        Tuning it has no effect.
+    vibration_factor : float
+        Vibration std dev acceptance factor: the deepest bin whose
+        magnitude std exceeds ``vibration_factor`` times the median
+        marks the crash.
+    proximity_bins : int
+        A crash is accepted only in a bin within ``proximity_bins`` of the
+        deepest sampled bin — a real seafloor strike is at the cast bottom,
+        so a supra-threshold spike higher up is mid-column vibration, not a
+        crash (audit r1-3). Must be >= 0; at the default ``depth_window=4``
+        m, ``proximity_bins=2`` accepts a strike within ~8 m of the deepest
+        sample. This is the geometric stand-in for the unimplemented
+        ``speed_factor`` fall-rate-collapse confirmation.
+
+    Returns
+    -------
+    float or None
+        Bottom depth [m], or None if no crash detected.
+
+    Notes
+    -----
+    The reported depth is the *mean* depth of the samples in the flagged
+    ``depth_window``-wide bin. When the crash onset falls early in that bin the
+    mean lies below the onset, so up to roughly half a bin width (~``depth_window
+    / 2``) of contaminated data can remain *above* the reported depth and be left
+    un-trimmed. This is a fundamental limit of the bin resolution; size
+    ``depth_window`` accordingly if tighter bottom trimming is required.
+    """
+    # speed_factor / median_factor / vibration_frequency are accepted for
+    # backward compatibility but are not yet wired into the algorithm (see the
+    # parameter docs above). They are kept as valid config keys — strict
+    # validate_config would reject a YAML that still lists them — but warn if a
+    # caller tunes one off its default so it is no longer a SILENT no-op.
+    # (#104 U4-F2.)
+    _unwired = {
+        "speed_factor": (speed_factor, 0.3),
+        "median_factor": (median_factor, 1.0),
+        "vibration_frequency": (vibration_frequency, 16),
+    }
+    _tuned = [name for name, (val, default) in _unwired.items() if val != default]
+    if _tuned:
+        warnings.warn(
+            "detect_bottom_crash: parameter(s) "
+            f"{', '.join(_tuned)} are accepted but not yet implemented; the "
+            "supplied value(s) have no effect on bottom detection",
+            stacklevel=2,
+        )
+
+    depth = np.asarray(depth_fast, dtype=np.float64)
+
+    if not vibration_channels:
+        return None
+
+    # Elementwise root-sum-square across all supplied channels. For two-axis
+    # ``{Ax, Ay}`` this matches the previous ``sqrt(Ax**2 + Ay**2)`` exactly.
+    mag_sq: np.ndarray | None = None
+    for arr in vibration_channels.values():
+        a = np.asarray(arr, dtype=np.float64)
+        if len(a) != len(depth):
+            return None
+        sq = a * a
+        mag_sq = sq if mag_sq is None else mag_sq + sq
+    assert mag_sq is not None  # unreachable: guarded by `if not vibration_channels`
+    accel_mag = np.sqrt(mag_sq)
+
+    # An all-NaN depth segment makes nanmax NaN; np.arange(..., NaN, ...) below
+    # then raises. Bail out cleanly instead of crashing the profile.
+    #
+    # Audit fix: short-circuit BEFORE nanmax on an all-NaN depth. np.errstate
+    # only governs IEEE FP flags (invalid/divide/...), NOT numpy's Python-level
+    # "All-NaN slice encountered" RuntimeWarning — so the old errstate guard let
+    # that warning escape (spurious log noise; promotable to an error by callers
+    # that filter warnings). Guarding on np.isfinite up front avoids the warning
+    # and the NaN max_depth entirely.
+    if not np.any(np.isfinite(depth)):
+        return None
+    max_depth = np.nanmax(depth)
+    if not np.isfinite(max_depth) or max_depth < depth_minimum:
+        return None
+
+    # Bin acceleration variance by depth
+    bin_size = depth_window
+    bins = np.arange(depth_minimum, max_depth + bin_size, bin_size)
+    if len(bins) < 2:
+        return None
+
+    n_bins = len(bins) - 1
+    idx = np.searchsorted(bins, depth, side="right") - 1
+    in_range = (idx >= 0) & (idx < n_bins) & np.isfinite(accel_mag)
+    idx_v = idx[in_range]
+    vals_v = accel_mag[in_range]
+    counts = np.bincount(idx_v, minlength=n_bins)
+    sums = np.bincount(idx_v, weights=vals_v, minlength=n_bins)
+    sums_sq = np.bincount(idx_v, weights=vals_v * vals_v, minlength=n_bins)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        means = np.where(counts > 0, sums / np.maximum(counts, 1), 0.0)
+        var = sums_sq / np.maximum(counts, 1) - means * means
+        var = np.maximum(var, 0.0)
+        bin_std = np.where(counts > 1, np.sqrt(var), np.nan)
+
+    valid = np.isfinite(bin_std)
+    if np.sum(valid) < 3:
+        return None
+
+    med_std = np.nanmedian(bin_std[valid])
+    threshold = med_std * vibration_factor
+
+    # A real bottom crash is at the seafloor — the deepest point of the cast.
+    # Restrict crash candidates to the near-bottom zone (within `proximity_bins`
+    # of the deepest sampled bin). A supra-threshold spike far above the bottom
+    # is mid-column vibration (a cable transient or a turbulence patch), not a
+    # crash; truncating the cast there would silently delete valid deep data
+    # (audit r1-3). This proximity gate is the geometric stand-in for the
+    # unimplemented MATLAB speed-drop (`speed_factor`) confirmation.
+    valid_idx = np.flatnonzero(valid)
+    deepest_valid = int(valid_idx[-1])
+    zone_top = deepest_valid - max(proximity_bins, 0)
+
+    def _bin_mean_depth(i: int) -> float:
+        # MEAN depth of the samples in bin i, not its geometric center: the
+        # deepest bin's right edge overhangs nanmax(depth) by up to one bin
+        # width, so its center can lie BELOW the deepest real sample and the
+        # caller's `P >= bottom_depth` would match nothing. The sample mean is
+        # guaranteed to lie within the bin's observed depths (robust to the
+        # fast/slow rate mismatch against the slow pressure the caller trims).
+        return float(np.nanmean(depth[in_range & (idx == i)]))
+
+    # Search the near-bottom zone from the deepest bin upward for the spike.
+    for i in range(deepest_valid, zone_top - 1, -1):
+        if valid[i] and bin_std[i] > threshold:
+            return _bin_mean_depth(i)
+
+    # No crash at the bottom. Surface any supra-threshold spike higher up —
+    # what the pre-fix deepest-upward scan would have mis-reported as a crash —
+    # so genuine mid-column contamination is visible rather than silently
+    # ignored, without truncating the (valid) deep cast.
+    for i in range(zone_top - 1, -1, -1):
+        if valid[i] and bin_std[i] > threshold:
+            spike_depth = _bin_mean_depth(i)
+            deepest_depth = float(np.nanmax(depth[in_range]))
+            warnings.warn(
+                f"detect_bottom_crash: vibration spike at ~{spike_depth:.1f} m "
+                f"is {deepest_depth - spike_depth:.1f} m above the deepest "
+                "sample; treated as mid-column contamination, not a bottom "
+                "crash (cast not truncated)",
+                stacklevel=2,
+            )
+            break
+
+    return None