From d6dcb52a6bdefd2a911e7e9bc5fec7ff268af5e7 Mon Sep 17 00:00:00 2001 From: Alessia Maggi Date: Thu, 3 Sep 2026 19:42:55 +0200 Subject: [PATCH 1/7] feat(detect): STA/LTA characteristic function atom --- tests/test_atoms_detect.py | 106 +++++++++++++++++++- xdas/__init__.py | 3 +- xdas/atoms/__init__.py | 4 +- xdas/atoms/detect.py | 191 ++++++++++++++++++++++++++++++++++++- 4 files changed, 297 insertions(+), 7 deletions(-) diff --git a/tests/test_atoms_detect.py b/tests/test_atoms_detect.py index 5ad2464a..d7b3a01e 100644 --- a/tests/test_atoms_detect.py +++ b/tests/test_atoms_detect.py @@ -10,7 +10,7 @@ import pytest import xdas as xd -from xdas.atoms import Trigger +from xdas.atoms import STALTA, Trigger def generate(): @@ -455,3 +455,107 @@ def test_each_lane_keeps_its_own_identity_and_time_base(self): assert sorted(zip(chunked["distance"], chunked["time"])) == sorted( zip(eager["distance"], eager["time"]) ) + + +def generate_stalta(nt=2000, nx=3, seed=42): + """A noisy record with three transients, for the characteristic function.""" + rng = np.random.default_rng(seed) + data = rng.normal(0.0, 1.0, (nt, nx)) + for onset in (400, 1100, 1700): + if onset + 30 <= nt: + data[onset : onset + 30] += 15.0 * np.exp(-np.arange(30) / 6.0)[:, None] + return xd.DataArray( + data=data, + coords={ + "time": { + "tie_indices": [0, nt - 1], + "tie_values": [0.0, (nt - 1) * 0.002], + "sampling_interval": 0.002, + }, + "distance": np.arange(nx) * 10.0, + }, + ) + + +def run_chunked(atom, da, n): + """Feed `da` to `atom` in `n` chunks and re-join everything it emits.""" + outs = [atom(chunk, chunk_dim="time") for chunk in xd.split(da, n, dim="time")] + return xd.concat(outs + list(atom.flush()), "time") + + +class TestSTALTA: + @pytest.mark.parametrize("mode", ["causal", "centered"]) + @pytest.mark.parametrize("n", [2, 5, 17, 200]) + def test_chunked_equals_eager(self, mode, n): + da = generate_stalta() + expected = STALTA(sta=0.02, lta=0.5, mode=mode)(da) + result = run_chunked(STALTA(sta=0.02, lta=0.5, mode=mode), da, n) + assert result.shape == expected.shape + assert np.allclose(result.values, expected.values) + assert np.array_equal( + result.coords["time"].values, expected.coords["time"].values + ) + + def test_causal_holds_nothing_back(self): + da = generate_stalta() + atom = STALTA(sta=0.02, lta=0.5, mode="causal") + assert run_chunked(atom, da, 4).sizes["time"] == da.sizes["time"] + assert atom.flush() == [] + + def test_centered_holds_back_and_flushes(self): + da = generate_stalta() + atom = STALTA(sta=0.02, lta=0.5, mode="centered") + outs = [atom(chunk, chunk_dim="time") for chunk in xd.split(da, 4, dim="time")] + emitted = xd.concat(outs, "time").sizes["time"] + assert emitted < da.sizes["time"] + (tail,) = atom.flush() + assert emitted + tail.sizes["time"] == da.sizes["time"] + + def test_causal_onset_is_later_than_centered(self): + da = generate_stalta() + causal = STALTA(sta=0.02, lta=0.5, mode="causal")(da) + centered = STALTA(sta=0.02, lta=0.5, mode="centered")(da) + assert int(causal.values[:, 0].argmax()) > int(centered.values[:, 0].argmax()) + + def test_twin_and_pipeline(self): + da = generate_stalta() + assert np.allclose( + xd.stalta(da, sta=0.02, lta=0.5).values, + STALTA(sta=0.02, lta=0.5)(da).values, + ) + assert isinstance(xd.stalta(..., sta=0.02, lta=0.5), STALTA) + picks = da >> (xd.stalta(..., sta=0.02, lta=0.5) >> xd.trigger(..., thresh=8.0)) + assert len(picks) > 0 + + def test_window_and_pad_mode(self): + da = generate_stalta() + hann = STALTA(sta=0.02, lta=0.5, window="hann")(da) + boxcar = STALTA(sta=0.02, lta=0.5, window="boxcar")(da) + assert not np.allclose(hann.values, boxcar.values) + edge = STALTA(sta=0.02, lta=0.5, pad_mode="edge")(da) + assert not np.allclose(edge.values, boxcar.values) + + @pytest.mark.parametrize("mode", ["causal", "centered"]) + def test_record_shorter_than_the_halo(self, mode): + # The whole stream fits inside the window: nothing is ever emitted by + # `call`, and `flush` pads both ends as the ends of the record. + da = generate_stalta(nt=60) + expected = STALTA(sta=0.02, lta=0.5, mode=mode)(da) + result = run_chunked(STALTA(sta=0.02, lta=0.5, mode=mode), da, 4) + assert np.allclose(result.values, expected.values) + + def test_flush_without_data_is_empty(self): + # Uninitialised, and initialised by an eager (unchunked) call: neither + # holds anything back. + atom = STALTA(sta=0.02, lta=0.5, mode="centered") + assert atom.flush() == [] + atom(generate_stalta()) + assert atom.flush() == [] + + def test_invalid_parameters(self): + with pytest.raises(ValueError, match="strictly positive"): + STALTA(sta=0.0, lta=1.0) + with pytest.raises(ValueError, match="longer than"): + STALTA(sta=1.0, lta=0.5) + with pytest.raises(ValueError, match="causal.*centered"): + STALTA(sta=0.02, lta=0.5, mode="acausal") diff --git a/xdas/__init__.py b/xdas/__init__.py index 902c6a4a..718754df 100644 --- a/xdas/__init__.py +++ b/xdas/__init__.py @@ -72,6 +72,7 @@ "rechunk", "resample", "sliding_mean_removal", + "stalta", "stft", "taper", "trigger", @@ -97,7 +98,7 @@ # `sys.modules` and does not rebind the attribute: the lowercase twin below # stays `xdas.trigger` for everyone. from . import trigger as _trigger_module # noqa: F401 isort: skip -from .atoms.detect import trigger +from .atoms.detect import stalta, trigger from .atoms.kernel import rechunk from .atoms.ml import annotate, mlpicker, pick from .atoms.operations import ( diff --git a/xdas/atoms/__init__.py b/xdas/atoms/__init__.py index 093fa825..a4e9d869 100644 --- a/xdas/atoms/__init__.py +++ b/xdas/atoms/__init__.py @@ -18,6 +18,7 @@ """ __all__ = [ + "STALTA", "STFT", "Annotate", "Atom", @@ -43,11 +44,12 @@ "as_function", "atomized", "compose", + "stalta", "trigger", ] from .core import Atom, Partial, Sequential, State, as_function, atomized, compose -from .detect import Trigger, trigger +from .detect import STALTA, Trigger, stalta, trigger from .kernel import DownSample, LFilter, Polyphase, Rechunk, SOSFilter, UpSample from .ml import Annotate, MLPicker, Picker from .operations import ( diff --git a/xdas/atoms/detect.py b/xdas/atoms/detect.py index c8ae5287..90f9fb83 100644 --- a/xdas/atoms/detect.py +++ b/xdas/atoms/detect.py @@ -1,23 +1,25 @@ """ -Detection atoms: turn a characteristic function into picks. +Detection atoms: characteristic functions, and the picks drawn from them. These atoms emit :class:`pandas.DataFrame` objects rather than arrays — the transducer contract makes that unremarkable, a pick table is just another chunk type flowing downstream to a CSV sink. :class:`Trigger` is the threshold detector; its lowercase twin is :func:`xdas.trigger`. +:class:`STALTA` builds the characteristic function such a detector consumes. """ from collections.abc import Mapping import numpy as np import pandas as pd +import scipy.signal as sp from numba import njit -from ..coordinates import Coordinate -from ..core import concat_coords +from ..coordinates import Coordinate, get_sampling_interval +from ..core import DataArray, concat, concat_coords from .core import Atom, State, atomized -__all__ = ["Trigger", "trigger"] +__all__ = ["STALTA", "Trigger", "stalta", "trigger"] #: Name of the label dimension a mapping of thresholds keys on. It is the #: dimension :class:`~xdas.atoms.Annotate` appends to its characteristic @@ -594,3 +596,184 @@ def _trigger( # pragma: no cover trigger = atomized(Trigger) + + +class STALTA(Atom): + """ + Short-term over long-term average characteristic function. + + The ratio of a short trailing (or centred) mean of the squared signal to a + long one: the classic amplitude detector, whose output is fed to + :class:`Trigger` to obtain picks. Both window lengths are given in the + physical units of `dim`, so the same atom applies to any sampling rate. + + Stateful: the trailing samples the next window will need are carried + across chunks, so chunked processing returns exactly what a single call on + the whole record returns. In ``"centered"`` mode a window also reaches + forward, so each call holds back the samples it cannot yet complete and + :meth:`flush` releases them at the end of the stream. In ``"causal"`` mode + nothing is held back and :meth:`flush` has nothing to return. + + Parameters + ---------- + sta : float + Length of the short-term window, in the units of `dim`. + lta : float + Length of the long-term window, in the units of `dim`. Must be longer + than `sta`. + mode : {"causal", "centered"}, optional + Where each window sits relative to the sample it produces. + ``"causal"`` (default) averages the samples up to and including it, as + a real-time detector must; the onset of a transient is then reported + late by roughly half the short window. ``"centered"`` averages + symmetrically about it, which sharpens the onset but needs samples + from the future, and so is only available offline. The choice shifts + pick times, so it is a property of the detector, not a tuning knob. + window : str, optional + Tapering window applied to both means, by default "boxcar" — the plain + running mean. Any window accepted by :func:`scipy.signal.get_window`. + pad_mode : str, optional + How the two ends of the *record* are extended where a window would + reach past them, by default "reflect". Chunk seams are never padded: + they use the real neighbouring samples. + dim : str, optional + The dimension along which to compute the ratio, by default "time". + + Examples + -------- + >>> import numpy as np + >>> import xdas as xd + + A transient buried in noise: + + >>> rng = np.random.default_rng(42) + >>> data = rng.normal(0.0, 1.0, 2000) + >>> data[1200:1240] += 20.0 + >>> da = xd.DataArray( + ... data=data, + ... coords={"time": {"tie_indices": [0, 1999], "tie_values": [0.0, 199.9], + ... "sampling_interval": 0.1}}, + ... ) + + Eager processing with the functional twin: + + >>> cft = xd.stalta(da, sta=1.0, lta=20.0) + >>> float(cft.max().values) > 10.0 + True + + Chunked processing gives the same answer, seam for seam: + + >>> atom = xd.stalta(..., sta=1.0, lta=20.0) + >>> chunks = [atom(chunk, chunk_dim="time") + ... for chunk in xd.split(da, 8, dim="time")] + >>> chunked = xd.concat(chunks + list(atom.flush()), "time") + >>> bool(np.allclose(chunked.values, cft.values)) + True + + Piped into the trigger, which is the point of it: + + >>> picks = xd.stalta(da, sta=1.0, lta=20.0) >> xd.trigger(..., thresh=8.0) + + """ + + def __init__( + self, sta, lta, mode="causal", window="boxcar", pad_mode="reflect", dim="time" + ): + super().__init__() + if not sta > 0.0: + raise ValueError("`sta` must be strictly positive") + if not lta > sta: + raise ValueError("`lta` must be longer than `sta`") + if mode not in ("causal", "centered"): + raise ValueError("`mode` must be either 'causal' or 'centered'") + self.sta = float(sta) + self.lta = float(lta) + self.mode = mode + self.window = window + self.pad_mode = pad_mode + self.dim = dim + + # states + self.fs = State(...) + self.buffer = State(...) + self.skip = State(...) + + def initialize(self, da, chunk_dim=None, **flags): + """Measure the sampling rate to size the windows, and open the buffer.""" + self.fs = State(1.0 / get_sampling_interval(da, self.dim)) + self.initialize_from_state() + self.skip = State(0) + if chunk_dim == self.dim: + self.buffer = State(da.isel({self.dim: slice(0, 0)})) + else: + self.buffer = State(None) + + def initialize_from_state(self): + """Derive the window lengths, in samples, from the sampling rate.""" + self.sta_n = _oddify(self.sta * self.fs, 3) + self.lta_n = _oddify(self.lta * self.fs, self.sta_n + 2) + if self.mode == "causal": + self.lookback, self.lookahead = self.lta_n - 1, 0 + else: + self.lookback = self.lookahead = self.lta_n // 2 + + def call(self, da, **flags): + """Emit the ratio for every sample whose windows are complete.""" + if self.buffer is None: # whole record: both ends are record ends + return self._ratio(da) + x = concat([self.buffer, da], self.dim) if self.buffer.sizes[self.dim] else da + size = x.sizes[self.dim] + if size <= self.lookback + self.lookahead: + # Too little of the record has arrived to extend its start the way + # a single call would: hold everything and emit nothing yet. + self.buffer = State(x) + return [] + stop = size - self.lookahead + out = self._ratio(x).isel({self.dim: slice(self.skip, stop)}) + keep = self.lookback + self.lookahead + self.buffer = State(x.isel({self.dim: slice(size - keep, None)})) + self.skip = State(stop - (size - keep)) + return out + + def flush(self): + """Release the held-back tail, padded as the end of a record.""" + # Not `self.buffer is None`: a flush also reaches an atom that was + # never chunked (buffer `None`) or never called at all (buffer `...`). + if not isinstance(self.buffer, DataArray): + return [] + if self.skip >= self.buffer.sizes[self.dim]: + return [] + return [self._ratio(self.buffer).isel({self.dim: slice(self.skip, None)})] + + def _ratio(self, da): + """Compute the ratio of the two windowed means over a whole block.""" + axis = da.get_axis_num(self.dim) + energy = np.square(np.asarray(da.values, dtype=float)) + sta = self._mean(energy, self.sta_n, axis) + lta = self._mean(energy, self.lta_n, axis) + np.maximum(lta, np.finfo(float).eps, out=lta) + return da.copy(data=sta / lta) + + def _mean(self, energy, size, axis): + """Windowed mean of `energy`, placed according to `mode`.""" + weights = sp.get_window(self.window, size).astype(float) + weights /= weights.sum() + shape = tuple(-1 if a == axis else 1 for a in range(energy.ndim)) + if self.mode == "causal": + before, after = size - 1, 0 + else: + before = after = size // 2 + pad = tuple( + (before, after) if a == axis else (0, 0) for a in range(energy.ndim) + ) + padded = np.pad(energy, pad, mode=self.pad_mode) + return sp.fftconvolve(padded, weights.reshape(shape), mode="valid") + + +def _oddify(size, floor): + """Round a window length to an odd number of samples, at least `floor`.""" + size = max(floor, round(float(size))) + return size if size % 2 else size + 1 + + +stalta = atomized(STALTA) From f9091a21c27acab66d6dc1bb8f8831a1fb03c7f2 Mon Sep 17 00:00:00 2001 From: Alessia Maggi Date: Thu, 3 Sep 2026 19:43:36 +0200 Subject: [PATCH 2/7] docs(detect): document the STA/LTA atom --- docs/api/atoms.md | 11 +++--- docs/release-notes.md | 11 ++++++ docs/user-guide/pipeline/atoms.md | 3 +- docs/user-guide/pipeline/picking.md | 55 +++++++++++++++++++++++++++++ 4 files changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/api/atoms.md b/docs/api/atoms.md index 348fa115..fb273b03 100644 --- a/docs/api/atoms.md +++ b/docs/api/atoms.md @@ -133,6 +133,7 @@ data it applies eagerly, called on `...` it returns the atom. rechunk resample sliding_mean_removal + stalta stft taper trigger @@ -144,16 +145,18 @@ data it applies eagerly, called on `...` it returns the atom. ## Detection and picking -`Annotate` runs a SeisBench model window by window, `Trigger` turns the -characteristic function it produces into a pick table, and `Picker` is the -whole pipeline a weight set describes — its own filter, its own sampling rate, +`STALTA` and `Annotate` build a characteristic function — the first from the +amplitude of the signal itself, the second by running a SeisBench model window +by window — `Trigger` turns either one into a pick table, and `Picker` is the +whole pipeline a weight set describes: its own filter, its own sampling rate, its own per-phase thresholds. Each has a lowercase functional twin at the top -level of `xdas` (`xdas.annotate`, `xdas.trigger`, `xdas.pick`). +level of `xdas` (`xdas.stalta`, `xdas.annotate`, `xdas.trigger`, `xdas.pick`). ```{eval-rst} .. autosummary:: :toctree: ../_autosummary + STALTA Annotate Trigger Picker diff --git a/docs/release-notes.md b/docs/release-notes.md index 54490082..ac424d7d 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,5 +1,16 @@ # Release notes +## Unreleased + +### Atoms +- **`xdas.stalta`**, the short-term over long-term average characteristic + function, feeding the existing `Trigger` so that detection no longer needs a + model. Both windows are given in the units of the dimension, `mode="causal"` + (default) or `"centered"` places them relative to the sample they produce, + and the atom is stateful: chunked processing returns what a single call on + the whole record returns, `flush()` releasing the tail `"centered"` mode + holds back (@amaggi). + ## 0.2.9 ### Tiles Backend diff --git a/docs/user-guide/pipeline/atoms.md b/docs/user-guide/pipeline/atoms.md index 34c94a0f..2834a51b 100644 --- a/docs/user-guide/pipeline/atoms.md +++ b/docs/user-guide/pipeline/atoms.md @@ -86,7 +86,8 @@ energy | {py:func}`~xdas.hilbert` | analytic signal | | {py:func}`~xdas.medfilt`, {py:func}`~xdas.sliding_mean_removal` | kernels in seconds or meters | | {py:func}`~xdas.rechunk` | a streaming-cadence knob, not an operation | -| {py:func}`~xdas.annotate`, {py:func}`~xdas.trigger`, {py:func}`~xdas.pick` | machine-learning picking (see [](picking.md)) | +| {py:func}`~xdas.stalta` | short-term over long-term average, windows in seconds | +| {py:func}`~xdas.annotate`, {py:func}`~xdas.trigger`, {py:func}`~xdas.pick` | detection and picking (see [](picking.md)) | Each has an atom behind it — {py:class}`~xdas.atoms.Filter`, {py:class}`~xdas.atoms.Resample`, and so on — reached by seeding with `...`. diff --git a/docs/user-guide/pipeline/picking.md b/docs/user-guide/pipeline/picking.md index 88cefa04..85bb3431 100644 --- a/docs/user-guide/pipeline/picking.md +++ b/docs/user-guide/pipeline/picking.md @@ -288,3 +288,58 @@ across that band. When the data already arrives at the model's training rate the stage does nothing and the two agree exactly; when a resample is needed the picks can diverge. Pass `resample=False` to drop the stage, or to compare the two implementations on identical waveforms. + +## Detecting without a model + +Not every detection needs a network of weights. {py:func}`~xdas.stalta` is the +classic amplitude detector — a short trailing average of the squared signal +over a long one — and it feeds the very same {py:class}`~xdas.atoms.Trigger`, +so the pick table and everything downstream of it are unchanged. Both window +lengths are given in the units of the dimension, seconds here, so the same atom +applies whatever the sampling rate: + +```{code-cell} +import numpy as np + +rng = np.random.default_rng(42) +data = rng.normal(size=(6000, 4)) +data[2000:2100] += 8.0 * np.exp(-np.arange(100) / 25.0)[:, None] +noisy = xd.DataArray( + data, + { + "time": { + "tie_indices": [0, 5999], + "tie_values": [0.0, 59.99], + "sampling_interval": 0.01, + }, + "distance": np.arange(4) * 10.0, + }, +) + +xd.trigger(xd.stalta(noisy, sta=0.5, lta=10.0), thresh=8.0) +``` + +The transient starts at 20 s and is picked a little after it: a causal detector +only ever sees the past, so it reports an onset late by roughly half the short +window. That is the default, and the only mode a real-time detector can use. +Offline, `mode="centered"` averages symmetrically about the sample it produces, +which sharpens the onset at the price of needing samples from the future: + +```{code-cell} +xd.trigger(xd.stalta(noisy, sta=0.5, lta=10.0, mode="centered"), thresh=8.0) +``` + +The choice moves pick times, so it is a property of the detector rather than a +tuning knob — the same threshold on the same record gives different times under +the two modes. + +Like every atom, it is stateful: an hour arriving in ten-second chunks gives +exactly what the hour gives in one piece, seam for seam. In `"centered"` mode +the samples whose window is not yet complete are held back, and `flush()` +releases them at the end of the stream — which the streaming machinery of +[](processing.md) calls for you: + +```{code-cell} +pipeline = xd.stalta(..., sta=0.5, lta=10.0) >> xd.trigger(..., thresh=8.0) +pipeline.process(noisy, chunks={"time": 500}) +``` From a2f47203e9763acbd4c70dba8a4d22a018602e45 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Fri, 16 Oct 2026 11:58:02 +0200 Subject: [PATCH 3/7] fix(detect): rebuild STALTA on ObsPy's recursive, classic and delayed methods Replace mode/window/pad_mode with method={recursive (default), classic, delayed, centered}. Running sums in numba kernels stream at O(1) per sample (was a full FFT convolution of the buffer per chunk, 54x slower than eager on 1 s chunks), floor the long-term average at tiny instead of eps (the ratio collapsed on ~1e-9 strain rates), zero the warm-up as ObsPy does instead of reflect-padding the record start (which leaked the future into causal output), and re-sum each boxcar once per window so a loud transient's round-off does not outlive two windows. recursive is bit-exact against obspy.signal.trigger.recursive_sta_lta, classic within 1e-10 of classic_sta_lta; delayed and centered are checked against direct window sums (ObsPy 1.5's delayed_sta_lta adds instead of subtracts). --- tests/test_atoms_detect.py | 224 ++++++++++++++++++------- xdas/atoms/detect.py | 328 ++++++++++++++++++++++++++----------- 2 files changed, 393 insertions(+), 159 deletions(-) diff --git a/tests/test_atoms_detect.py b/tests/test_atoms_detect.py index d7b3a01e..9fb29b76 100644 --- a/tests/test_atoms_detect.py +++ b/tests/test_atoms_detect.py @@ -457,105 +457,203 @@ def test_each_lane_keeps_its_own_identity_and_time_base(self): ) -def generate_stalta(nt=2000, nx=3, seed=42): +STALTA_METHODS = ["recursive", "classic", "delayed", "centered"] +BOXCAR_METHODS = ["classic", "delayed", "centered"] + + +def generate_stalta(nt=6000, nx=3, seed=42, delta=0.01): """A noisy record with three transients, for the characteristic function.""" rng = np.random.default_rng(seed) data = rng.normal(0.0, 1.0, (nt, nx)) - for onset in (400, 1100, 1700): - if onset + 30 <= nt: - data[onset : onset + 30] += 15.0 * np.exp(-np.arange(30) / 6.0)[:, None] + for onset in (1500, 3200, 4700): + if onset + 100 <= nt: + data[onset : onset + 100] += 15.0 * np.exp(-np.arange(100) / 25.0)[:, None] return xd.DataArray( data=data, coords={ "time": { "tie_indices": [0, nt - 1], - "tie_values": [0.0, (nt - 1) * 0.002], - "sampling_interval": 0.002, + "tie_values": [0.0, (nt - 1) * delta], + "sampling_interval": delta, }, "distance": np.arange(nx) * 10.0, }, ) -def run_chunked(atom, da, n): - """Feed `da` to `atom` in `n` chunks and re-join everything it emits.""" - outs = [atom(chunk, chunk_dim="time") for chunk in xd.split(da, n, dim="time")] - return xd.concat(outs + list(atom.flush()), "time") +def boxcar_reference(x, nsta, nlta, method): + """Direct sum of every window, zero where one is incomplete.""" + energy = np.square(x) + n = len(x) + out = np.zeros(n) + for i in range(n): + match method: + case "classic": + ends = (i, i) + case "delayed": + ends = (i, i - nsta) + case "centered": + ends = (i + nsta // 2, i + nlta // 2) + windows = [(ends[0] - nsta + 1, ends[0]), (ends[1] - nlta + 1, ends[1])] + if all(lo >= 0 and hi < n for lo, hi in windows): + (a, b), (c, d) = windows + out[i] = energy[a : b + 1].mean() / energy[c : d + 1].mean() + return out class TestSTALTA: - @pytest.mark.parametrize("mode", ["causal", "centered"]) - @pytest.mark.parametrize("n", [2, 5, 17, 200]) - def test_chunked_equals_eager(self, mode, n): + @pytest.mark.parametrize("sta, lta", [(0.5, 10.0), (0.21, 3.0)]) + def test_recursive_matches_obspy_exactly(self, sta, lta): + from obspy.signal.trigger import recursive_sta_lta + da = generate_stalta() - expected = STALTA(sta=0.02, lta=0.5, mode=mode)(da) - result = run_chunked(STALTA(sta=0.02, lta=0.5, mode=mode), da, n) - assert result.shape == expected.shape - assert np.allclose(result.values, expected.values) - assert np.array_equal( - result.coords["time"].values, expected.coords["time"].values - ) + result = STALTA(sta, lta, method="recursive")(da) + nsta, nlta = round(sta / 0.01), round(lta / 0.01) + for lane in range(da.sizes["distance"]): + expected = recursive_sta_lta(da.values[:, lane], nsta, nlta) + np.testing.assert_array_equal(result.values[:, lane], expected) + + @pytest.mark.parametrize("sta, lta", [(0.5, 10.0), (0.21, 3.0)]) + def test_classic_matches_obspy(self, sta, lta): + from obspy.signal.trigger import classic_sta_lta + + da = generate_stalta() + result = STALTA(sta, lta, method="classic")(da) + nsta, nlta = round(sta / 0.01), round(lta / 0.01) + for lane in range(da.sizes["distance"]): + expected = classic_sta_lta(da.values[:, lane], nsta, nlta) + np.testing.assert_allclose(result.values[:, lane], expected, rtol=1e-10) + # the same zero warm-up, sample for sample + np.testing.assert_array_equal(result.values[:, lane] == 0, expected == 0) + + @pytest.mark.parametrize("method", BOXCAR_METHODS) + @pytest.mark.parametrize("sta, lta", [(0.5, 10.0), (0.2, 3.0)]) + def test_boxcar_matches_direct_sums(self, method, sta, lta): + da = generate_stalta() + result = STALTA(sta, lta, method=method)(da) + nsta, nlta = round(sta / 0.01), round(lta / 0.01) + expected = boxcar_reference(da.values[:, 0], nsta, nlta, method) + np.testing.assert_allclose(result.values[:, 0], expected, rtol=1e-10) + + @pytest.mark.parametrize("method", STALTA_METHODS) + def test_dim_on_any_axis(self, method): + da = generate_stalta() + expected = STALTA(0.5, 10.0, method=method)(da) + result = STALTA(0.5, 10.0, method=method)(da.transpose("distance", "time")) + assert result.dims == ("distance", "time") + np.testing.assert_array_equal(result.values, expected.values.T) - def test_causal_holds_nothing_back(self): + @pytest.mark.parametrize("method", STALTA_METHODS) + def test_chunk_invariant(self, method): + da = generate_stalta() + atom = STALTA(0.5, 10.0, method=method) + xd.testing.assert_chunk_invariant(atom, da, chunks={"time": 1000}, gaps=2) + # chunks far shorter than the long window, and than what "centered" + # holds back + xd.testing.assert_chunk_invariant(atom, da, chunks={"time": 37}, cuts=0) + + @pytest.mark.parametrize("method", STALTA_METHODS) + def test_chunked_along_another_dim(self, method): + da = generate_stalta() + expected = STALTA(0.5, 10.0, method=method)(da) + result = STALTA(0.5, 10.0, method=method).process(da, chunks={"distance": 1}) + np.testing.assert_array_equal(result.values, expected.values) + + @pytest.mark.parametrize("method", STALTA_METHODS) + def test_scale_invariant(self, method): + # DAS strain rates are ~1e-9: their energy must not hit the floor + da = generate_stalta() + expected = STALTA(0.5, 10.0, method=method)(da).values + result = STALTA(0.5, 10.0, method=method)(da * 1e-9).values + np.testing.assert_allclose(result, expected, rtol=1e-9) + + @pytest.mark.parametrize("method", BOXCAR_METHODS) + def test_round_off_does_not_outlive_a_loud_transient(self, method): + # A burst 1e9 times louder than what follows: a cumulative sum keeps + # its round-off for the rest of the trace, the running sums for at + # most two windows. + da = generate_stalta(nt=12000, nx=1) + data = da.values.copy() + data[2000:2100] *= 1e6 + data[3000:] *= 1e-3 + da = da.copy(data=data) + nsta, nlta = 50, 1000 + result = STALTA(0.5, 10.0, method=method)(da).values[:, 0] + expected = boxcar_reference(data[:, 0], nsta, nlta, method) + clean = slice(2100 + 2 * (nsta + nlta), None) + np.testing.assert_allclose(result[clean], expected[clean], rtol=1e-8) + + @pytest.mark.parametrize("method", ["recursive", "classic", "delayed"]) + def test_causal_methods_ignore_the_future(self, method): da = generate_stalta() - atom = STALTA(sta=0.02, lta=0.5, mode="causal") - assert run_chunked(atom, da, 4).sizes["time"] == da.sizes["time"] + expected = STALTA(0.5, 10.0, method=method)(da).values + data = da.values.copy() + data[2500:] = 100.0 + result = STALTA(0.5, 10.0, method=method)(da.copy(data=data)).values + np.testing.assert_array_equal(result[:2500], expected[:2500]) + assert not np.array_equal(result[2500:], expected[2500:]) + + @pytest.mark.parametrize("method", ["recursive", "classic", "delayed"]) + def test_causal_methods_hold_nothing_back(self, method): + da = generate_stalta() + atom = STALTA(0.5, 10.0, method=method) + for chunk in xd.split(da, 7, dim="time"): + out = atom(chunk, chunk_dim="time") + assert out.sizes["time"] == chunk.sizes["time"] assert atom.flush() == [] - def test_centered_holds_back_and_flushes(self): + def test_centered_holds_back_half_the_long_window(self): da = generate_stalta() - atom = STALTA(sta=0.02, lta=0.5, mode="centered") + atom = STALTA(0.5, 10.0, method="centered") outs = [atom(chunk, chunk_dim="time") for chunk in xd.split(da, 4, dim="time")] emitted = xd.concat(outs, "time").sizes["time"] - assert emitted < da.sizes["time"] + assert emitted == da.sizes["time"] - 1000 // 2 (tail,) = atom.flush() - assert emitted + tail.sizes["time"] == da.sizes["time"] + assert tail.sizes["time"] == 1000 // 2 + np.testing.assert_array_equal(tail.values, 0.0) + assert atom.flush() == [] - def test_causal_onset_is_later_than_centered(self): + def test_centered_onset_is_earlier_than_causal(self): da = generate_stalta() - causal = STALTA(sta=0.02, lta=0.5, mode="causal")(da) - centered = STALTA(sta=0.02, lta=0.5, mode="centered")(da) + causal = STALTA(0.5, 10.0, method="classic")(da) + centered = STALTA(0.5, 10.0, method="centered")(da) assert int(causal.values[:, 0].argmax()) > int(centered.values[:, 0].argmax()) - def test_twin_and_pipeline(self): - da = generate_stalta() - assert np.allclose( - xd.stalta(da, sta=0.02, lta=0.5).values, - STALTA(sta=0.02, lta=0.5)(da).values, - ) - assert isinstance(xd.stalta(..., sta=0.02, lta=0.5), STALTA) - picks = da >> (xd.stalta(..., sta=0.02, lta=0.5) >> xd.trigger(..., thresh=8.0)) - assert len(picks) > 0 - - def test_window_and_pad_mode(self): - da = generate_stalta() - hann = STALTA(sta=0.02, lta=0.5, window="hann")(da) - boxcar = STALTA(sta=0.02, lta=0.5, window="boxcar")(da) - assert not np.allclose(hann.values, boxcar.values) - edge = STALTA(sta=0.02, lta=0.5, pad_mode="edge")(da) - assert not np.allclose(edge.values, boxcar.values) - - @pytest.mark.parametrize("mode", ["causal", "centered"]) - def test_record_shorter_than_the_halo(self, mode): - # The whole stream fits inside the window: nothing is ever emitted by - # `call`, and `flush` pads both ends as the ends of the record. - da = generate_stalta(nt=60) - expected = STALTA(sta=0.02, lta=0.5, mode=mode)(da) - result = run_chunked(STALTA(sta=0.02, lta=0.5, mode=mode), da, 4) - assert np.allclose(result.values, expected.values) + @pytest.mark.parametrize("method", STALTA_METHODS) + def test_record_shorter_than_the_windows(self, method): + # nothing is ever complete: all zeros, chunked or not + da = generate_stalta(nt=300) + expected = STALTA(0.5, 10.0, method=method)(da) + np.testing.assert_array_equal(expected.values, 0.0) + result = STALTA(0.5, 10.0, method=method).process(da, chunks={"time": 40}) + np.testing.assert_array_equal(result.values, expected.values) def test_flush_without_data_is_empty(self): - # Uninitialised, and initialised by an eager (unchunked) call: neither - # holds anything back. - atom = STALTA(sta=0.02, lta=0.5, mode="centered") + # uninitialised, and initialised by an eager (unchunked) call: neither + # holds anything back + atom = STALTA(0.5, 10.0, method="centered") assert atom.flush() == [] atom(generate_stalta()) assert atom.flush() == [] + def test_twin_and_pipeline(self): + da = generate_stalta() + np.testing.assert_array_equal( + xd.stalta(da, sta=0.5, lta=10.0).values, STALTA(0.5, 10.0)(da).values + ) + assert isinstance(xd.stalta(..., sta=0.5, lta=10.0), STALTA) + picks = da >> (xd.stalta(..., sta=0.5, lta=10.0) >> xd.trigger(..., thresh=5.0)) + assert len(picks) > 0 + def test_invalid_parameters(self): + with pytest.raises(ValueError, match="`method` must be one of"): + STALTA(0.5, 10.0, method="causal") with pytest.raises(ValueError, match="strictly positive"): - STALTA(sta=0.0, lta=1.0) + STALTA(0.0, 1.0) with pytest.raises(ValueError, match="longer than"): - STALTA(sta=1.0, lta=0.5) - with pytest.raises(ValueError, match="causal.*centered"): - STALTA(sta=0.02, lta=0.5, mode="acausal") + STALTA(1.0, 0.5) + da = generate_stalta() + with pytest.raises(ValueError, match="shorter than one sample"): + STALTA(0.004, 10.0)(da) + with pytest.raises(ValueError, match="more samples than"): + STALTA(0.5, 0.504)(da) diff --git a/xdas/atoms/detect.py b/xdas/atoms/detect.py index 90f9fb83..42f2098f 100644 --- a/xdas/atoms/detect.py +++ b/xdas/atoms/detect.py @@ -12,7 +12,6 @@ import numpy as np import pandas as pd -import scipy.signal as sp from numba import njit from ..coordinates import Coordinate, get_sampling_interval @@ -602,17 +601,39 @@ class STALTA(Atom): """ Short-term over long-term average characteristic function. - The ratio of a short trailing (or centred) mean of the squared signal to a - long one: the classic amplitude detector, whose output is fed to - :class:`Trigger` to obtain picks. Both window lengths are given in the - physical units of `dim`, so the same atom applies to any sampling rate. - - Stateful: the trailing samples the next window will need are carried - across chunks, so chunked processing returns exactly what a single call on - the whole record returns. In ``"centered"`` mode a window also reaches - forward, so each call holds back the samples it cannot yet complete and - :meth:`flush` releases them at the end of the stream. In ``"causal"`` mode - nothing is held back and :meth:`flush` has nothing to return. + The ratio of a short mean of the squared signal to a long one: the classic + amplitude detector, whose output is fed to :class:`Trigger` to obtain + picks. Both window lengths are given in the physical units of `dim`, so + the same atom applies to any sampling rate. + + The ``recursive`` and ``classic`` methods follow their ObsPy counterparts + of :mod:`obspy.signal.trigger` sample for sample, including the samples + reported as zero while the windows are not yet full. All methods are + computed by running sums carried from chunk to chunk, so chunked processing + returns exactly what a single call on the whole record returns, at a cost + that does not depend on the window lengths. + + ============== ========================================================== + method definition + ============== ========================================================== + ``recursive`` Exponential averages of time constants `sta` and `lta` + (Evans and Allen), as ObsPy's ``recursive_sta_lta``. + The default, and the cheapest to stream: its state is two + numbers per channel. + ``classic`` Trailing boxcar means, as ObsPy's ``classic_sta_lta``. + ``delayed`` Trailing boxcar means, the long window ending where the + short one starts so that a transient does not raise its + own reference (Withers et al., 1998). + ``centered`` Boxcar means centred on the sample they produce, so the + peak sits on the transient, but each window reaches `lta` / + 2 into the future: + offline only, the samples it cannot yet complete being + held back until :meth:`flush`. + ============== ========================================================== + + The choice moves pick times, so it is a property of the detector, not a + tuning knob: the peak of a trailing boxcar lags the transient by about half + the short window, that of ``centered`` does not. Parameters ---------- @@ -621,24 +642,29 @@ class STALTA(Atom): lta : float Length of the long-term window, in the units of `dim`. Must be longer than `sta`. - mode : {"causal", "centered"}, optional - Where each window sits relative to the sample it produces. - ``"causal"`` (default) averages the samples up to and including it, as - a real-time detector must; the onset of a transient is then reported - late by roughly half the short window. ``"centered"`` averages - symmetrically about it, which sharpens the onset but needs samples - from the future, and so is only available offline. The choice shifts - pick times, so it is a property of the detector, not a tuning knob. - window : str, optional - Tapering window applied to both means, by default "boxcar" — the plain - running mean. Any window accepted by :func:`scipy.signal.get_window`. - pad_mode : str, optional - How the two ends of the *record* are extended where a window would - reach past them, by default "reflect". Chunk seams are never padded: - they use the real neighbouring samples. + method : {"recursive", "classic", "delayed", "centered"}, optional + How the two averages are computed, by default "recursive". dim : str, optional The dimension along which to compute the ratio, by default "time". + Notes + ----- + Samples whose windows are incomplete — the start of each run, and with + ``"centered"`` its end too — are zero, which no positive threshold + triggers on. The boxcar sums are recomputed from scratch once per window, + so the round-off of a loud transient does not outlive two windows (the + cumulative sum of ObsPy's ``classic_sta_lta`` keeps it for the rest of the + trace). ObsPy's ``delayed_sta_lta`` is not used as a reference: as of + ObsPy 1.5 it adds the samples leaving its windows instead of subtracting + them. + + References + ---------- + Withers, M., Aster, R., Young, C., Beiriger, J., Harris, M., Moore, S., + and Trujillo, J. (1998). A comparison of select trigger algorithms for + automated global seismic phase and event detection. Bulletin of the + Seismological Society of America, 88(1), 95-106. + Examples -------- >>> import numpy as np @@ -664,10 +690,8 @@ class STALTA(Atom): Chunked processing gives the same answer, seam for seam: >>> atom = xd.stalta(..., sta=1.0, lta=20.0) - >>> chunks = [atom(chunk, chunk_dim="time") - ... for chunk in xd.split(da, 8, dim="time")] - >>> chunked = xd.concat(chunks + list(atom.flush()), "time") - >>> bool(np.allclose(chunked.values, cft.values)) + >>> chunked = atom.process(da, chunks={"time": 250}) + >>> bool(np.array_equal(chunked.values, cft.values)) True Piped into the trigger, which is the point of it: @@ -676,104 +700,216 @@ class STALTA(Atom): """ - def __init__( - self, sta, lta, mode="causal", window="boxcar", pad_mode="reflect", dim="time" - ): + def __init__(self, sta, lta, method="recursive", dim="time"): super().__init__() + if method not in _STALTA_METHODS: + raise ValueError( + f"`method` must be one of {', '.join(map(repr, _STALTA_METHODS))}" + ) if not sta > 0.0: raise ValueError("`sta` must be strictly positive") if not lta > sta: raise ValueError("`lta` must be longer than `sta`") - if mode not in ("causal", "centered"): - raise ValueError("`mode` must be either 'causal' or 'centered'") self.sta = float(sta) self.lta = float(lta) - self.mode = mode - self.window = window - self.pad_mode = pad_mode + self.method = method self.dim = dim # states - self.fs = State(...) + self.delta = State(...) + self.count = State(...) + self.sums = State(...) + self.ring = State(...) self.buffer = State(...) - self.skip = State(...) def initialize(self, da, chunk_dim=None, **flags): - """Measure the sampling rate to size the windows, and open the buffer.""" - self.fs = State(1.0 / get_sampling_interval(da, self.dim)) + """Measure the sampling interval to size the windows, and zero the sums.""" + self.delta = State(float(get_sampling_interval(da, self.dim))) self.initialize_from_state() - self.skip = State(0) + lanes = da.size // da.sizes[self.dim] + self.count = State(0) + self.sums = State(self._fresh_sums(lanes)) + self.ring = State(np.zeros((lanes, self.history))) + # `None` marks a whole record per call (no seam along `dim` to cross) if chunk_dim == self.dim: self.buffer = State(da.isel({self.dim: slice(0, 0)})) else: self.buffer = State(None) def initialize_from_state(self): - """Derive the window lengths, in samples, from the sampling rate.""" - self.sta_n = _oddify(self.sta * self.fs, 3) - self.lta_n = _oddify(self.lta * self.fs, self.sta_n + 2) - if self.mode == "causal": - self.lookback, self.lookahead = self.lta_n - 1, 0 + """Derive the window lengths and offsets, in samples.""" + self.nsta = round(self.sta / self.delta) + self.nlta = round(self.lta / self.delta) + if self.nsta < 1: + raise ValueError("`sta` is shorter than one sample") + if not self.nlta > self.nsta: + raise ValueError("`lta` must span more samples than `sta`") + # each boxcar window ends `delay` samples before the newest one + self.lag = 0 + match self.method: + case "delayed": + self.dsta, self.dlta = 0, self.nsta + case "centered": + self.lag = self.nlta // 2 + self.dsta, self.dlta = self.lag - self.nsta // 2, 0 + case _: + self.dsta = self.dlta = 0 + if self.method == "recursive": + self.start, self.history = self.nlta, 0 else: - self.lookback = self.lookahead = self.lta_n // 2 + reach = max(self.nsta + self.dsta, self.nlta + self.dlta) + self.start, self.history = reach - 1, reach + 1 def call(self, da, **flags): - """Emit the ratio for every sample whose windows are complete.""" - if self.buffer is None: # whole record: both ends are record ends - return self._ratio(da) + """Emit the ratio for every sample the stream so far determines.""" + if self.buffer is None: # whole record: start afresh, end with the tail + lanes = da.size // da.sizes[self.dim] + self.count = State(0) + self.sums = State(self._fresh_sums(lanes)) + self.ring = State(np.zeros((lanes, self.history))) + shifted = self._advance(da)[..., self.lag :] + values = np.zeros(shifted.shape[:-1] + (da.sizes[self.dim],)) + values[..., : shifted.shape[-1]] = shifted + return da.copy(data=self._unlane(values, da)) + values = self._advance(da) x = concat([self.buffer, da], self.dim) if self.buffer.sizes[self.dim] else da - size = x.sizes[self.dim] - if size <= self.lookback + self.lookahead: - # Too little of the record has arrived to extend its start the way - # a single call would: hold everything and emit nothing yet. - self.buffer = State(x) + # the newest `lag` samples stay held back: their windows reach samples + # yet to come + emit = max(x.sizes[self.dim] - self.lag, 0) + self.buffer = State(x.isel({self.dim: slice(emit, None)})) + if not emit: return [] - stop = size - self.lookahead - out = self._ratio(x).isel({self.dim: slice(self.skip, stop)}) - keep = self.lookback + self.lookahead - self.buffer = State(x.isel({self.dim: slice(size - keep, None)})) - self.skip = State(stop - (size - keep)) - return out + values = values[..., values.shape[-1] - emit :] + out = x.isel({self.dim: slice(0, emit)}) + return out.copy(data=self._unlane(values, out)) def flush(self): - """Release the held-back tail, padded as the end of a record.""" + """Release the held-back tail, zero since its windows run off the record.""" # Not `self.buffer is None`: a flush also reaches an atom that was # never chunked (buffer `None`) or never called at all (buffer `...`). - if not isinstance(self.buffer, DataArray): - return [] - if self.skip >= self.buffer.sizes[self.dim]: + if not isinstance(self.buffer, DataArray) or not self.buffer.sizes[self.dim]: return [] - return [self._ratio(self.buffer).isel({self.dim: slice(self.skip, None)})] - - def _ratio(self, da): - """Compute the ratio of the two windowed means over a whole block.""" - axis = da.get_axis_num(self.dim) - energy = np.square(np.asarray(da.values, dtype=float)) - sta = self._mean(energy, self.sta_n, axis) - lta = self._mean(energy, self.lta_n, axis) - np.maximum(lta, np.finfo(float).eps, out=lta) - return da.copy(data=sta / lta) - - def _mean(self, energy, size, axis): - """Windowed mean of `energy`, placed according to `mode`.""" - weights = sp.get_window(self.window, size).astype(float) - weights /= weights.sum() - shape = tuple(-1 if a == axis else 1 for a in range(energy.ndim)) - if self.mode == "causal": - before, after = size - 1, 0 + tail = self.buffer.copy(data=np.zeros(self.buffer.shape)) + self.buffer = State(self.buffer.isel({self.dim: slice(0, 0)})) + return [tail] + + def _fresh_sums(self, lanes): + """Return the initial running sums, two per lane, ObsPy's for "recursive".""" + sums = np.zeros((lanes, 2)) + if self.method == "recursive": + sums[:, 1] = _TINY + return sums + + def _advance(self, da): + """Feed one block to the kernel, returning its ratios lane by lane.""" + values = np.moveaxis(np.asarray(da.values), da.get_axis_num(self.dim), -1) + energy = np.square(values.reshape(-1, values.shape[-1]), dtype=float) + # the kernels update the sums and the ring in place + if self.method == "recursive": + out = _recursive_ratio(energy, self.sums, self.count, self.nsta, self.nlta) else: - before = after = size // 2 - pad = tuple( - (before, after) if a == axis else (0, 0) for a in range(energy.ndim) - ) - padded = np.pad(energy, pad, mode=self.pad_mode) - return sp.fftconvolve(padded, weights.reshape(shape), mode="valid") + out = _boxcar_ratio( + energy, + self.sums, + self.ring, + self.count, + self.nsta, + self.dsta, + self.nlta, + self.dlta, + self.start, + ) + self.count = State(self.count + energy.shape[-1]) + return out + def _unlane(self, values, like): + """Fold lane-by-lane ratios back into the layout of `like`.""" + axis = like.get_axis_num(self.dim) + shape = np.moveaxis(np.empty(like.shape, dtype=bool), axis, -1).shape + return np.moveaxis(values.reshape(shape), -1, axis) -def _oddify(size, floor): - """Round a window length to an odd number of samples, at least `floor`.""" - size = max(floor, round(float(size))) - return size if size % 2 else size + 1 + +_STALTA_METHODS = ("recursive", "classic", "delayed", "centered") + +#: The floor of the long-term average, ObsPy's: smallest normal float64. +_TINY = np.finfo(np.float64).tiny + + +@njit(cache=True) +def _recursive_ratio(energy, sums, count, nsta, nlta): # pragma: no cover + """ + Evans and Allen recursive STA/LTA, resumable, as ObsPy's. + + `sums` holds the two averages of each lane and is updated in place; + `count` is the index, in the run, of the first sample of `energy`. + """ + csta = 1.0 / nsta + clta = 1.0 / nlta + icsta = 1.0 - csta + iclta = 1.0 - clta + lanes, size = energy.shape + out = np.zeros((lanes, size)) + for lane in range(lanes): + sta = sums[lane, 0] + lta = sums[lane, 1] + for j in range(size): + t = count + j + if t == 0: # ObsPy's recursion starts at the second sample + continue + sta = csta * energy[lane, j] + icsta * sta + lta = clta * energy[lane, j] + iclta * lta + if t >= nlta: + out[lane, j] = sta / max(lta, _TINY) + sums[lane, 0] = sta + sums[lane, 1] = lta + return out + + +@njit(cache=True) +def _boxcar_ratio( + energy, sums, ring, count, nsta, dsta, nlta, dlta, start +): # pragma: no cover + """ + Ratio of two boxcar means, resumable. + + Each window spans `n` samples and ends `d` samples before the newest one. + `ring` keeps the last ``ring.shape[1]`` energies of each lane and `sums` + the two running sums, both updated in place; `count` is the index, in the + run, of the first sample of `energy`. Samples before `start` are zero. + """ + lanes, size = energy.shape + out = np.zeros((lanes, size)) + for lane in range(lanes): + ssta = sums[lane, 0] + slta = sums[lane, 1] + for j in range(size): + t = count + j + ring[lane, t % ring.shape[1]] = energy[lane, j] + ssta = _slide(ring[lane], ssta, t - dsta, nsta) + slta = _slide(ring[lane], slta, t - dlta, nlta) + if t >= start: + out[lane, j] = (ssta / nsta) / max(slta / nlta, _TINY) + sums[lane, 0] = ssta + sums[lane, 1] = slta + return out + + +@njit(cache=True) +def _slide(ring, total, last, n): # pragma: no cover + """Move a running sum of `n` samples to the window ending at `last`.""" + if last < 0: + return 0.0 + size = ring.shape[0] + # once per window, sum from scratch: what sliding accumulated is dropped + if (last + 1) % n == 0: + total = 0.0 + for k in range(last - n + 1, last + 1): + total += ring[k % size] + return total + total += ring[last % size] + if last >= n: + total -= ring[(last - n) % size] + return total stalta = atomized(STALTA) From bb4b5ba0bada34a1206dd66435d874bba5ddd199 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Fri, 16 Oct 2026 11:58:03 +0200 Subject: [PATCH 4/7] docs(detect): document the STA/LTA methods --- docs/release-notes.md | 2 +- docs/user-guide/pipeline/atoms.md | 2 +- docs/user-guide/pipeline/picking.md | 46 +++++++++++++++++------------ 3 files changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/release-notes.md b/docs/release-notes.md index 9ac2f24b..c38ba6dd 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -3,7 +3,7 @@ ## 0.2.10 (unreleased) ### New Features -- **`xdas.stalta`**, the short-term over long-term average characteristic function, feeding the existing `Trigger` so that detection no longer needs a model. Both windows are given in the units of the dimension, `mode="causal"` (default) or `"centered"` places them relative to the sample they produce, and the atom is stateful: chunked processing returns what a single call on the whole record returns, `flush()` releasing the tail `"centered"` mode holds back (@amaggi). +- **`xdas.stalta`**, the short-term over long-term average characteristic function, feeding the existing `Trigger` so that detection no longer needs a model. Both windows are given in the units of the dimension. `method="recursive"` (default) and `"classic"` reproduce ObsPy's `recursive_sta_lta` and `classic_sta_lta` sample for sample, `"delayed"` ends the long window where the short one starts, and `"centered"` centres both windows for offline use. The atom is stateful and streams at a cost independent of the window lengths: chunked processing returns what a single call on the whole record returns, `flush()` releasing the tail `"centered"` holds back (@amaggi, @atrabattoni). - **Aragon Photonics HDAS support.** The new `aragon` engine reads HDAS 3.0 `HDAS_StrainRate` HDF5 files, returning samples as stored. The time axis keeps the device stamps (to their float64 resolution) and declares the header sampling interval with the smallest tolerance they allow; `ctype={"time": "sampled"}` steps at the header interval and `"dense"` keeps every stamp. The distance axis comes from the header. HDF5 and tile virtualization (@atrabattoni). - Add a `"fosina"` alias of the `"prodml"` engine, and list in the user guide the instruments known to write ProdML (@atrabattoni). diff --git a/docs/user-guide/pipeline/atoms.md b/docs/user-guide/pipeline/atoms.md index 2834a51b..539ab146 100644 --- a/docs/user-guide/pipeline/atoms.md +++ b/docs/user-guide/pipeline/atoms.md @@ -86,7 +86,7 @@ energy | {py:func}`~xdas.hilbert` | analytic signal | | {py:func}`~xdas.medfilt`, {py:func}`~xdas.sliding_mean_removal` | kernels in seconds or meters | | {py:func}`~xdas.rechunk` | a streaming-cadence knob, not an operation | -| {py:func}`~xdas.stalta` | short-term over long-term average, windows in seconds | +| {py:func}`~xdas.stalta` | short-term over long-term average (ObsPy's recursive, classic, delayed, or centered), windows in seconds | | {py:func}`~xdas.annotate`, {py:func}`~xdas.trigger`, {py:func}`~xdas.pick` | detection and picking (see [](picking.md)) | Each has an atom behind it — {py:class}`~xdas.atoms.Filter`, diff --git a/docs/user-guide/pipeline/picking.md b/docs/user-guide/pipeline/picking.md index 85bb3431..50e6314e 100644 --- a/docs/user-guide/pipeline/picking.md +++ b/docs/user-guide/pipeline/picking.md @@ -292,11 +292,11 @@ two implementations on identical waveforms. ## Detecting without a model Not every detection needs a network of weights. {py:func}`~xdas.stalta` is the -classic amplitude detector — a short trailing average of the squared signal -over a long one — and it feeds the very same {py:class}`~xdas.atoms.Trigger`, -so the pick table and everything downstream of it are unchanged. Both window -lengths are given in the units of the dimension, seconds here, so the same atom -applies whatever the sampling rate: +classic amplitude detector — a short average of the squared signal over a long +one — and it feeds the very same {py:class}`~xdas.atoms.Trigger`, so the pick +table and everything downstream of it are unchanged. Both window lengths are +given in the units of the dimension, seconds here, so the same atom applies +whatever the sampling rate: ```{code-cell} import numpy as np @@ -316,30 +316,38 @@ noisy = xd.DataArray( }, ) -xd.trigger(xd.stalta(noisy, sta=0.5, lta=10.0), thresh=8.0) +xd.trigger(xd.stalta(noisy, sta=0.5, lta=10.0), thresh=4.0) ``` -The transient starts at 20 s and is picked a little after it: a causal detector -only ever sees the past, so it reports an onset late by roughly half the short -window. That is the default, and the only mode a real-time detector can use. -Offline, `mode="centered"` averages symmetrically about the sample it produces, -which sharpens the onset at the price of needing samples from the future: +The default `method="recursive"` is the Evans and Allen exponential average, +and `"classic"` the trailing boxcar one: both reproduce their +[ObsPy](https://docs.obspy.org/packages/autogen/obspy.signal.trigger.html) +counterparts sample for sample, including the zeros reported while the long +window is not yet full. `"delayed"` ends the long window where the short one +starts, so that a transient does not raise its own reference. + +All three are causal: they only ever see the past, and they are the methods a +real-time detector can use. Their peak trails the transient — by about half +the short window for the boxcar ones, which only peak once that window is full +of it. Offline, `method="centered"` averages symmetrically about the sample it +produces, which brings the peak back onto the transient at the price of +needing samples from the future: ```{code-cell} -xd.trigger(xd.stalta(noisy, sta=0.5, lta=10.0, mode="centered"), thresh=8.0) +xd.trigger(xd.stalta(noisy, sta=0.5, lta=10.0, method="centered"), thresh=4.0) ``` The choice moves pick times, so it is a property of the detector rather than a -tuning knob — the same threshold on the same record gives different times under -the two modes. +tuning knob — the same threshold on the same record gives different times +under different methods. Like every atom, it is stateful: an hour arriving in ten-second chunks gives -exactly what the hour gives in one piece, seam for seam. In `"centered"` mode -the samples whose window is not yet complete are held back, and `flush()` -releases them at the end of the stream — which the streaming machinery of -[](processing.md) calls for you: +exactly what the hour gives in one piece, seam for seam, at a cost that does +not depend on the window lengths. With `"centered"` the samples whose window is +not yet complete are held back, and `flush()` releases them at the end of the +stream — which the streaming machinery of [](processing.md) calls for you: ```{code-cell} -pipeline = xd.stalta(..., sta=0.5, lta=10.0) >> xd.trigger(..., thresh=8.0) +pipeline = xd.stalta(..., sta=0.5, lta=10.0) >> xd.trigger(..., thresh=4.0) pipeline.process(noisy, chunks={"time": 500}) ``` From 847f117e45a5ab1f5f24f7d915088396e1ac8d44 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Fri, 16 Oct 2026 12:32:27 +0200 Subject: [PATCH 5/7] perf(detect): split STALTA across channels with parallelize Add parallel= like the other kernel atoms: nogil numba kernels split by lane through xdas.parallel.parallelize, the pool sized by the samples processed rather than by the carried ring (which a streamed chunk barely touches). Lay the energy out in C order: on time-first data moveaxis left it strided and the kernels missed cache on every sample (classic 6x slower). --- tests/test_atoms_detect.py | 11 +++++++++++ xdas/atoms/detect.py | 26 ++++++++++++++++++-------- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/tests/test_atoms_detect.py b/tests/test_atoms_detect.py index 9fb29b76..9c85ed6f 100644 --- a/tests/test_atoms_detect.py +++ b/tests/test_atoms_detect.py @@ -636,6 +636,17 @@ def test_flush_without_data_is_empty(self): atom(generate_stalta()) assert atom.flush() == [] + @pytest.mark.parametrize("method", STALTA_METHODS) + def test_parallel_matches_serial(self, method): + # each worker updates its own slice of lanes of the carried sums + da = generate_stalta(nx=7) + expected = STALTA(0.5, 10.0, method=method, parallel=False)(da) + result = STALTA(0.5, 10.0, method=method, parallel=3)(da) + np.testing.assert_array_equal(result.values, expected.values) + atom = STALTA(0.5, 10.0, method=method, parallel=3) + chunked = atom.process(da, chunks={"time": 2500}) + np.testing.assert_array_equal(chunked.values, expected.values) + def test_twin_and_pipeline(self): da = generate_stalta() np.testing.assert_array_equal( diff --git a/xdas/atoms/detect.py b/xdas/atoms/detect.py index 42f2098f..0f2afeee 100644 --- a/xdas/atoms/detect.py +++ b/xdas/atoms/detect.py @@ -16,6 +16,7 @@ from ..coordinates import Coordinate, get_sampling_interval from ..core import DataArray, concat, concat_coords +from ..parallel import get_workers_count, parallelize from .core import Atom, State, atomized __all__ = ["STALTA", "Trigger", "stalta", "trigger"] @@ -646,6 +647,8 @@ class STALTA(Atom): How the two averages are computed, by default "recursive". dim : str, optional The dimension along which to compute the ratio, by default "time". + parallel : int, bool, or None, optional + Worker count for parallelisation across channels. Notes ----- @@ -700,7 +703,7 @@ class STALTA(Atom): """ - def __init__(self, sta, lta, method="recursive", dim="time"): + def __init__(self, sta, lta, method="recursive", dim="time", parallel=None): super().__init__() if method not in _STALTA_METHODS: raise ValueError( @@ -714,6 +717,7 @@ def __init__(self, sta, lta, method="recursive", dim="time"): self.lta = float(lta) self.method = method self.dim = dim + self.parallel = parallel # states self.delta = State(...) @@ -803,12 +807,18 @@ def _fresh_sums(self, lanes): def _advance(self, da): """Feed one block to the kernel, returning its ratios lane by lane.""" values = np.moveaxis(np.asarray(da.values), da.get_axis_num(self.dim), -1) - energy = np.square(values.reshape(-1, values.shape[-1]), dtype=float) - # the kernels update the sums and the ring in place + # C order: the kernels walk each lane along `dim`, which `moveaxis` strides + energy = np.square(values.reshape(-1, values.shape[-1]), dtype=float, order="C") + # the kernels update the sums and the ring in place, each worker its + # own slice of lanes; the pool is sized by the samples processed, not + # by the ring, which a call barely touches + parallel = get_workers_count(self.parallel, energy.nbytes) if self.method == "recursive": - out = _recursive_ratio(energy, self.sums, self.count, self.nsta, self.nlta) + func = parallelize((0, 0, None, None, None), 0, parallel)(_recursive_ratio) + out = func(energy, self.sums, self.count, self.nsta, self.nlta) else: - out = _boxcar_ratio( + func = parallelize((0, 0, 0) + (None,) * 6, 0, parallel)(_boxcar_ratio) + out = func( energy, self.sums, self.ring, @@ -835,7 +845,7 @@ def _unlane(self, values, like): _TINY = np.finfo(np.float64).tiny -@njit(cache=True) +@njit(nogil=True, cache=True) def _recursive_ratio(energy, sums, count, nsta, nlta): # pragma: no cover """ Evans and Allen recursive STA/LTA, resumable, as ObsPy's. @@ -865,7 +875,7 @@ def _recursive_ratio(energy, sums, count, nsta, nlta): # pragma: no cover return out -@njit(cache=True) +@njit(nogil=True, cache=True) def _boxcar_ratio( energy, sums, ring, count, nsta, dsta, nlta, dlta, start ): # pragma: no cover @@ -894,7 +904,7 @@ def _boxcar_ratio( return out -@njit(cache=True) +@njit(nogil=True, cache=True) def _slide(ring, total, last, n): # pragma: no cover """Move a running sum of `n` samples to the window ending at `last`.""" if last < 0: From e31f0edb51100e7450f0b074e416a4cb17ace171 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Fri, 16 Oct 2026 12:46:52 +0200 Subject: [PATCH 6/7] ci: run the workflows on pull requests Pushes to a fork fire the workflows in the fork, where Actions are off by default, so pull requests from forks were never tested. Trigger on pull_request too, and limit push to main and dev to avoid running twice for branches pushed to origin. --- .github/workflows/code-coverage.yaml | 5 ++++- .github/workflows/tests.yaml | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/code-coverage.yaml b/.github/workflows/code-coverage.yaml index 6f7ca3bf..14151ed2 100644 --- a/.github/workflows/code-coverage.yaml +++ b/.github/workflows/code-coverage.yaml @@ -1,6 +1,9 @@ name: Code Coverage -on: [push] +on: + push: + branches: [main, dev] + pull_request: jobs: test: diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index eca09ad2..c4400f67 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -1,6 +1,9 @@ name: tests -on: [push] +on: + push: + branches: [main, dev] + pull_request: jobs: build: From 340eb4db947e1c0939248dd7ef2b67eef9e10c48 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Fri, 16 Oct 2026 12:54:41 +0200 Subject: [PATCH 7/7] test(detect): compare recursive STALTA to ObsPy at round-off On macOS arm64 the compiler fuses the recursion's multiply-add in one of the two builds, so values differ in the last bits (relative 1e-15) and the bit-exact comparison failed on CI. --- tests/test_atoms_detect.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/tests/test_atoms_detect.py b/tests/test_atoms_detect.py index 9c85ed6f..f786b751 100644 --- a/tests/test_atoms_detect.py +++ b/tests/test_atoms_detect.py @@ -503,7 +503,7 @@ def boxcar_reference(x, nsta, nlta, method): class TestSTALTA: @pytest.mark.parametrize("sta, lta", [(0.5, 10.0), (0.21, 3.0)]) - def test_recursive_matches_obspy_exactly(self, sta, lta): + def test_recursive_matches_obspy(self, sta, lta): from obspy.signal.trigger import recursive_sta_lta da = generate_stalta() @@ -511,7 +511,10 @@ def test_recursive_matches_obspy_exactly(self, sta, lta): nsta, nlta = round(sta / 0.01), round(lta / 0.01) for lane in range(da.sizes["distance"]): expected = recursive_sta_lta(da.values[:, lane], nsta, nlta) - np.testing.assert_array_equal(result.values[:, lane], expected) + # the same recursion, but a compiler may fuse its multiply-add + # (arm64 does), so only round-off apart + np.testing.assert_allclose(result.values[:, lane], expected, rtol=1e-12) + np.testing.assert_array_equal(result.values[:, lane] == 0, expected == 0) @pytest.mark.parametrize("sta, lta", [(0.5, 10.0), (0.21, 3.0)]) def test_classic_matches_obspy(self, sta, lta):