das-mccc 0.2.0__py3-none-any.whl

das_mccc-0.2.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: das-mccc
+Version: 0.2.0
+Summary: Iterative network MCCC refinement of DAS arrival curves with absolute anchoring and Ricker polarity QC
+Author-email: Jaewoo Kim <jk103@rice.edu>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Jaewoo-Kim-Rice/das-mccc
+Project-URL: Algorithm, https://github.com/Jaewoo-Kim-Rice/das-mccc/blob/main/docs/algorithm.md
+Keywords: DAS,distributed acoustic sensing,microseismic,cross-correlation,phase picking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: numba
+Requires-Dist: numba; extra == "numba"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# das-mccc
+
+Refine a DAS arrival curve with an iterative network multi-channel cross-correlation
+(MCCC), anchor its absolute level on the aligned stack, and return per-channel polarity
+and quality measures. Arrays in, arrays out: no site, file or path concepts.
+
+The core is the refiner of [das-focmec](https://github.com/Jaewoo-Kim-Rice/das-focmec)
+(`das_focmec.processing.mccc_core.ultra_mccc_iterative`), extracted with its history so it
+can be used by any picker. Started from a rough curve (a VLM trace, a bracket, a
+theoretical moveout) it recovers the shape of the arrival to the precision of a human
+curve: on 24 CAPE 2025 reads the shape MAD against human picks went from 2.2 to 1.95 ms
+(P) and 4.5 to 4.15 ms (S), and a curve started on the wrong lobe went from 5.6 to 2.65 ms.
+
+## Install
+
+```
+pip install -e .            # numpy, scipy
+pip install -e '.[numba]'   # fast pairwise correlation (strongly recommended)
+pip install -e '.[dev]'     # pytest, ruff
+```
+
+Without numba the pairwise correlation runs in pure numpy: identical results, one to two
+orders of magnitude slower, and a warning is logged at import.
+
+## Use
+
+```python
+import numpy as np
+from dasmccc import refine_curve, refine_phases, DIRECT, SECONDARY
+
+# waveform: (n_channels, n_samples) float, filtered as you like
+# curve   : (n_channels,) arrival in samples, NaN where the phase is not picked
+res = refine_curve(waveform, curve, DIRECT)
+
+res.curve          # refined arrival (samples), NaN where the input was NaN
+res.curve_relative # same shape, at the initial curve's level (no anchor)
+res.anchor_offset  # samples added by the anchor rule (NaN if the rule refused)
+res.polarity       # -1 / 0 / +1 per channel
+res.snr, res.coherence, res.kept
+res.aligned, res.stack   # the aligned window and its stack, for plots
+
+# several phases of one gather, strongest first; refined phases are masked for the next and a
+# narrow tapered pre-mask (+-40 samples, 10 taper) keeps them out of the correlation
+out = refine_phases(waveform, {"S": s_curve, "P": p_curve, "SP": sp_curve})
+# several curves of one tag: any keys, plus a key -> tag map
+out = refine_phases(waveform, {"S": s_curve, "R1": r1, "R2": r2},
+                    tags={"S": "S", "R1": "REFL", "R2": "REFL"})
+```
+
+Settings live in `RefineConfig` (everything in samples and channels). `DIRECT` is the
+das-focmec configuration for direct waves (window 200, corr_len 200, smoothness 50, four
+passes, pre-mask 100); `SECONDARY` narrows it for conversions and reflections (window
+120, corr_len 100, three passes, pre-mask 50). Both were calibrated at 1 kHz and 2 m channel
+spacing; `docs/algorithm.md` gives the conversion to other rates and spacings, what each
+knob does, and the anchoring and masking rules.
+
+## For das-focmec
+
+`dasmccc.legacy` exposes `ultra_mccc_iterative` and `diff_corr_ric` with the das-focmec
+signatures and identical results, so `das_focmec.processing.workflows` only changes its
+import line.
+
+## What it does not do
+
+* It does not re-pick. The initial curve decides which arrival and roughly which lobe is
+  refined; MCCC measures relative delays within `pair_slope` samples per channel of it.
+* The anchor moves the whole curve by one offset measured on the stack (secondary phases
+  inherit their parent's). The first-lobe rule sits about 5 ms before the human pick for P
+  and within a few ms of it for S on the CAPE 2025 fibres, with a per-fibre constant;
+  calibrate it per site against a few human picks when onsets are needed.
+* Sub-sample precision: the alignment is integer; tau is a float but the returned curve
+  inherits the integer initial alignment plus the smoothed tau.
+
+## Development
+
+```
+PYTHONPATH=src pytest -q
+ruff check src tests && ruff format --check src tests
+```

das_mccc-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+das_mccc-0.2.0.dist-info/licenses/LICENSE,sha256=sryuJWrcza8-CCtUmy0VR6_D7vK90fPOXfhE4VxpiHw,1072
+dasmccc/__init__.py,sha256=txpbzWpT2g2Qmx97HhcP3TQWlcS5InMDptJWNGYnrTQ,1051
+dasmccc/anchor.py,sha256=VrbKqi4cHaFbaH47QW9lfLCFrFEuWz0lVTAAeWSTVxA,3317
+dasmccc/core.py,sha256=S6yYlh27x14CkHJlCyAqgK4WxGGol9EjItwKHto3JJ0,8331
+dasmccc/legacy.py,sha256=U-5uQSe6_tApURflt9DGCT19xE3JXAnrHTu3o5brZc8,3642
+dasmccc/ops.py,sha256=66efQzMPLbz8EB1jAi5_O5Tp-Tdc3WVh0AXenGDvX5o,2731
+dasmccc/pipeline.py,sha256=2JruQ7CpusuMMwlRSuNt7GzbA4VxOoTA7DQvCksxf7Q,27159
+dasmccc/polarity.py,sha256=jcsZ82BVjnx5H-EIeOdN3oNoR_2zn_qzQA_4z1y1lsY,5730
+dasmccc/signal.py,sha256=KjZ70-Jo29bRVOadI2LN2TP4vL3yr1l5zxbkKfq1hac,5338
+das_mccc-0.2.0.dist-info/METADATA,sha256=CJdgKKNdntuXMnzibzyETPloaTzjWUU6knw5fhtUBUQ,4890
+das_mccc-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+das_mccc-0.2.0.dist-info/top_level.txt,sha256=abRPwUZpu0ZjfM0cQVQfjwOg5D72N4Ay-Z9DqASjBKo,8
+das_mccc-0.2.0.dist-info/RECORD,,

das_mccc-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

das_mccc-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jaewoo Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

das_mccc-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dasmccc

dasmccc/__init__.py

@@ -0,0 +1,45 @@
+"""dasmccc: iterative network MCCC refinement of DAS arrival curves.
+
+from dasmccc import refine_curve, DIRECT
+res = refine_curve(waveform, curve, DIRECT)   # arrays in, RefineResult out
+"""
+
+__version__ = "0.2.0"
+
+from .anchor import first_lobe, stack_peak
+from .core import iterate_align, mccc, pairwise_lags, partner_pairs, solve_tau
+from .pipeline import (
+    DIRECT,
+    SECONDARY,
+    NothingToRefine,
+    RefineConfig,
+    RefineResult,
+    refine_curve,
+    refine_phases,
+)
+from .polarity import PolarityConfig, PolarityResult, RickerWindows, ricker_polarity, ricker_windows
+from .signal import NUMBA_AVAILABLE
+
+__all__ = [
+    "DIRECT",
+    "__version__",
+    "NUMBA_AVAILABLE",
+    "NothingToRefine",
+    "SECONDARY",
+    "PolarityConfig",
+    "PolarityResult",
+    "RefineConfig",
+    "RefineResult",
+    "RickerWindows",
+    "first_lobe",
+    "iterate_align",
+    "mccc",
+    "pairwise_lags",
+    "partner_pairs",
+    "refine_curve",
+    "refine_phases",
+    "ricker_polarity",
+    "ricker_windows",
+    "solve_tau",
+    "stack_peak",
+]

dasmccc/anchor.py

@@ -0,0 +1,79 @@
+"""Absolute anchoring of a relatively aligned gather.
+
+Network MCCC fixes only relative delays; the level of the refined curve is whatever the
+initial curve's level was (the lobe the initial picker traced). The rules here measure one
+offset on the aligned stack so that the curve is moved to a reproducible feature of the
+wavelet. All offsets are in samples relative to ``centre`` (the alignment sample).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+
+log = logging.getLogger("dasmccc")
+
+
+def stack_peak(stack: np.ndarray, centre: int) -> float:
+    """Offset of the |stack| maximum. Reproducible on strong reads, but the peak lobe is
+    not the same lobe on every read (spread of tens of ms against human onsets)."""
+    return float(int(np.argmax(np.abs(stack))) - centre)
+
+
+def first_lobe(
+    stack: np.ndarray,
+    centre: int,
+    min_frac: float = 0.4,
+    guard: int | None = 40,
+    contiguous: bool = True,
+    window: tuple[int, int] | None = (-30, 10),
+) -> float:
+    """Offset of the centre of the first lobe of the stack.
+
+    Candidates are the local maxima of |stack|. ``window`` = (lo, hi) restricts the search to
+    ``centre + lo .. centre + hi`` (samples): the prior that the initial picker traced a lobe
+    of the arrival, so the onset lies at most one wavelet before it and hardly after it. The
+    reference amplitude is the |stack| peak inside the window. With ``contiguous`` the rule
+    walks back from that peak lobe by lobe while each lobe keeps at least ``min_frac`` of the
+    peak and returns the earliest lobe of that run (a precursor separated by a weaker lobe is
+    not the onset); without it the earliest candidate above ``min_frac`` anywhere before the
+    peak is taken (the original rule). The peak itself is returned when no earlier lobe
+    qualifies.
+
+    Tuned on 616 CAPE 2025 reads with human picks (das-phase-agent research record,
+    `docs/11_anchor_tuning.md`): window (-30, 10), contiguous, min_frac 0.4 on the
+    channel-normalised stack removed every refusal and halved the gross anchor errors
+    against the original rule (window None, contiguous False, min_frac 0.3, plain stack).
+
+    ``guard`` bounds |offset|: a larger offset is judged unreliable, a warning is logged and
+    NaN is returned so the caller keeps the relative level.
+    """
+    a = np.abs(np.asarray(stack, float))
+    n = len(a)
+    if window is None:
+        lo, hi = 0, n
+    else:
+        lo, hi = max(0, centre + int(window[0])), min(n, centre + int(window[1]) + 1)
+        if hi - lo < 3:
+            raise ValueError(f"anchor window {window} leaves no samples around centre {centre}")
+    pk = lo + int(np.argmax(a[lo:hi]))
+    ext = [i for i in range(max(1, lo), pk) if a[i] >= a[i - 1] and a[i] >= a[i + 1]]
+    first = pk
+    if contiguous:
+        for i in reversed(ext):
+            if a[i] >= min_frac * a[pk]:
+                first = i
+            else:
+                break
+    else:
+        ok = [i for i in ext if a[i] >= min_frac * a[pk]]
+        if ok:
+            first = ok[0]
+    offset = float(first - centre)
+    if guard is not None and abs(offset) > guard:
+        log.warning(
+            "first_lobe anchor %+.0f samples exceeds guard %d; anchor not applied", offset, guard
+        )
+        return float("nan")
+    return offset

dasmccc/core.py

@@ -0,0 +1,210 @@
+"""Network multi-channel cross-correlation (MCCC) on an aligned DAS gather.
+
+One MCCC pass measures, for every channel, the lag that maximises the absolute
+correlation with about fifty partner channels drawn from a normal distribution
+within +-corr_len channels, then solves the sparse least-squares problem
+
+    min_tau || lamb * (tau_i - tau_j - lag_ij) ||^2 + || smoothness * (tau_{c+1} - tau_c) ||^2
+
+and smooths tau with a moving average. ``iterate_align`` repeats the pass, applying tau
+to the gather and median-filtering it along the fibre between passes.
+
+Sign convention: a positive tau[c] means channel c currently arrives *later* than its
+partners by tau samples (the aligned trace has to be advanced by tau).
+
+Every quantity is in samples or channels; the per-pair lag bound
+``max(pair_slope * |i - j|, pair_min_shift)`` is a bound on the *residual* moveout
+slope relative to the initial curve, not on the absolute moveout.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+from scipy import sparse
+from scipy.sparse.linalg import lsqr
+
+from .ops import moving_avg, spatial_median, tau_shift
+from .signal import NUMBA_AVAILABLE, jit, limited_cc, normal_distribution, prange
+
+log = logging.getLogger("dasmccc")
+
+
+def partner_pairs(
+    n_channels: int, corr_len: int, n_partners: int = 50, partner_std: float = 20.0
+) -> tuple[np.ndarray, np.ndarray]:
+    """Channel pairs (i, j) with j > i to correlate.
+
+    For each channel i, ``n_partners`` candidates are drawn as quantiles of a normal
+    distribution (std ``partner_std`` channels) truncated to
+    [i - corr_len, min(n_channels - 1, i + corr_len)]; candidates outside the fibre or
+    with j <= i are dropped, so each channel keeps roughly n_partners / 2 partners ahead
+    of it (the pairs behind it come from the earlier channels).
+    """
+    pairs_i, pairs_j = [], []
+    for i in range(n_channels):
+        cand = normal_distribution(
+            i - corr_len, min(n_channels - 1, i + corr_len), n_partners, partner_std
+        )
+        j = cand[(cand >= 0) & (cand < n_channels) & (cand > i)]
+        if j.size:
+            pairs_i.append(np.full(j.size, i, dtype=np.int64))
+            pairs_j.append(j.astype(np.int64))
+    if not pairs_i:
+        return np.zeros(0, np.int64), np.zeros(0, np.int64)
+    return np.concatenate(pairs_i), np.concatenate(pairs_j)
+
+
+@jit(nopython=True, parallel=True, cache=True)
+def _pair_lags_numba(data, pairs_i, pairs_j, pair_max_shift, lags):  # pragma: no cover - compiled
+    n_samples = data.shape[1]
+    for k in prange(len(pairs_i)):
+        tr_i = data[pairs_i[k], :]
+        tr_j = data[pairs_j[k], :]
+        ms = pair_max_shift[k]
+        best_shift = 0
+        best_abs = 0.0
+        for s in range(2 * ms + 1):
+            shift = s - ms
+            total = 0.0
+            if shift < 0:
+                for idx in range(n_samples + shift):
+                    total += tr_i[idx] * tr_j[idx - shift]
+            elif shift > 0:
+                for idx in range(n_samples - shift):
+                    total += tr_i[idx + shift] * tr_j[idx]
+            else:
+                for idx in range(n_samples):
+                    total += tr_i[idx] * tr_j[idx]
+            if abs(total) > best_abs:
+                best_abs = abs(total)
+                best_shift = shift
+        lags[k] = best_shift
+
+
+def pairwise_lags(
+    data: np.ndarray,
+    pairs_i: np.ndarray,
+    pairs_j: np.ndarray,
+    pair_slope: float = 0.2,
+    pair_min_shift: int = 3,
+    use_numba: bool | None = None,
+) -> np.ndarray:
+    """Lag (samples) maximising |cross-correlation| of each pair, searched within
+    +-max(pair_slope * (j - i), pair_min_shift) samples. Sign-agnostic, so a polarity
+    flip between channels does not break the alignment.
+    """
+    if use_numba is None:
+        use_numba = NUMBA_AVAILABLE
+    if use_numba and not NUMBA_AVAILABLE:
+        raise RuntimeError("use_numba=True requested but numba is not installed")
+    pair_max_shift = np.maximum((pairs_j - pairs_i) * pair_slope, pair_min_shift).astype(np.int64)
+    lags = np.zeros(len(pairs_i), dtype=np.float64)
+    if len(pairs_i) == 0:
+        return lags
+    data_c = np.ascontiguousarray(data, dtype=np.float64)
+    if use_numba:
+        _pair_lags_numba(data_c, pairs_i, pairs_j, pair_max_shift, lags)
+    else:
+        for k in range(len(pairs_i)):
+            ms = int(pair_max_shift[k])
+            corr = limited_cc(data_c[pairs_i[k]], data_c[pairs_j[k]], ms, use_numba=False)
+            lags[k] = np.argmax(np.abs(corr)) - ms
+    return lags
+
+
+def solve_tau(
+    n_channels: int,
+    pairs_i: np.ndarray,
+    pairs_j: np.ndarray,
+    lags: np.ndarray,
+    lamb: float = 1.0,
+    smoothness: float = 0.0,
+    reference_dt: np.ndarray | None = None,
+    tau_avg: int = 100,
+) -> np.ndarray:
+    """Least-squares tau (n_channels,) from pairwise lags, with an optional first-difference
+    smoothness term and a final moving average of ``tau_avg`` channels.
+
+    ``reference_dt`` (n_channels - 1,) makes the smoothness term target that adjacent-channel
+    difference instead of zero (follow a theoretical moveout while correlating).
+    """
+    n_pairs = len(pairs_i)
+    rows = np.repeat(np.arange(n_pairs), 2)
+    cols = np.column_stack([pairs_i, pairs_j]).ravel()
+    vals = np.tile([1.0, -1.0], n_pairs)
+    diff = sparse.csr_matrix((lamb * vals, (rows, cols)), shape=(n_pairs, n_channels))
+    b = lamb * np.asarray(lags, float)
+    if smoothness > 0:
+        m = n_channels - 1
+        d_rows = np.repeat(np.arange(m), 2)
+        d_cols = np.column_stack([np.arange(m), np.arange(1, n_channels)]).ravel()
+        d_vals = np.tile([-1.0, 1.0], m)
+        d_mat = sparse.csr_matrix((smoothness * d_vals, (d_rows, d_cols)), shape=(m, n_channels))
+        if reference_dt is None:
+            b_smooth = np.zeros(m)
+        else:
+            reference_dt = np.asarray(reference_dt, float)
+            if reference_dt.shape != (m,):
+                raise ValueError(f"reference_dt must have shape ({m},), got {reference_dt.shape}")
+            b_smooth = reference_dt
+        diff = sparse.vstack([diff, d_mat]).tocsr()
+        b = np.concatenate([b, smoothness * b_smooth])
+    tau = lsqr(diff, b, atol=1e-10, btol=1e-10)[0]
+    if tau_avg > n_channels:
+        log.warning(
+            "tau_avg %d longer than the %d refined channels; averaging over all of them",
+            tau_avg,
+            n_channels,
+        )
+        tau_avg = n_channels
+    return moving_avg(tau, tau_avg)
+
+
+def mccc(
+    data: np.ndarray,
+    corr_len: int,
+    n_partners: int = 50,
+    partner_std: float = 20.0,
+    pair_slope: float = 0.2,
+    pair_min_shift: int = 3,
+    lamb: float = 1.0,
+    smoothness: float = 0.0,
+    reference_dt: np.ndarray | None = None,
+    tau_avg: int = 100,
+    use_numba: bool | None = None,
+) -> np.ndarray:
+    """One MCCC pass on an aligned gather (n_channels, n_samples); returns tau (n_channels,)."""
+    pairs_i, pairs_j = partner_pairs(data.shape[0], corr_len, n_partners, partner_std)
+    lags = pairwise_lags(data, pairs_i, pairs_j, pair_slope, pair_min_shift, use_numba)
+    return solve_tau(data.shape[0], pairs_i, pairs_j, lags, lamb, smoothness, reference_dt, tau_avg)
+
+
+def iterate_align(
+    aligned: np.ndarray,
+    corr_len: int,
+    n_iter: int = 4,
+    medfilt_channels: int = 25,
+    medfilt_iters: tuple[int, ...] = (1, 2, 3),
+    use_numba: bool | None = None,
+    **mccc_kwargs,
+) -> tuple[np.ndarray, np.ndarray, list[np.ndarray]]:
+    """Iterated MCCC on a pre-aligned, windowed gather.
+
+    Pass i (1-based) correlates within ``corr_len // i`` channels, applies tau, and median
+    filters the gather along the fibre when i is in ``medfilt_iters``. Returns
+    (aligned, total_tau, taus); ``total_tau`` (n_channels,) is the summed tau, so the
+    refined arrival of channel c is ``round(initial_pick[c]) + total_tau[c]`` in the
+    original sample axis (see ``pipeline.refine_curve``).
+    """
+    taus = []
+    total = np.zeros(aligned.shape[0])
+    for i in range(1, n_iter + 1):
+        tau = mccc(aligned, corr_len // i, use_numba=use_numba, **mccc_kwargs)
+        taus.append(tau)
+        total += tau
+        aligned = tau_shift(aligned, tau)
+        if i in medfilt_iters:
+            aligned = spatial_median(aligned, medfilt_channels)
+    return aligned, total, taus

dasmccc/legacy.py

@@ -0,0 +1,91 @@
+"""das-focmec compatible entry points.
+
+``das_focmec.processing.workflows.mccc_pipeline`` was written against
+``ultra_mccc_iterative`` and ``diff_corr_ric`` from its own ``mccc_core``; these wrappers
+keep those signatures and return values exactly (intermediate arrays, legacy (n, 2) pick
+and tau layouts) on top of the dasmccc building blocks, so that the focal-mechanism
+pipeline reproduces bit for bit while new code uses ``dasmccc.refine_curve``.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+
+import numpy as np
+
+from .core import mccc
+from .ops import shift_arr, spatial_median, tau_shift
+from .polarity import ricker_windows
+
+log = logging.getLogger("dasmccc")
+
+
+def ultra_mccc_iterative(
+    das_arr: np.ndarray,
+    pick: np.ndarray,
+    corr_len: int,
+    max_shift: int | None,
+    lamb: float,
+    n_iterations: int = 3,
+    shrinked_window_length: int = 300,
+    medfilt_iterations=(1, 2, 3),
+    smoothness: float = 0.0,
+    reference_dt: np.ndarray | None = None,
+    pre_mccc_mask_half_width: int | None = None,
+):
+    """Legacy iterative MCCC.
+
+    pick : (n_channels, 2) array [channel index, pick sample] as in das-focmec.
+    max_shift : accepted for compatibility and ignored, as it always was: the per-pair lag
+        bound is max(0.2 * channel gap, 3) samples.
+
+    Returns ``(intermediates, total_shift, [first_shifts, base_time], tau_list)`` where
+    ``intermediates = [das_arr, shifted, after pass 1, ...]``, the refined pick is
+    ``base_time - total_shift`` and each tau is an (n_channels, 2) [index, tau] array.
+    """
+    if max_shift is not None:
+        warnings.warn(
+            "ultra_mccc_iterative: max_shift has no effect (per-pair bound is "
+            "max(0.2 * gap, 3) samples); pass None to silence",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    half = shrinked_window_length // 2
+    base_time = das_arr.shape[1] // 2
+    pick = np.asarray(pick, float)
+    if pick.shape != (das_arr.shape[0], 2):
+        raise ValueError(f"pick must be (n_channels, 2), got {pick.shape}")
+    log.info("legacy ultra_mccc_iterative: initial shift")
+    shifted, first_shifts = shift_arr(das_arr, pick[:, 1], base_time)
+    shifted = shifted[:, base_time - half : base_time + half]
+    if pre_mccc_mask_half_width is not None:
+        centre = shifted.shape[1] // 2
+        keep = np.zeros_like(shifted)
+        sl = slice(centre - pre_mccc_mask_half_width, centre + pre_mccc_mask_half_width)
+        keep[:, sl] = shifted[:, sl]
+        shifted = keep
+        log.info("  pre-MCCC mask +-%d samples", pre_mccc_mask_half_width)
+    current = shifted
+    intermediates = [das_arr, shifted]
+    tau_list = []
+    total_shift = first_shifts.astype(np.float64).copy()
+    for i in range(1, n_iterations + 1):
+        log.info("  MCCC pass %d", i)
+        tau = mccc(
+            current, corr_len // i, lamb=lamb, smoothness=smoothness, reference_dt=reference_dt
+        )
+        tau_list.append(np.column_stack([np.arange(tau.size), tau]))
+        current = tau_shift(current, tau)
+        if i in medfilt_iterations:
+            current = spatial_median(current, 25)
+        intermediates.append(current)
+        total_shift -= tau
+    return intermediates, total_shift, [first_shifts, base_time], tau_list
+
+
+def diff_corr_ric(shifted_arr, max_shift, snr_thresh=5, mmad_thresh=4.0, ricker_freq=50):
+    """Legacy tuple form of :func:`dasmccc.polarity.ricker_windows`:
+    ``(dts, polarities, amps, snrs, wins)``."""
+    r = ricker_windows(shifted_arr, max_shift, snr_thresh, mmad_thresh, ricker_freq)
+    return r.dt, r.polarity, r.amplitude, r.snr, r.window

dasmccc/ops.py

@@ -0,0 +1,61 @@
+"""Array operations on a (n_channels, n_samples) gather: integer time shifts,
+tau smoothing and the spatial (channel-axis) median filter."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.signal import medfilt
+
+PAD_VALUE = 1e-14  # samples rolled in from outside the trace (tiny, not exactly zero)
+
+
+def _shift_trace(trace: np.ndarray, shift: int) -> np.ndarray:
+    """Delay ``trace`` by ``shift`` samples (negative = advance), padding with PAD_VALUE."""
+    if shift > 0:
+        return np.concatenate([np.full(shift, PAD_VALUE), trace[:-shift]])
+    if shift < 0:
+        return np.concatenate([trace[-shift:], np.full(-shift, PAD_VALUE)])
+    return trace.copy()
+
+
+def shift_arr(data: np.ndarray, picks: np.ndarray, base_time: int) -> tuple[np.ndarray, np.ndarray]:
+    """Shift every channel so that its pick (sample index, rounded) lands on ``base_time``.
+
+    Returns (shifted, shifts) with ``shifts[c] = round(base_time - picks[c])`` in samples.
+    """
+    picks = np.asarray(picks, float)
+    if picks.shape != (data.shape[0],):
+        raise ValueError(f"picks must have shape ({data.shape[0]},), got {picks.shape}")
+    if not np.all(np.isfinite(picks)):
+        raise ValueError("picks must be finite for every channel")
+    shifts = np.round(base_time - picks).astype(int)
+    shifted = np.stack([_shift_trace(data[c], int(shifts[c])) for c in range(data.shape[0])])
+    return shifted, shifts
+
+
+def tau_shift(data: np.ndarray, tau: np.ndarray) -> np.ndarray:
+    """Advance every channel by ``round(tau[c])`` samples (tau > 0 moves the trace earlier)."""
+    tau = np.asarray(tau, float)
+    if tau.shape != (data.shape[0],):
+        raise ValueError(f"tau must have shape ({data.shape[0]},), got {tau.shape}")
+    return np.stack([_shift_trace(data[c], int(round(-tau[c]))) for c in range(data.shape[0])])
+
+
+def moving_avg(x: np.ndarray, win: int) -> np.ndarray:
+    """Centred moving average of length ``win`` with reflected edges; same length as ``x``."""
+    if win < 2:
+        return np.asarray(x, float).copy()
+    if win > len(x):
+        raise ValueError(f"moving_avg window {win} longer than the array ({len(x)})")
+    pad_left = win // 2
+    pad_right = win - 1 - pad_left
+    padded = np.pad(np.asarray(x, float), (pad_left, pad_right), mode="reflect")
+    return np.convolve(padded, np.ones(win) / win, mode="valid")
+
+
+def spatial_median(data: np.ndarray, n_channels: int) -> np.ndarray:
+    """Median filter along the channel axis with an odd kernel of ``n_channels``
+    (zero-padded at the fibre ends, as scipy.signal.medfilt does)."""
+    if n_channels % 2 == 0:
+        raise ValueError("spatial median kernel must be odd")
+    return medfilt(data, kernel_size=(n_channels, 1))