das-mccc 0.2.0__tar.gz

das_mccc-0.2.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,79 @@
+# 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/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "das-mccc"
+version = "0.2.0"
+description = "Iterative network MCCC refinement of DAS arrival curves with absolute anchoring and Ricker polarity QC"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Jaewoo Kim", email = "jk103@rice.edu"}]
+keywords = ["DAS", "distributed acoustic sensing", "microseismic", "cross-correlation", "phase picking"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = ["numpy", "scipy"]
+
+[project.urls]
+Repository = "https://github.com/Jaewoo-Kim-Rice/das-mccc"
+Algorithm = "https://github.com/Jaewoo-Kim-Rice/das-mccc/blob/main/docs/algorithm.md"
+
+[project.optional-dependencies]
+numba = ["numba"]
+dev = ["pytest", "ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

das_mccc-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

das_mccc-0.2.0/src/das_mccc.egg-info/PKG-INFO

@@ -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/src/das_mccc.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/das_mccc.egg-info/PKG-INFO
+src/das_mccc.egg-info/SOURCES.txt
+src/das_mccc.egg-info/dependency_links.txt
+src/das_mccc.egg-info/requires.txt
+src/das_mccc.egg-info/top_level.txt
+src/dasmccc/__init__.py
+src/dasmccc/anchor.py
+src/dasmccc/core.py
+src/dasmccc/legacy.py
+src/dasmccc/ops.py
+src/dasmccc/pipeline.py
+src/dasmccc/polarity.py
+src/dasmccc/signal.py
+tests/test_core.py
+tests/test_legacy.py
+tests/test_pipeline.py

das_mccc-0.2.0/src/das_mccc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

das_mccc-0.2.0/src/das_mccc.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy
+scipy
+
+[dev]
+pytest
+ruff
+
+[numba]
+numba

das_mccc-0.2.0/src/das_mccc.egg-info/top_level.txt

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

das_mccc-0.2.0/src/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",
+]

das_mccc-0.2.0/src/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