Better Atoms: a functional form for every atom, on a new physical-unit vocabulary

docs/api/atoms.md

@@ -32,7 +32,12 @@ Methods
    Atom.initialize
    Atom.initialize_from_state
    Atom.call
+   Atom.flush
    Atom.reset
+   Atom.process
+   Atom.iter_chunks
+   Atom.gather
+   Atom.merge
    Atom.save_state
    Atom.set_state
    Atom.load_state
@@ -75,13 +80,65 @@ Methods
    Partial.get_state
 ```
 
-## Decorators
+## Decorators and composition
 
 ```{eval-rst}
 .. autosummary::
    :toctree: ../_autosummary
 
+   as_function
    atomized
+   compose
+```
+
+## Task atoms
+
+Public processing vocabulary with physical parameters only.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: ../_autosummary
+
+   Decimate
+   Differentiate
+   Filter
+   Integrate
+   Resample
+   STFT
+```
+
+## Function forms
+
+Every atom has a function form exported at the top level of `xdas`: called on
+data it applies eagerly, called on `...` it returns the atom.
+
+```{eval-rst}
+.. currentmodule:: xdas
+```
+
+```{eval-rst}
+.. autosummary::
+   :toctree: ../_autosummary
+
+   annotate
+   decimate
+   detrend
+   differentiate
+   filter
+   hilbert
+   integrate
+   medfilt
+   pick
+   rechunk
+   resample
+   sliding_mean_removal
+   stft
+   taper
+   trigger
+```
+
+```{eval-rst}
+.. currentmodule:: xdas.atoms
 ```
 
 ## Signal processing
@@ -90,13 +147,41 @@ Methods
 .. autosummary::
    :toctree: ../_autosummary
 
-   DownSample
    FIRFilter
    IIRFilter
-   LFilter
-   MLPicker
    ResamplePoly
-   SOSFilter
+```
+
+## 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,
+its own per-phase thresholds. Each has a lowercase functional twin at the top
+level of `xdas` (`xdas.annotate`, `xdas.trigger`, `xdas.pick`).
+
+```{eval-rst}
+.. autosummary::
+   :toctree: ../_autosummary
+
+   Annotate
    Trigger
+   Picker
+```
+
+## Kernel atoms
+
+Expert layer (`xdas.atoms.kernel`): exact stateful primitives with machine
+parameters, designed by the task atoms from the data at the first call.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: ../_autosummary
+
+   DownSample
+   LFilter
+   Polyphase
+   Rechunk
+   SOSFilter
    UpSample
-```
+```

docs/api/processing.md

@@ -11,6 +11,9 @@
    :toctree: ../_autosummary
 
    process
+   watch
+   get_source
+   get_writer
 ```
 
 ## Loaders
@@ -43,6 +46,7 @@
    StreamWriter
    ZMQPublisher
    ZMQSubscriber
+   ResultWriter
 ```
 
 ### DataArrayWriter
@@ -66,4 +70,16 @@
    ZMQPublisher.submit
    ZMQPublisher.write
    ZMQPublisher.result
+   ZMQPublisher.wait_for_subscribers
+   ZMQPublisher.close
+```
+
+### ZMQSubscriber
+
+```{eval-rst}
+.. autosummary::
+   :toctree: ../_autosummary
+
+   ZMQSubscriber.wait_until_subscribed
+   ZMQSubscriber.close
 ```

docs/api/testing.md

@@ -8,5 +8,7 @@
 .. autosummary::
    :toctree: ../_autosummary
 
+   assert_chunk_invariant
    dummy
+   inject_gaps
 ```

docs/api/xdas.md

@@ -34,6 +34,8 @@
    get_sampling_interval
    sortby
    split
+   stack
+   trim_overlaps
    plot_availability
 ```
 
@@ -153,6 +155,7 @@ Methods
 .. autosummary::
    :toctree: ../_autosummary
 
+   DataCollection.select
    DataCollection.query
    DataCollection.issequence
    DataCollection.ismapping

docs/user-guide/faq.md

@@ -68,10 +68,11 @@ output samples. When you split data into chunks and apply the filter independent
 each chunk, the state is re-initialised at every boundary and the transient response
 distorts the result near each chunk edge.
 
-Use the stateful atom equivalents from {py:mod}`xdas.atoms` (e.g.
-{py:class}`~xdas.atoms.IIRFilter`, {py:class}`~xdas.atoms.LFilter`) inside a
-{py:class}`~xdas.atoms.Sequential` pipeline. These atoms carry the filter state across
-chunk boundaries automatically when used with {py:func}`~xdas.processing.process`.
+Build the pipeline out of atoms — `xd.filter(..., (1.0, 10.0))` rather than
+`xs.filter(da, ...)` — and run it with {py:meth}`~xdas.atoms.Atom.process`. The atoms
+carry the filter state across chunk boundaries, and flush and restart it wherever the
+input actually has a gap or changes sampling rate, so the chunked answer is the eager
+one. {py:func}`xdas.testing.assert_chunk_invariant` checks that on your own pipeline.
 
 ## Can I use xdas with seismic data that is not DAS?
 

docs/user-guide/index.md

@@ -29,7 +29,8 @@ access large multi-file acquisitions as a single seamless array.
 :link: pipeline/index
 :link-type: doc
 Building processing sequences with {py:class}`~xdas.atoms.Atom` objects and applying
-them chunk-by-chunk on datasets larger than memory, including real-time streaming.
+them chunk-by-chunk on datasets larger than memory, including real-time streaming and
+phase picking with SeisBench models.
 ```
 
 ```{grid-item-card} How-To Guides

docs/user-guide/io/obspy.md

@@ -62,16 +62,17 @@ for station in stations:
 *Xdas* reads seismological data through ObsPy, with the engine named `"obspy"`
 after the library rather than after any one format: decoding is
 {py:func}`obspy.read`, so miniSEED, SAC, GSE2, SEG-2 and everything else ObsPy
-supports goes through the same path. `engine="miniseed"` still works as an
-alias.
+supports goes through the same path.
 
 The engine mirrors {py:func}`obspy.read` exactly: **one contiguous ObsPy
 `Trace` becomes one lazy `DataArray`**, and the collection mirrors the
 `Stream`, nested on the four levels of the SEED hierarchy. Nothing is decoded
 at this point — the scan only records where each trace lives.
 
 ```{note}
-This part encourages experimenting with seismic data. Depending on the most common use cases users find, this could lead to changes in development direction.
+The legacy `"miniseed"` engine is a different reader, kept for the code written
+against it: it returns one stacked-channel array per file rather than a
+collection. See [](data-formats.md).
 ```
 
 ## Reading
@@ -82,6 +83,7 @@ the directory layout does not have to be described, since the SEED identifiers
 inside the files already say where each trace belongs.
 
 ```{code-cell}
+import numpy as np
 import xdas as xd
 
 dc = xd.open("NX/*/*.mseed", engine="obspy")
@@ -103,7 +105,7 @@ semantics of `obspy.Stream.select`, with shell-style globbing on the keys:
 dc.select(station="SX00[123]", channel="HH?")
 ```
 
-`select` chooses *which* leaves are kept; {py:meth}`~xdas.DataCollection.sel`
+`select` chooses *which* leaves are kept; {py:meth}`~xdas.DataMapping.sel`
 trims *inside* each leaf by coordinate label. Indexing works too, and reads
 like the seed id it is:
 
@@ -159,15 +161,12 @@ every copy and look at them, `xd.split(da, "overlaps")` cuts them apart.
 ## Stacking channels and stations
 
 As often, the different channels of a station are synchronized. They can be
-stacked into a two-dimensional array with {py:func}`xdas.concat`, which stays
-lazy: the identifiers that vary along the new dimension become a coordinate,
-the ones that do not stay scalar.
+collapsed into a dimension of a two-dimensional array with
+{py:func}`xdas.stack`, which stays lazy: the level's keys become the new
+coordinate, and the identifiers that do not vary stay scalar.
 
 ```{code-cell}
-def stack(node, dim):
-    return xd.concat([node[key][0] for key in sorted(node)], dim)
-
-da = stack(dc["NX"]["SX001"]["00"], "channel")
+da = xd.stack(dc["NX"]["SX001"]["00"], "channel")[0]
 da
 ```
 
@@ -177,10 +176,7 @@ array, ready for array analysis:
 
 ```{code-cell}
 sub = dc.sel(time=slice("2024-01-01T00:01:00", "2024-01-01T00:02:59.99"))
-da = xd.concat(
-    [stack(sub["NX"][station]["00"], "channel") for station in sorted(sub["NX"])],
-    "station",
-)
+da = xd.stack(xd.stack(sub["NX"], "channel"), "station")["00"][0]
 da
 ```