Algorithms

Overview

This page is a curated quick reference to commonly used algorithms available in MsPASS. The functions described here are all algorithms for handling MsPASS seismic data objects. Utility functions for other objectives are described elsewhere.

The generated Python algorithms API is the complete reference for additional specialized routines and current signatures.

Most high-level Python processing functions use MsPASS decorators to provide a common API. Low-level C++ bindings and helper functions can differ, so the linked docstring remains authoritative. Key conventions are:

1. Most high-level processing functions take a seismic data object as arg0. Multi-input algorithms and the nonstandard functions listed below are exceptions.

2. Some functions can handle all data types and some are more restrictive. The tables below provide a quick reference in addition to the docstrings.

3. Wrapped functions validate arg0 either in the decorator or in the function. Invalid usage normally raises TypeError or ValueError.

4. High-level processing functions implement the dead/live concept. A dead input normally returns without numerical processing. Consult the linked docstring for type-changing and multi-input functions.

5. Decorated functions that are intrinsically atomic (i.e. operate on TimeSeries and/or Seismogram objects) can also be applied to ensembles. In MsPASS an ensemble is just a container with one or more atomic data stored under the common symbol member. (e.g. if e is a TimeSeriesEnsemble, then e.member[i] is the ith component TimeSeries object.) Atomic algorithms applied to ensemble are always done as a loop over the member array.

6. High-level wrappers normally convert recoverable per-datum failures into a killed datum with an error-log entry. Usage errors, fatal failures, and direct calls to low-level bindings can still raise exceptions. When an individual datum has issues that don’t allow the algorithm to work with the specified inputs (e.g. windowing when the window range is outside the time range of the data) the datum will be killed with a message posted to the object’s error log.

This document is organized as a set of tables with hyperlinks to the docstrings for each algorithm function.

Processing Functions

These algorithms have a function form to allow their use in parallel map operations. They are functions that have one or more seismic data objects as inputs and return the output of the algorithm. The output may or may not be the same type. Some are wrappers for obspy functions, some are written in C++ with python wrappers, and some are pure C++ functions with python bindings. Note the name field in the table below is a hyperlink to the docstring for that function.

The input and output columns describe each row explicitly. “Any” means any of the four MsPASS seismic data types. Some decorated atomic functions also loop over the matching ensemble type; confirm that behavior in the linked docstring.

Table 3 Processing Functions

Name	Synopsis	Inputs	Outputs
correlate	Cross-correlate pair of signals (obspy)	TimeSeries, TimeSeries	numpy.ndarray
correlate_stream_template	obspy correlation of many with a template	Seismogram or TimeSeriesEnsemble, plus template	Seismogram or TimeSeriesEnsemble
correlate_template	obspy single channel correlation against a template	TimeSeries, TimeSeries template	numpy.ndarray
detrend	obspy detrend algorithm	Any	Same as input
filter	obspy time-invariant filter function	All	Same as input
interpolate	obspy function to resample using interpolation	Any	Same as input
WindowData	Cut a smaller window from a larger segment	All	Same as input
merge	Combine a set of segments into one	list of TimeSeries	TimeSeries
scale	scale data to specified level with a specified amplitude metric	Any	Same as input
broadband_snr_QC	Computes a series of snr-based amplitude metrics and posts them to output Metadata	TimeSeries or Seismogram	Same as input (Metadata altered)
arrival_snr	Computes a series of snr-based amplitude metrics relative to an arrival time	TimeSeries	TimeSeries (Metadata altered)
FD_snr_estimator	Computes a set of broadband snr estimates in the frequency domain	TimeSeries	[dict,ErrorLogger]
ArrivalTimeReference	Shifts time 0 to arrival time defined by a Metadata key	Seismogram or SeismogramEnsemble	Same as input
agc	Applies an automatic gain control operator with a specified duration	Seismogram	TimeSeries of gains, Seismogram input altered in place
repair_overlaps	Repair overlapping data segments	list of TimeSeries	list of TimeSeries
seed_ensemble_sort	Sorts an ensemble into net:sta:chan:loc order	TimeSeriesEnsemble	None (input reordered in place)
splice_segments	Splice a list of TimeSeries objects into a continuous single TimeSeries	list of TimeSeries	TimeSeriesWGaps
bundle_seed_data	Bundle a TimeSeriesEnsemble into a SeismogramEnsemble	TimeSeriesEnsemble	SeismogramEnsemble
BundleSEEDGroup	Bundle a list of TimeSeries into a Seismogram object	list of TimeSeries	Seismogram
ExtractComponent	Extract one component from a Seismogram or SeismogramEnsemble	Seismogram or SeismogramEnsemble	TimeSeries or TimeSeriesEnsemble
ator	Change from UTC to relative time standard	any	same as input
rtoa	Change from relative to UTC time standard	any	same as input
rotate	Generic coordinate rotation	Seismogram or SeismogramEnsemble	same as input
rotate_to_standard	Restore data to cardinal directions	Seismogram or SeismogramEnsemble	same as input
transform	Apply a general transformation matrix to 3C data	Seismogram or SeismogramEnsemble	same as input
linear_taper	Apply a one-sided, linear taper	any	same as input
cosine_taper	Apply a one-sided, cosine taper	any	same as input
vector_taper	Apply a taper defined by a vector of samples	any	same as input
erase_metadata	Clear all values associated with specified Metadata keys	Any	Same as input

Nonstandard Processing Functions

The next table is similar to above, but the inputs or outputs are not seismic data objects. They are used internally by some functions and can have utility for writing custom functions that use them inside another algorithm.

Table 4 Nonstandard Processing Functions

Name	Synopsis	Inputs	Outputs
BandwidthStatistics	Compute statistical summary of snr in a passband returned by EstimateBandwidth	Two PowerSpectrum objects and BandwidthData	Metadata
EstimateBandwidth	Estimate signal bandwidth estimate of power spectra of signal and noise	PowerSpectrum objects for signal and noise	BandwidthData - input for BandwidthStatistics
MADAmplitude	Calculate amplitude with the MAD metric	TimeSeries or Seismogram	float
PeakAmplitude	Calculate amplitude with the peak absolute value	TimeSeries or Seismogram	float
PercAmplitude	Calculate amplitude at a specified percentage level	TimeSeries or Seismogram	float
RMSAmplitude	Calculate amplitude with the RMS metric	TimeSeries or Seismogram	float
snr	Compute one of several possible time-domain signal-to-noise ratio metrics	TimeSeries or Seismogram	float

Processing Objects

This collection of things are “processing objects” meaning they implement processing using a C++ or python class that has a method that runs an algorithm on seismic data. All are effectively functions that take inputs and emit an output. The only difference is the syntax of a “method” compared to a simple function. They also have the same API guarantees listed at the beginning of this section (i.e. the list of items in the first section).

Table 5 Processing Objects

Class Name	Synopsis	Processing method	Inputs	Outputs
Add	Add a constant to a metadata value	apply	any	Edited version of input
Add2	Add two metadata values	apply	any	Edited version of input
ChangeKey	Change key associated with a value	apply	any	Edited version of input
Divide	Divide a metadata value by a constant	apply	any	Edited version of input
Divide2	Divide one metadata value by another	apply	any	Edited version of input
IntegerDivide	Apply integer divide operator to a metadata value	apply	any	Edited version of input
IntegerDivide2	Apply integer divide operator to two metadata values	apply	any	Edited version of input
Mod	Change a key to value mod constant	apply	any	Edited version of input
Mod2	Set a field as mod division of a pair of values	apply	any	Edited version of input
Multiply	Change a key to value times constant	apply	any	Edited version of input
Multiply2	Set a field as the product of a pair of values	apply	any	Edited version of input
SetValue	Set a field to a constant	apply	any	Edited version of input
Subtract	Change a key to value minus a constant	apply	any	Edited version of input
Subtract2	Set a field as difference of a pair of values	apply	any	Edited version of input
MetadataOperatorChain	Apply a chain of metadata calculators	apply	any	Edited version of input
FiringSquad	Apply a series of kill operators	kill_if_true	any	Edited version of input
MetadataDefined	Kill if a key-value pair is defined	kill_if_true	any	Edited version of input
MetadataUndefined	Kill if a key-value pair is not defined	kill_if_true	any	Edited version of input
MetadataEQ	Kill a datum if a value is equal to constant	kill_if_true	any	Edited version of input
MetadataNE	Kill a datum if a value is not equal to constant	kill_if_true	any	Edited version of input
MetadataGE	Kill if a value is greater than or equal to a constant	kill_if_true	any	Edited version of input
MetadataGT	Kill if a value is greater than a constant	kill_if_true	any	Edited version of input
MetadataLE	Kill if a value is less than or equal to a constant	kill_if_true	any	Edited version of input
MetadataLT	Kill if a value is less than a constant	kill_if_true	any	Edited version of input
MetadataInterval	Kill for value relative to an interval	kill_if_true	any	Edited version of input

Deconvolution algorithms

MsPASS has a specialized algorithms module on “deconvolution”. Users should recognize that currently the module has algorithms for “deconvolution” in form of estimation of so called “receiver functions”. Receiver functions are a special type of deconvolution useful only, at present anyway, for application to teleseismic body wave phase data.

A suite of conventional scalar and generalized iterative methods is available through two different mechanisms:

1. The wrapper function mspasspy.algorithms.RFdeconProcessor.RFdecon() is a functional form that can be used directly in map operators.

2. By default, RFdecon instantiates an instance of the class mspasspy.algorithms.RFdeconProcessor.RFdeconProcessor in each call to the function. It is more efficient (i.e. faster) to instantiate a single processor and pass it through the engine argument on repeated calls, especially for methods with significant setup costs. The processor’s lower-level mspasspy.algorithms.RFdeconProcessor.RFdeconProcessor.apply() method is also available for specialized workflows.

See the docstrings with links above for usage.

A different, unpublished (aka experimental) algorithm called “Colored Noise Regularized Three Component Decon “ is implemented in the C++ class mspasspy.ccore.algorithms.deconvolution.CNRDeconEngine. There are two python functions that utilize the “engine”:

1. mspasspy.algorithms.CNRDecon.CNRRFDecon() uses the CNR algorithm to estimate conventional “receiver functions” where each 3C station is deconvolved independently.

2. The same engine is used for an array version called mspasspy.algorithms.CNRDecon.CNRArrayDecon()

See Deconvolution Operators for conventional, CNR, and generalized iterative deconvolution guidance.