Algorithms

Overview

This page is a quick reference to algorithms available in MsPASS. The page 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.

Table 3 Processing Functions

Name	Synopsis	Inputs	Outputs
correlate	Cross-correlate pair of signals	TimeSeries	TimeSeries
correlate_stream_template	obspy correlation of many with a template	TimeSeriesEnsemble(arg)),TimeSeries(arg1)	TimeSeriesEnsemble
correlate_template	obspy single channel correlation against a template	TimeSeries	TimeSeries
detrend	obspy detrend algorithm	TimeSeries	TimeSeries
filter	obspy time-invariant filter function	All	Same as input
interpolate	obspy function to resample using interpolation	TimeSeries	TimeSeries
WindowData	Cut a smaller window from a larger segment	All	Same as input
merge	Combine a set of segments into one	TimeSeriesEnsemble (member vector)	TimeSeries
scale	scale data to specified level with a specified amplitude metric	Any	Same as input
snr	Compute one of several possible time-domain signal-to-noise ratio metrics	TimeSeries Seismogram	float
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 Extarrival 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	TimeSeries
seed_ensemble_sort	Sorts an ensemble into net:sta:chan:loc order	TimeSeriesEnsemble	TimeSeriesEnsemble
splice_segments	Splice a list of TimeSeries objects into a continuous single TimeSeries	list of TimeSeries	TimeSeries
bundle	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

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
BandwidthStatisticsBandwidthStatistics	Compute statistical summary of snr in a passband returned by EstimateBandwidth	BandwidthData object	Metadata
EstimateBandwidth	Estimate signal bandwidth estimate of power spectra of signal and noise	PowerSpectra of signal and noise windows	BandwidthData - input for BandwidthStatisics
MADAmplitude	Calculate amplitude with the MAD metric	TimeSeries or Seismogram	double
PeakAmplitude	Calculate amplitude with the peak absolute value	TimeSeries or Seismogram	double
PercAmplitude	Calculate amplitude at a specified percentage level	TimeSeries or Seismogram	double
RMSAmplitude	Calculate amplitude with the RMS metric	TimeSeries or Seismogram	double

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.

Table 5 Processing Objects

Class Name	Synopsis	Processing method	Inputs	Outputs
Add	Add a constant to a metadata value	apply	Any seismic data object	Edited version of input
Add2	Add two metadata values	apply	Any seismic data object	Edited version of input
ChangeKey	Change key associated with a value	apply	Any seismic data object	Edited version of input
Divide	Divide a metadata value by a constant	apply	Any seismic data object	Edited version of input
Divide2	Divide one metadata value by another	apply	Any seismic data object	Edited version of input
IntegerDivide	Apply integer divide operator to a metadata value	apply	Any seismic data object	Edited version of input
IntegerDivide2	Apply integer divide operator to two metadata values	apply	Any seismic data object	Edited version of input
Mod	Change a key to value mod constant	apply	Any seismic data object	Edited version of input
Mod2	Set a field as mod division of a pair of values	apply	Any seismic data object	Edited version of input
Multiply	Change a key to value times constant	apply	Any seismic data object	Edited version of input
Multiply2	Set a field as produce of a pair of values	apply	Any seismic data object	Edited version of input
SetValue	Set a field to a constant	apply	Any seismic data object	Edited version of input
Subtract	Change a key to value minus a constant	apply	Any seismic data object	Edited version of input
Subtract2	Set a field as difference of a pair of values	apply	Any seismic data object	Edited version of input
erase_metadata	Clear all defined values of a specified key	apply	Any seismic data object	Edited version of input
MetadataOperatorChain	Apply a chain of metadata calculators	apply	Any seismic data object	Edited version of input
FiringSquad	Apply a series of kill operators	kill_if_true	Any seismic data object	Edited version of input
MetadataDefined	Kill if a key-value pair is defined	kill_if_true	Any seismic data object	Edited version of input
MetadataUndefined	Kill if a key-value pair is not defined	kill_if_true	Any seismic data object	Edited version of input
MetadataEQMetadataEQ	Kill a datum if a value is equal to constant	kill_if_true	Any seismic data object	Edited version of input
MetadataNEMetadataNE	Kill a datum if a value is not equal to constant	kill_if_true	Any seismic data object	Edited version of input
MetadataGE	Kill if a value is greater than or equal to a constant	kill_if_true	Any seismic data object	Edited version of input
MetadataGT	Kill if a value is greater than a constant	kill_if_true	Any seismic data object	Edited version of input
MetadataLE	Kill if a value is less than or equal to a constant	kill_if_true	Any seismic data object	Edited version of input
MetadataLT	Kill if a value is less than a constant	kill_if_true	Any seismic data object	Edited version of input
MetadataInterval	Kill for value relative to an interval	kill_if_true	Any seismic data object	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 methods are available through two different mechanisms:

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

2. The RFdecon function 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 instance of this class and run it’s mspasspy.algorithms.RFdeconProcessor.RFdeconProcessor.apply() method, especially for multitaper methods that require computing the Slepian tapers.

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.CNR3CDecon. See the mspass deconvolution tutorial for guidance on using this experimental algorithm.