Waveform Models

BasicPhaseAE

class BasicPhaseAE(in_channels=3, classes=3, phases='NPS', sampling_rate=100, **kwargs)

Bases: WaveformModel

Simple AutoEncoder network architecture to pick P-/S-phases, from Woollam et al., (2019).

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	300
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.3

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

Parameters:

• in_channels (int) – Number of input channels, by default 3.

• in_samples (int) – Number of input samples per channel, by default 600. The model expects input shape (in_channels, in_samples)

• classes (int) – Number of output classes, by default 3.

• phases (list, str) – Phase hints for the classes, by default “NPS”. Can be None.

• sampling_rate (float) – Sampling rate of traces, by default 100.

• kwargs – Keyword arguments passed to the constructor of WaveformModel.

annotate_batch_post(batch, piggyback, argdict)

Runs postprocessing on the predictions of a window for the annotate function, e.g., reformatting them. By default, returns the original prediction. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Predictions for the batch. The data type depends on the model.

• argdict (dict[str, Any]) – Dictionary of arguments

• piggyback (Any) – Piggyback information, by default None.

Return type:

Tensor

Returns:

Postprocessed predictions

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

classify_aggregate(annotations, argdict)

Converts the annotations to discrete thresholds using picks_from_annotations(). Trigger onset thresholds for picks are derived from the argdict at keys “[phase]_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of picks

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

CRED

class CRED(in_samples=3000, in_channels=3, sampling_rate=100, original_compatible=False, **kwargs)

Bases: WaveformModel

Note: There are subtle differences between the model presented in the paper (as in Figure 1) and the code on Github.

Here we follow the implementation from Github to allow for compatibility with the pretrained weights.

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	1500
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
detection_threshold	Detection threshold	0.5

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

classify_aggregate(annotations, argdict)

Converts the annotations to discrete detections using detections_from_annotations(). Trigger onset thresholds are derived from the argdict at key “detection_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of detections

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

static waveforms_to_spectrogram(batch)

Transforms waveforms into spectrogram using short term fourier transform :type batch: Tensor :param batch: Waveforms with shape (channels, samples) :rtype: Tensor :return: Spectrogram with shape (channels, times, frequencies)

DeepDenoiser

class DeepDenoiser(sampling_rate=100, **kwargs)

Bases: WaveformModel

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	1500
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate_batch_post(batch, piggyback, argdict)

Runs postprocessing on the predictions of a window for the annotate function, e.g., reformatting them. By default, returns the original prediction. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Predictions for the batch. The data type depends on the model.

• argdict (dict[str, Any]) – Dictionary of arguments

• piggyback (Any) – Piggyback information, by default None.

Return type:

Tensor

Returns:

Postprocessed predictions

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

static generate_label(stations)

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

SeisDAE

class SeisDAE(in_samples=3000, in_channels=2, sampling_rate=100, filters_root=8, depth=6, kernel_size=(3, 3), strides=(2, 2), output_activation=Softmax(dim=1), drop_rate=0.0, use_bias=False, norm='peak', eps=1e-13, nfft=60, nperseg=30, attention=False, **kwargs)

Bases: WaveformModel

Seismic Denoising Autoencoder using U-Net Architecture with additional attention gates. A configurable denoising autoencoder for seismic waveform data that operates in the time-frequency domain using the Short-Time Fourier Transform (STFT). The model is based on a U-Net structure with optional attention gates and skip connections.

Parameters:

• in_samples (int) – Length of the input waveform in samples. Default is 3000 samples.

• in_channels (int) – Number of input channels (e.g., 2 for real and imaginary STFT components). Default are 2 channels.

• sampling_rate (float) – Sampling rate of the waveform data in Hz. Default sampling rate is 100 Hz.

• filters_root (int) – Number of filters in the first convolutional layer (doubles with depth). Default is 8.

• depth (int) – Number of encoding/decoding levels in the U-Net. Default is 6 for STFT

• kernel_size (tuple[int, int]) – Kernel size for convolutional layers. Default is (3, 3).

• strides (tuple[int, int]) – Stride size used for down/upsampling using Conv2D and transpose Conv2D layers. Default is (2, 2).

• output_activation – Activation function applied to final output Default is Softmax.

• drop_rate (float) – Dropout rate used throughout the network. Default drop_rate is 0

• use_bias (bool) – Whether to use bias in convolutional layers. Default is False.

• norm (str) – Type of normalization applied to traces (“peak” or “std”). Default is “peak”

• eps (float) – Factor to avoid division by zero. Default value is 1e-13.

• nfft (int) – Length of the FFT used, if a zero padded FFT is desired for scipy STFT. If None, the FFT length is nperseg.

• nperseg (int) – Length of each segment for scipy STFT. Default is 60

• attention (bool) – Whether to use attention gates in skip connections or not. Default is False

• kwargs – Additional arguments passed to the base WaveformModel.

annotate_batch_post(batch, piggyback, argdict)

Does postprocessing when predicting datasets

Return type:

Tensor

annotate_batch_pre(batch, argdict)

Does preprocessing for prediction

Return type:

Tensor

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

static generate_label(stations)

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

Depth phase models

class DepthPhaseModel(time_before=12.5, depth_levels=None, tt_args=None, qc_std=None, qc_depth=None)

Bases: object

Helper class implementing all tools for determining depth from depth phases

Parameters:

• time_before (float) – Time included before the P pick in seconds

• depth_levels (ndarray | None) – Array of depth levels to search for

• tt_args (dict[str, Any] | None) – Arguments for the TTLookup

• qc_std (float | None) – Maximum standard deviation to pass quality control. If None, no quality control is applied.

• qc_depth (float | None) – Quality control is only applied to predictions shallower than this depth. If None, quality control is applied to all depth levels.

class DepthFinder(networks, depth_model, phase_model, p_window=10, p_threshold=0.15)

Bases: object

This class is a high-level interface to the depth phase models. It determines event depth at teleseismic distances based on a preliminary location. In contrast to the depth phase models, it is not provided with waveforms, but automatically downloads data through FDSN. Furthermore, it automatically determines first P arrivals using predicted travel times and a deep learning picker.

The processing consists of several steps:

• determine available station at the time of the event

• predict P arrivals

• download waveforms through FDSN

• repick P arrivals with a deep learning model

• determine depth with deep learning based depth model

If waveforms and P wave picks are already available, it is highly recommended to directly use the underlying depth phase model instead of this helper.

Example application

networks = {"GFZ": ["GE"], "IRIS": ["II", "IU"]}  # FDSN providers and networks
depth_model = sbm.DepthPhaseTEAM.from_pretrained("original")  # A depth phase model
phase_model = sbm.PhaseNet.from_pretrained("geofon")  # A teleseismic picking model
depth_finder = DepthFinder(networks, depth_model, phase_model)

Parameters:

• networks (dict[str, list[str]]) – Dictionary of FDSN providers and seismic network codes to query

• depth_model (DepthPhaseModel) – The depth phase model to use

• phase_model (WaveformModel) – The phase picking model to use for pick refinement

• p_window (float) – Seconds around the predicted P arrival to search for actual arrival

• p_threshold (float) – Minimum detection confidence for the primary P phase to include a record

get_depth(lat, lon, depth, origin_time)

Get the depth of an event based on its preliminary latitude, longitude, depth and origin time. A depth estimate needs to be input, as it is required to predict preliminary P arrivals. This is not a circular reasoning, as depth and origin_time trade off against each other.

Parameters:

• lat (float) – Latitude of the event

• lon (float) – Longitude of the event

• depth (float) – Preliminary depth of the event

• origin_time (UTCDateTime) – Preliminary origin time of the event

Return type:

ClassifyOutput

class DepthPhaseNet(phases=('P', 'pP', 'sP'), sampling_rate=20.0, depth_phase_args=None, norm='peak', **kwargs)

Bases: PhaseNet, DepthPhaseModel

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	1500
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(0, 0)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate(stream, p_picks, **kwargs)

Get depth phase probabilities curves for one event. Note that the annotations are aligned to have the P arrival at UTCDateTime(0), i.e., 1970-01-01 00:00:00. The probability curves are not normalized, there absolute value is therefore meaningless.

Warning

This class does not expose an ‘annotate_async` function directly.

Parameters:

• stream (Stream) – Obspy stream to annotate

• p_picks (dict[str, UTCDateTime]) – Dictionary of P pick times. Station codes will be truncated to NET.STA.LOC.

• kwargs – All kwargs are passed to the annotate function of the superclass.

classify(stream, p_picks, distances=None, inventory=None, epicenter=None, **kwargs)

Calculate depth of an event using depth phase picking and a line search over the depth axis. Can only handle one event at a time.

For the line search, the epicentral distances of the stations to the event is required. These can either be provided directly or through an inventory and the event epicenter.

Warning

This class does not expose an ‘classify_async` function directly.

Parameters:

• stream (Stream) – Obspy stream to classify

• p_picks (dict[str, UTCDateTime]) – Dictionary of P pick times. Station codes will be truncated to NET.STA.LOC.

• distances (dict[str, float] | None) – Dictionary of epicentral distances for the stations in degrees

• inventory (Inventory | None) – Inventory for the stations

• epicenter (tuple[float, float] | None) – (latitude, longitude) of the event epicenter

Return type:

ClassifyOutput

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

tensor

class DepthPhaseTEAM(phases=('P', 'pP', 'sP'), classes=3, sampling_rate=20.0, depth_phase_args=None, norm='peak', **kwargs)

Bases: PhaseTEAM, DepthPhaseModel

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	0
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate(stream, p_picks, **kwargs)

Get depth phase probabilities curves for one event. Note that the annotations are aligned to have the P arrival at UTCDateTime(0), i.e., 1970-01-01 00:00:00. The probability curves are not normalized, there absolute value is therefore meaningless.

Parameters:

• stream (Stream) – Obspy stream to annotate

• p_picks (dict[str, UTCDateTime]) – Dictionary of P pick times. Station codes will be truncated to NET.STA.LOC.

• kwargs – All kwargs are passed to the annotate function of the superclass.

classify(stream, p_picks, distances=None, inventory=None, epicenter=None, **kwargs)

Calculate depth of an event using depth phase picking and a line search over the depth axis. Can only handle one event at a time.

For the line search, the epicentral distances of the stations to the event is required. These can either be provided directly or through an inventory and the event epicenter.

Parameters:

• stream (Stream) – Obspy stream to classify

• p_picks (dict[str, UTCDateTime]) – Dictionary of P pick times. Station codes will be truncated to NET.STA.LOC.

• distances (dict[str, float] | None) – Dictionary of epicentral distances for the stations in degrees

• inventory (Inventory | None) – Inventory for the stations

• epicenter (tuple[float, float] | None) – (latitude, longitude) of the event epicenter

Return type:

ClassifyOutput

EQTransformer

class EQTransformer(in_channels=3, in_samples=6000, classes=2, phases='PS', lstm_blocks=3, drop_rate=0.1, original_compatible=False, sampling_rate=100, norm='std', **kwargs)

Bases: WaveformModel

The EQTransformer from Mousavi et al. (2020)

Implementation adapted from the Github repository https://github.com/smousavi05/EQTransformer Assumes padding=”same” and activation=”relu” as in the pretrained EQTransformer models

By instantiating the model with from_pretrained(“original”) a binary compatible version of the original EQTransformer with the original weights from Mousavi et al. (2020) can be loaded.

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	3000
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	max
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.1
detection_threshold	Detection threshold	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(500, 500)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

Parameters:

• in_channels – Number of input channels, by default 3.

• in_samples – Number of input samples per channel, by default 6000. The model expects input shape (in_channels, in_samples)

• classes – Number of output classes, by default 2. The detection channel is not counted.

• phases – Phase hints for the classes, by default “PS”. Can be None.

• lstm_blocks – Number of LSTM blocks

• drop_rate – Dropout rate

• original_compatible – If True, uses a few custom layers for binary compatibility with original model from Mousavi et al. (2020). This option defaults to False. It is usually recommended to stick to the default value, as the custom layers show slightly worse performance than the PyTorch builtins. The exception is when loading the original weights using from_pretrained().

• norm – Data normalization strategy, either “peak” or “std”.

• kwargs – Keyword arguments passed to the constructor of WaveformModel.

annotate_batch_post(batch, piggyback, argdict)

Runs postprocessing on the predictions of a window for the annotate function, e.g., reformatting them. By default, returns the original prediction. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Predictions for the batch. The data type depends on the model.

• argdict (dict[str, Any]) – Dictionary of arguments

• piggyback (Any) – Piggyback information, by default None.

Return type:

Tensor

Returns:

Postprocessed predictions

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

classify_aggregate(annotations, argdict)

Converts the annotations to discrete picks using picks_from_annotations() and to discrete detections using detections_from_annotations(). Trigger onset thresholds for picks are derived from the argdict at keys “[phase]_threshold”. Trigger onset thresholds for detections are derived from the argdict at key “detection_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of picks, list of detections

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

property phases

EQTP

class EQTP(in_samples=12000, **kwargs)

Bases: EQTransformer

The EQTP from Peng et al. (2025)

It is an extended version of the EQTransformer model, which builds upon its phase picking capabilities by adding P-wave polarity determination functionality.

This model is designed for processing three-component seismic waveform data, and can simultaneously output picking results for phases such as P-waves/S-waves and polarity determination results for P-waves (Up U/Down D/Unknown N).

Implementation is adapted from the EQTransformer with SeisBench GitHub repository (https://github.com/seisbench/seisbench).

The EQTP model can be instantiated via the from_pretrained(“ncedc”) method.

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	3000
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	max
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.1
detection_threshold	Detection threshold	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(500, 500)
polarity_threshold	Polarity threshold	0.3

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

classify_aggregate(annotations, argdict)

Converts the annotations to discrete picks using picks_from_annotations() and to discrete detections using detections_from_annotations(). Trigger onset thresholds for picks are derived from the argdict at keys “[phase]_threshold”. Trigger onset thresholds for detections are derived from the argdict at key “detection_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of picks, list of detections

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

GPD

class GPD(in_channels=3, classes=3, phases=None, eps=1e-10, sampling_rate=100, pred_sample=200, original_compatible=False, **kwargs)

Bases: WaveformModel

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	0
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	10
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.7

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

classify_aggregate(annotations, argdict)

Converts the annotations to discrete picks using picks_from_annotations(). Trigger onset thresholds for picks are derived from the argdict at keys “[phase]_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of picks

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

property phases

LFEDetect

class LFEDetect(*args, **kwargs)

Bases: VariableLengthPhaseNet

This detection and phase picking model for low-frequency earthquakes (LFEs) is based on PhaseNet. Please note that, for the time being, LFE detection models do not reach the quality of EQ detection models.

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	0.5
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(0, 0)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

OBSTransformer

class OBSTransformer(lstm_blocks=2, drop_rate=0.2, original_compatible='non-conservative', **kwargs)

Bases: EQTransformer

Initialize an instance of OBSTransformer model. OBSTransformer is built based on the original (non-conservative) EqTransformer model.

Warning

Creating an OBSTransformer instance does not automatically load the model weights. To do so, use OBSTransformer.from_pretrained(“obst2024”).

PhaseNet

class PhaseNet(in_channels=3, classes=3, phases='NPS', sampling_rate=100, norm='std', filter_factor=1, **kwargs)

Bases: WaveformModel

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	1500
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(0, 0)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

Parameters:

filter_factor (int) – Increase the number of filters used in each layer by this factor compared to the original PhaseNet. Based on PhaseNetWC proposed by Naoi et al. (2024)

annotate_batch_post(batch, piggyback, argdict)

Runs postprocessing on the predictions of a window for the annotate function, e.g., reformatting them. By default, returns the original prediction. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Predictions for the batch. The data type depends on the model.

• argdict (dict[str, Any]) – Dictionary of arguments

• piggyback (Any) – Piggyback information, by default None.

Return type:

Tensor

Returns:

Postprocessed predictions

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

classify_aggregate(annotations, argdict)

Converts the annotations to discrete thresholds using picks_from_annotations(). Trigger onset thresholds for picks are derived from the argdict at keys “[phase]_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of picks

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

classmethod from_pretrained_expand(name, version_str='latest', update=False, force=False, wait_for_file=False)

Load pretrained model with weights and copy the input channel weights that match the Z component to a new, 4th dimension that is used to process the hydrophone component of the input trace.

For further instructions, see from_pretrained(). This method differs from from_pretrained() in that it does not call helper functions to load the model weights. Instead it covers the same logic and, in addition, takes intermediate steps to insert a new in_channels dimension to the loaded model and copy weights.

Parameters:

• name (str) – Model name prefix.

• version_str (str) – Version of the weights to load. Either a version string or “latest”. The “latest” model is the model with the highest version number.

• force (bool, optional) – Force execution of download callback, defaults to False

• update (bool) – If true, downloads potential new weights file and config from the remote repository. The old files are retained with their version suffix.

• wait_for_file (bool, optional) – Whether to wait on partially downloaded files, defaults to False

Returns:

Model instance

Return type:

SeisBenchModel

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

class PhaseNetLight(in_channels=3, classes=3, phases='NPS', sampling_rate=100, norm='std', **kwargs)

Bases: PhaseNet

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	1500
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(0, 0)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

PhaseNetLight is a slightly reduced version of PhaseNet. It is primarily included for compatibility reasons with an earlier, incomplete implementation of PhaseNet in SeisBench prior to v0.3.

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

class VariableLengthPhaseNet(in_samples=600, in_channels=3, classes=3, phases='PSN', sampling_rate=100, norm='peak', norm_axis=(-1,), output_activation='softmax', empty=False, **kwargs)

Bases: PhaseNet

This version of PhaseNet has extended functionality:

• The number of input samples can be changed. However, the number of layers in the model does not change, i.e., the receptive field stays unchanged. In addition, models will usually not perform well if applied to a different input length than trained on.

• Output activation can be switched between softmax (all components sum to 1, i.e., no overlapping phases) and sigmoid (each component is normed individually between 0 and 1).

• The axis for normalizing the waveforms before passing them to the model can be specified explicitly.

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	0.5
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	avg
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.3
blinding	Number of prediction samples to discard on each side of each window prediction	(0, 0)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

forward(x, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict

PickBlue

PickBlue(base='phasenet', **kwargs)

Initialize a PickBlue model. All kwargs are passed to from_pretrained.

Parameters:

base (str) – Base model to use. Currently, supports either eqtransformer or phasenet.

Skynet

class Skynet(in_channels=3, classes=3, phases='PSN', sampling_rate=100, norm='peak', **kwargs)

Bases: WaveformModel

Skynet is a phase picker with a U-Net architecture with a focus on regional phases and a long receptive field. The model offers first arrival pickers and multiphase pickers for Pn, Pg, Sn, and Sg phases.

The following parameters are available for the annotate/classify functions:

Argument	Description	Default value
batch_size	Batch size for the model	256
overlap	Overlap between prediction windows. Values between 0 and 1 are treated as fractions of the window length. Values above 1 a sample counts. (only for window prediction models)	15000
stacking	Stacking method for overlapping windows (only for window prediction models). Options are ‘max’ and ‘avg’.	max
stride	Stride in samples (only for point prediction models)	1
strict	If true, only annotate if recordings for all components are available, otherwise impute missing data with zeros.	False
flexible_horizontal_components	If true, accepts traces with Z12 components as ZNE and vice versa. This is usually acceptable for rotationally invariant models, e.g., most picking models.	True
zerophase_resample	If true, the filter applied before resampling for anti-aliasing is zero-phase. Otherwise, uses causal filter. Note that using a different filter in application than in training might cause small out of distribution issues	True
*_threshold	Detection threshold for the provided phase	0.5
blinding	Number of prediction samples to discard on each side of each window prediction	(0, 0)

Hint

Please note that the default parameters can be superseded by the pretrained model weights. Check model.default_args to see which parameters are overwritten.

annotate_batch_post(batch, piggyback, argdict)

Runs postprocessing on the predictions of a window for the annotate function, e.g., reformatting them. By default, returns the original prediction. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Predictions for the batch. The data type depends on the model.

• argdict (dict[str, Any]) – Dictionary of arguments

• piggyback (Any) – Piggyback information, by default None.

Return type:

Tensor

Returns:

Postprocessed predictions

annotate_batch_pre(batch, argdict)

Runs preprocessing on batch level for the annotate function, e.g., normalization. By default, returns the input batch unmodified. Optionally, this can return a tuple of the preprocessed batch and piggyback information that is passed to annotate_batch_post(). This can for example be used to transfer normalization information. Inheriting classes should overwrite this function if necessary.

Parameters:

• batch (Tensor) – Input batch

• argdict (dict[str, Any]) – Dictionary of arguments

Return type:

Tensor

Returns:

Preprocessed batch and optionally piggyback information that is passed to annotate_batch_post()

classify_aggregate(annotations, argdict)

Converts the annotations to discrete thresholds using picks_from_annotations(). Trigger onset thresholds for picks are derived from the argdict at keys “[phase]_threshold”.

Parameters:

• annotations – See description in superclass

• argdict – See description in superclass

Return type:

ClassifyOutput

Returns:

List of picks

forward(X, logits=False)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

get_model_args()

Obtain all model parameters for saving.

Returns:

Dictionary of all parameters for a model to store during saving.

Return type:

Dict