Algorithms

Overview

This page is a quick reference to 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 API of all the functions described here is standardized. Key features to be aware of are:

1. All functions assume arg0 is a seismic data object.

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

3. All functions enforce the data type of arg0 and will throw a TypeError exception for any mismatch.

4. All implement the dead/live concept. In particular, all have the behavior that if the data object passed as arg0 is marked dead it immediately returns. If the type of input and output are the same the return is identical to the input. If the type changes and an input datum is marked dead the output will be a default constructed version of the output type with a copy of the Metadata from the input and a copy of the input’s error log.

5. All functions that are intrinsically atomic (i.e. operates on TimeSeries and/or Seismogram objects) also work 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. No MsPASS will throw an exception except for a usage error or a system level failure that is unrecoverable. 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.

Note also if an input or output are listed as TimeSeries it will also process a TimeSeriesEnsemble with a loop. Similarly, if input or output is listed as Seismogram the function will also process a SeismogramEnsemble with a loop. When input or output are listed as “any” it means any seismic data type is handled.

Table 3 Processing Functions

Name	Synopsis	Inputs	Outputs
correlate	Cross-correlate pair of signals (obspy)	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
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	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 produce 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
erase_metadata	Clear all defined values of a specified key	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
MetadataEQMetadataEQ	Kill a datum if a value is equal to constant	kill_if_true	any	Edited version of input
MetadataNEMetadataNE	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 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.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 the mspass deconvolution tutorial for guidance on using these experimental algorithms.