Skip to content

Add STALTA characteristic-function atom - #86

Merged
atrabattoni merged 8 commits into
xdas-dev:devfrom
amaggi:feat/stalta
Oct 16, 2026
Merged

atrabattoni merged 8 commits into
xdas-dev:devfrom
amaggi:feat/stalta

Conversation

@amaggi

@amaggi amaggi commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Add an STALTA characteristic-function atom

Xdas has a threshold detector (Trigger) but nothing to feed it apart from a
SeisBench model. This adds the classic amplitude detector — the ratio of a
short-term to a long-term average of the squared signal — as an atom, so
detection no longer needs a network of weights:

picks = xd.trigger(xd.stalta(da, sta=0.5, lta=10.0), thresh=8.0)

or, as a pipeline that streams:

pipeline = xd.stalta(..., sta=0.5, lta=10.0) >> xd.trigger(..., thresh=8.0)
pipeline.process(source, out="picks.csv")

What it does

  • Windows in physical units. sta and lta are given in the units of
    dim, and the sample counts are derived in initialize from the measured
    sampling rate, the way operations.Filter does — so a parameter survives a
    change of rate.
  • Two placements. mode="causal" (default) averages the samples up to and
    including the one it produces, as a real-time detector must; mode="centered"
    averages symmetrically about it, which sharpens the onset but reaches into the
    future and so is offline only. The choice moves pick times, so it is a
    property of the detector rather than a tuning knob.
  • window and pad_mode for the taper applied to both means and for how
    the two ends of the record are extended. Chunk seams are never padded: they
    use the real neighbouring samples.
  • Chunk-invariant. State carries the halo the next window needs, so a
    chunked run returns exactly what a single call on the whole record returns —
    tested over 2, 5, 17 and 200 chunks in both modes, and for a record shorter
    than the halo. In "centered" mode the samples whose window is not yet
    complete are held back and flush() releases them; in "causal" mode nothing
    is held back and flush() has nothing to return.

Notes for review

  • Nothing is added to Trigger. It already turns a characteristic function
    into picks, statefully, and does it well; this only supplies another kind of
    input to it.
  • recursive_sta_lta is deliberately left out. The recursive form is a
    different (and genuinely streaming-native) estimator, and belongs in its own
    PR rather than as a method= flag bolted on here.
  • STALTA does not survive save_state/load_state. Its buffer is a
    DataArray, and Atom.set_state converts a DataArray state to a bare
    ndarray (xdas/atoms/core.py, the # TODO: shouldn't need __array__ line),
    so the coordinates are lost. This is the same limitation DownSample,
    Rechunk and Polyphase already have — the two commented-out round-trip
    tests in tests/test_atoms.py are about exactly this — so I have not worked
    around it here. Happy to take it on as a follow-up if you want the state
    machinery finished.

Checks

  • ruff check and ruff format clean.
  • xdas/atoms/detect.py at 100% coverage bar one pre-existing line
    (Trigger.merge's empty-table branch, covered by test_atoms_ml.py).
  • Docs build with no new warnings; the new user-guide section executes.
  • Full suite green, with two caveats that are not from this branch and
    reproduce on a clean dev on macOS arm64:
    • tests/test_signal.py::TestSTFT::test_parrallel and
      tests/virtual/test_tiles.py::TestStoredForm::test_non_utf8_root_survives_the_header
      fail on dev as they do here.
    • The interpreter segfaults when tests/test_picking.py runs in the same
      process as anything that has imported torch (tests/test_atoms_ml.py, but
      also dascore/seisbench pulled in elsewhere) — torch's OpenMP against
      numba's @njit(parallel=True) in xdas/picking.py. Neither
      KMP_DUPLICATE_LIB_OK=TRUE nor NUMBA_NUM_THREADS=1 helps. Running
      tests/test_picking.py in its own process is the workaround; worth a
      separate issue.

amaggi and others added 6 commits September 3, 2026 19:42
… 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).
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).

@atrabattoni atrabattoni left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @amaggi, thanks for this, STA/LTA feeding straight into Trigger is really useful.

I compared it with ObsPy and ran into a few issues, so I pushed three commits on top of yours:

  • the LTA is floored at eps, which is too high for DAS data in strain rate (values around 1e-9): the ratio drops to ~0.004
  • after a strong event, the fftconvolve round-off gives absurd ratios in the quiet part that follows
  • in causal mode, the reflect padding at the start uses future samples
  • in streaming, each chunk re-convolves the whole buffer, so it gets very slow with small chunks (54x slower than one call on 1 s chunks)

I replaced mode/window/pad_mode with a method argument that follows ObsPy: "recursive" (now the default, same values as recursive_sta_lta), "classic" (matches classic_sta_lta), "delayed", and I kept your "centered" mode for offline use. Under the hood it's now running sums in numba, so the cost doesn't depend on the window lengths anymore and chunked results are identical to a single call. I also added parallel= like the other filters, and tests against ObsPy.

Side note: ObsPy's delayed_sta_lta looks buggy (it adds the leaving samples instead of subtracting them), so I tested that one against plain window sums.

These changes shouldn't affect your code, so I'll merge it as is.

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.
@codecov

codecov Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (017cb74) to head (340eb4d).

Additional details and impacted files
@@            Coverage Diff            @@
##               dev       #86   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           49        49           
  Lines         9293      9391   +98     
  Branches      1680      1694   +14     
=========================================
+ Hits          9293      9391   +98     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

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.
@atrabattoni
atrabattoni merged commit ddfdf1d into xdas-dev:dev Oct 16, 2026
9 checks passed
@amaggi
amaggi deleted the feat/stalta branch October 19, 2026 07:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants