microstructure-tpw 0.3.0__py3-none-any.whl

odas_tpw/rsi/shear_noise.py

@@ -0,0 +1,128 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Electronics noise model for shear probe channels.
+
+Port of noise_shearchannel.m from the ODAS MATLAB library (v4.5.1).
+
+The shear probe circuit consists of:
+  1. Charge-transfer amplifier (LTC6240, R1=1 GΩ, C1=1.5 nF)
+  2. Differentiator (R2, C2, R3, C3)
+  3. Anti-aliasing filter (two cascaded 4th-order Butterworth)
+  4. ADC sampler
+
+References
+----------
+RSI Technical Note 042: Noise in Shear Measurements.
+"""
+
+import numpy as np
+import numpy.typing as npt
+
+
+def noise_shearchannel(
+    F: npt.ArrayLike,
+    *,
+    R1: float = 1e9,
+    C1: float = 1.5e-9,
+    R2: float = 499,
+    C2: float = 0.94e-6,
+    R3: float = 1e6,
+    C3: float = 470e-12,
+    CP: float = 0,
+    E_1: float = 9e-9,
+    fc: float = 50,
+    I_1: float = 0.56e-15,
+    f_AA: float = 110,
+    fs: float = 512,
+    VFS: float = 4.096,
+    Bits: int = 16,
+    gamma_RSI: float = 2.5,
+    T_K: float = 295,
+    K_B: float = 1.382e-23,
+) -> np.ndarray:
+    """Compute the output noise spectrum of the shear probe channel.
+
+    Parameters
+    ----------
+    F : array_like
+        Frequency vector [Hz].
+    R1 : float
+        First-stage feedback resistance [Ohm]. Default: 1 GΩ.
+    C1 : float
+        First-stage charge-transfer capacitance [F]. Default: 1.5 nF.
+    R2 : float
+        Differentiator input resistance [Ohm]. Default: 499 Ω.
+    C2 : float
+        Differentiator capacitance [F]. Default: 0.94 µF.
+    R3 : float
+        Differentiator feedback resistance [Ohm]. Default: 1 MΩ.
+    C3 : float
+        Differentiator feedback capacitance [F]. Default: 470 pF.
+    CP : float
+        Probe capacitance [F]. Default: 0 (no probe). Set to ~1 nF with probe.
+    E_1 : float
+        First-stage amplifier voltage noise [V/√Hz]. Default: 9e-9.
+    fc : float
+        First-stage flicker noise knee frequency [Hz]. Default: 50.
+    I_1 : float
+        First-stage amplifier current noise [A/√Hz]. Default: 0.56e-15.
+    f_AA : float
+        Anti-aliasing filter cutoff [Hz]. Default: 110.
+    fs : float
+        Sampling rate [Hz]. Default: 512.
+    VFS : float
+        ADC full-scale voltage [V]. Default: 4.096.
+    Bits : int
+        ADC resolution [bits]. Default: 16.
+    gamma_RSI : float
+        ADC noise factor (RSI sampler excess). Default: 2.5.
+    T_K : float
+        Operating temperature [K]. Default: 295.
+    K_B : float
+        Boltzmann constant [J/K]. Default: 1.382e-23.
+
+    Returns
+    -------
+    noise : ndarray
+        Noise spectrum [counts² / Hz].
+    """
+    F = np.asarray(F, dtype=np.float64)
+    omega = 2 * np.pi * F
+
+    delta_s = VFS / 2**Bits  # ADC step size
+    fN = fs / 2  # Nyquist frequency
+
+    # --- Stage 1: Charge-transfer amplifier (LTC6240) ---
+    # Voltage noise (1/f model from spec sheet)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        V_V1 = E_1**2 * (fc / F) * np.sqrt(1 + (F / fc) ** 2)
+    V_V1 = np.where(np.isfinite(V_V1), V_V1, 0.0)
+
+    # Current noise (frequency-independent up to 300 Hz)
+    V_I1 = I_1**2 * R1**2 / (1 + (omega * R1 * C1) ** 2)
+
+    # Johnson (thermal) noise from R1
+    V_R1 = 4 * K_B * T_K * R1 / (1 + (omega * R1 * C1) ** 2)
+
+    # Noise gain of first stage (includes probe capacitance)
+    G_1 = (1 + (omega * R1 * (CP + C1)) ** 2) / (1 + (omega * R1 * C1) ** 2)
+
+    Noise_1 = G_1 * (V_V1 + V_I1) + V_R1
+
+    # --- Stage 2: Differentiator ---
+    G_2 = (omega * R3 * C2) ** 2 / (1 + (omega * R2 * C2) ** 2) / (1 + (omega * R3 * C3) ** 2)
+
+    # Note: MATLAB uses (Noise_1 + V_V1) not (Noise_1 + V_V2) —
+    # same first-stage voltage noise applied as second-stage input noise
+    Noise_2 = (Noise_1 + V_V1) * G_2
+
+    # --- Anti-aliasing: two cascaded 4th-order Butterworth ---
+    G_AA = 1.0 / (1 + (F / f_AA) ** 8) ** 2
+    Noise_3 = Noise_2 * G_AA
+
+    # --- Sampling: ADC quantization noise ---
+    Noise_4 = Noise_3 + gamma_RSI * delta_s**2 / (12 * fN)
+
+    # Convert to counts²/Hz
+    noise_counts = Noise_4 / delta_s**2
+
+    return np.asarray(noise_counts)

odas_tpw/rsi/speed.py

@@ -0,0 +1,221 @@
+# May-2026, Pat Welch, pat@mousebrains.com
+"""Configurable through-water speed computation from a loaded ``.p`` file.
+
+Shared by both the ``rsi`` and ``perturb`` pipelines (``perturb.speed``
+re-exports ``compute_speed_for_pfile``). Run *after* the ``.p`` file is loaded
+and any hotel data has been merged into ``pf.channels``, so
+``compute_speed_for_pfile`` sees the union of both sources.
+
+Methods
+-------
+``"pressure"``
+    ODAS-style smoothed ``|dP/dt|`` at slow rate, interpolated and
+    Butterworth-smoothed onto fast rate. This is the historical default
+    (correct for VMP, returns vertical speed for a glider).
+
+``"em"``
+    Use the ``U_EM`` channel from the ``.p`` file directly — the
+    MicroRider's electromagnetic flowmeter measurement of along-axis
+    flow. Errors out if ``U_EM`` is missing.
+
+``"flight"``
+    Construct an inviscid flight-model along-axis speed from the MR's
+    own pressure and inclinometers:
+
+        U_along = |W| / sin(|pitch| - aoa)
+
+    where ``aoa`` is the angle of attack (``aoa_deg``, default 3 deg
+    matching ODAS Slocum trim). The pitch axis is auto-picked from the
+    inclinometer axis with the larger swing -- Slocum mountings some-
+    times have ``Incl_X`` carrying pitch, sometimes ``Incl_Y``.
+
+``"constant"``
+    Use the scalar in ``speed.value`` for every fast-rate sample.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import numpy as np
+
+
+def compute_speed_for_pfile(
+    pf: Any,
+    speed_cfg: dict | None,
+    vehicle: str | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return (speed_fast, W_slow) from configured method, in m/s and dbar/s.
+
+    Parameters
+    ----------
+    pf : PFile
+        Has ``channels`` (already merged with hotel), ``t_fast``,
+        ``t_slow``, ``fs_fast``, ``fs_slow``.
+    speed_cfg : dict
+        Merged ``speed:`` section from the perturb config.
+    vehicle : str | None
+        Vehicle string from instrument_info (``"slocum_glider"``,
+        ``"vmp"`` etc.). Auto-resolves ``tau`` and, for the ``pressure``
+        method, triggers a bias warning on glide/horizontal platforms
+        (where ``|dP/dt|`` is not the through-water speed).
+
+    Returns
+    -------
+    speed_fast : (n_fast,) float64, m/s, >= ``speed_cutout``.
+                 For the pressure method this is numerically |dP/dt| in
+                 dbar/s treated as m/s (the ODAS convention). 1 dbar is
+                 ~0.99 m (equivalently 1 m ~ 1.006-1.009 dbar depending on
+                 latitude/density), so |dP/dt| in dbar/s slightly OVER-states
+                 the true speed in m/s, by <1%. Through epsilon's strong
+                 inverse speed leverage (~U^-4 in the shear conversion and
+                 wavenumber transform) that biases the reported epsilon
+                 slightly LOW.
+    W_slow     : (n_slow,) float64, dbar/s. Always the smoothed |dP/dt|
+                 -- independent of method, useful for QC/binning.
+    """
+    from odas_tpw.rsi.vehicle import resolve_direction, resolve_tau
+    from odas_tpw.scor160.profile import compute_speed_fast as _ode_speed
+    from odas_tpw.scor160.profile import smooth_fall_rate
+
+    cfg = speed_cfg or {}
+    method = cfg.get("method", "pressure")
+    speed_cutout = float(cfg.get("speed_cutout", 0.05))
+    tau = float(cfg.get("tau") or resolve_tau(vehicle or ""))
+
+    P_slow = np.asarray(pf.channels["P"], dtype=np.float64)
+    fs_slow = float(pf.fs_slow)
+    fs_fast = float(pf.fs_fast)
+    t_fast = np.asarray(pf.t_fast, dtype=np.float64)
+    t_slow = np.asarray(pf.t_slow, dtype=np.float64)
+
+    # W_slow always: smoothed |dP/dt|, regardless of method.
+    W_slow = smooth_fall_rate(P_slow, fs_slow, tau=tau)
+
+    if method == "pressure":
+        # For a glider / horizontal platform, |dP/dt| is the VERTICAL speed and
+        # underestimates the along-path flow past the sensors; epsilon has ~U^4
+        # leverage, so this strongly biases epsilon high. The rsi path warns
+        # about this in helpers.prepare_profiles, but perturb precomputes speed
+        # here and so never reaches that warning — emit the equivalent here so
+        # the perturb path is not silent (audit r2-3). VMP (down/up) is unaffected.
+        direction = resolve_direction("auto", vehicle or "")
+        if direction in ("glide", "horizontal"):
+            warnings.warn(
+                f"Vehicle direction '{direction}' but speed.method='pressure' "
+                "computes speed from |dP/dt| (vertical); set speed.method="
+                "'flight' (glider) or 'em' (horizontal), or speed.value — "
+                "epsilon scales as ~U^4 and will be strongly biased",
+                stacklevel=2,
+            )
+        speed_fast, _ = _ode_speed(
+            P_slow, t_fast, t_slow, fs_fast, fs_slow,
+            tau=tau, speed_min=speed_cutout,
+        )
+        return speed_fast, W_slow
+
+    if method == "constant":
+        v = cfg.get("value")
+        if v is None:
+            raise ValueError("speed.method='constant' but speed.value is null")
+        speed_fast = np.full(len(t_fast), max(abs(float(v)), speed_cutout))
+        return speed_fast, W_slow
+
+    if method == "em":
+        if "U_EM" not in pf.channels:
+            raise ValueError(
+                "speed.method='em' but channel U_EM is missing from the "
+                ".p file. Use 'flight' or 'pressure' instead."
+            )
+        U_em_slow = np.abs(np.asarray(pf.channels["U_EM"], dtype=np.float64))
+        return _slow_to_fast(U_em_slow, t_fast, t_slow, fs_fast, fs_slow,
+                             tau=tau, speed_min=speed_cutout), W_slow
+
+    if method == "flight":
+        aoa_deg = float(cfg.get("aoa_deg", 3.0))
+        min_pitch_deg = float(cfg.get("min_pitch_deg", 5.0))
+        aq = cfg.get("amplitude_quantile") or (1.0, 99.0)
+        speed_slow = _flight_model_slow(
+            W_slow, pf, aoa_deg=aoa_deg, min_pitch_deg=min_pitch_deg,
+            amplitude_quantile=(float(aq[0]), float(aq[1])),
+        )
+        return _slow_to_fast(speed_slow, t_fast, t_slow, fs_fast, fs_slow,
+                             tau=tau, speed_min=speed_cutout), W_slow
+
+    raise ValueError(
+        f"Unknown speed.method={method!r}. "
+        "Expected: pressure | em | flight | constant."
+    )
+
+
+def _slow_to_fast(
+    arr_slow: np.ndarray,
+    t_fast: np.ndarray,
+    t_slow: np.ndarray,
+    fs_fast: float,
+    fs_slow: float,
+    tau: float,
+    speed_min: float,
+) -> np.ndarray:
+    """Match scor160 speed pipeline: linear interp + Butterworth smoothing."""
+    from scipy.signal import butter, filtfilt
+
+    # NaN-safe interp by filling on the slow grid first.
+    finite = np.isfinite(arr_slow)
+    if not finite.any():
+        return np.full(len(t_fast), speed_min)
+    arr_slow = np.where(
+        finite, arr_slow,
+        np.interp(t_slow, t_slow[finite], arr_slow[finite]),
+    )
+    arr_fast = np.interp(t_fast, t_slow, arr_slow)
+    f_c = 0.68 / tau
+    b, a = butter(1, f_c / (fs_fast / 2.0))
+    arr_fast = np.asarray(filtfilt(b, a, arr_fast))
+    return np.asarray(np.maximum(arr_fast, speed_min), dtype=np.float64)
+
+
+def _flight_model_slow(
+    W_slow: np.ndarray,
+    pf: Any,
+    aoa_deg: float,
+    min_pitch_deg: float,
+    amplitude_quantile: tuple[float, float] = (1.0, 99.0),
+) -> np.ndarray:
+    """U_along = |W| / sin(glide angle), at slow rate.
+
+    Steady-flight kinematics (Merckelbach et al. 2010,
+    doi:10.1175/2009JTECHO710.1): W = U * sin(gamma) with glide-path
+    angle gamma = |pitch| - angle of attack, so U = |W| / sin(gamma).
+    Roll does not enter the along-path relation (it rotates the body
+    about the flight axis without changing the vertical velocity
+    component); an earlier version multiplied by cos(roll), which
+    inflated U by 1/cos(roll).
+
+    Pitch axis auto-picked from whichever of ``Incl_X``/``Incl_Y`` has
+    the larger percentile-spread amplitude (default 99-1) -- Slocum
+    mountings vary, and percentiles keep brief outlier spikes from
+    masquerading as the high-amplitude flight axis.
+    """
+    iX = np.asarray(pf.channels.get("Incl_X"), dtype=np.float64) \
+        if "Incl_X" in pf.channels else None
+    iY = np.asarray(pf.channels.get("Incl_Y"), dtype=np.float64) \
+        if "Incl_Y" in pf.channels else None
+    if iX is None or iY is None:
+        raise ValueError(
+            "speed.method='flight' needs Incl_X and Incl_Y channels in the "
+            ".p file. Use 'pressure' or 'em' instead."
+        )
+    lo_q, hi_q = float(amplitude_quantile[0]), float(amplitude_quantile[1])
+    iX_rng = float(np.nanpercentile(iX, hi_q) - np.nanpercentile(iX, lo_q))
+    iY_rng = float(np.nanpercentile(iY, hi_q) - np.nanpercentile(iY, lo_q))
+    pitch_deg = iX if iX_rng >= iY_rng else iY
+
+    pitch = np.deg2rad(pitch_deg)
+    aoa = np.deg2rad(aoa_deg)
+    eff = np.maximum(np.abs(pitch) - aoa, 0.0)
+    sin_path = np.sin(eff)
+    sin_floor = np.sin(np.deg2rad(min_pitch_deg))
+    sin_path = np.where(sin_path > sin_floor, sin_path, np.nan)
+    return np.asarray(np.abs(W_slow) / sin_path, dtype=np.float64)

odas_tpw/rsi/vehicle.py

@@ -0,0 +1,74 @@
+# Mar-2026, Claude and Pat Welch, pat@mousebrains.com
+"""Vehicle attributes for RSI instruments.
+
+Maps vehicle types to their default profile direction and smoothing
+time constant (tau), matching ODAS ``default_vehicle_attributes.ini``.
+"""
+
+from __future__ import annotations
+
+# (direction, tau) per vehicle — matches ODAS default_vehicle_attributes.ini
+VEHICLE_ATTRIBUTES: dict[str, tuple[str, float]] = {
+    "vmp": ("down", 1.5),
+    "rvmp": ("up", 1.5),
+    "xmp": ("down", 1.5),
+    "argo_float": ("up", 60.0),
+    "slocum_glider": ("glide", 3.0),
+    "sea_glider": ("glide", 5.0),
+    "sea_explorer": ("glide", 3.0),
+    "auv": ("horizontal", 10.0),
+    "auv_emc": ("horizontal", 10.0),
+    "nemo": ("horizontal", 60.0),
+    "micro_squid": ("horizontal", 1.5),
+    "stand": ("horizontal", 1.5),
+}
+
+DEFAULT_DIRECTION = "down"
+DEFAULT_TAU = 1.5
+
+_EXPLICIT_DIRECTIONS = {"up", "down", "glide", "horizontal"}
+
+
+def resolve_direction(direction: str, vehicle: str) -> str:
+    """Resolve profile direction from user setting and vehicle type.
+
+    Parameters
+    ----------
+    direction : str
+        User-specified direction.  ``"auto"`` looks up *vehicle* in
+        :data:`VEHICLE_ATTRIBUTES`; any explicit value (``"up"``,
+        ``"down"``, ``"glide"``, ``"horizontal"``) passes through unchanged.
+    vehicle : str
+        Vehicle identifier from the instrument config (lower-case).
+
+    Returns
+    -------
+    str
+        Resolved direction.
+    """
+    if direction.lower() in _EXPLICIT_DIRECTIONS:
+        return direction.lower()
+    # "auto" or unrecognised → look up vehicle
+    attrs = VEHICLE_ATTRIBUTES.get(vehicle.lower())
+    if attrs is not None:
+        return attrs[0]
+    return DEFAULT_DIRECTION
+
+
+def resolve_tau(vehicle: str) -> float:
+    """Return the smoothing time constant for a vehicle.
+
+    Parameters
+    ----------
+    vehicle : str
+        Vehicle identifier (lower-case).
+
+    Returns
+    -------
+    float
+        Tau [s].
+    """
+    attrs = VEHICLE_ATTRIBUTES.get(vehicle.lower())
+    if attrs is not None:
+        return attrs[1]
+    return DEFAULT_TAU