3.6.1.1. quakemigrate.signal.onsets

The quakemigrate.onsets module handles the generation of Onset functions. The default method uses the ratio between the short-term and long-term averages of the signal amplitude.

Feel free to contribute more Onset function options!

copyright

2020–2023, QuakeMigrate developers.

license

GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

3.6.1.1.1. quakemigrate.signal.onsets.base

A simple abstract base class with method stubs to enable users to extend QuakeMigrate with custom onset functions that remain compatible with the core of the package.

Also contains a light class to encapsulate the data generated by the onset function, to be used for migration or phase picking.

copyright

2020–2023, QuakeMigrate developers.

license

GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

class quakemigrate.signal.onsets.base.Onset(**kwargs)

Bases: ABC

QuakeMigrate default onset function class.

sampling_rate

Desired sampling rate for input data; sampling rate at which the onset functions will be computed.

Type

int

pre_pad

Option to override the default pre-pad duration of data to read before computing 4-D coalescence in detect() and locate().

Type

float, optional

post_pad

Option to override the default post-pad duration of data to read before computing 4-D coalescence in detect() and locate().

Type

float

calculate_onsets()

Generate onset functions that represent seismic phase arrivals

pad(timespan)

Create appropriate padding to include the taper.

abstract calculate_onsets()

Method stub for calculation of onset functions.

gaussian_halfwidth(phase)

Method stub for Gaussian half-width estimate.

pad(timespan)

Determine the number of samples needed to pre- and post-pad the timespan.

Parameters

timespan (float) – The time window to pad.

Returns

• pre_pad (float) – Option to override the default pre-pad duration of data to read before computing 4-D coalescence in detect() and locate().

• post_pad (float) – Option to override the default post-pad duration of data to read before computing 4-D coalescence in detect() and locate().

abstract property post_pad

Get property stub for pre_pad.

abstract property pre_pad

Get property stub for pre_pad.

class quakemigrate.signal.onsets.base.OnsetData(onsets, phases, channel_maps, filtered_waveforms, availability, starttime, endtime, sampling_rate)

Bases: object

The OnsetData class encapsulates the onset functions calculated by transforming seismic data using the chosen onset detection algorithm (characteristic function).

This includes a dictionary describing which onset functions are available for each station and phase, and the intermediary filtered or otherwise pre-processed waveform data used to calculate the onset function.

Parameters

• onsets (dict of dicts) – Keys “station”, each of which contains keys for each phase, e.g. “P” and “S”. {“station”: {“P”: p_onset, “S”: s_onset}}. Onset functions are calculated by transforming the raw seismic data using some characteristic function designed to highlight phase arrivals.

• phases (list of str) – Phases for which onsets have been calculated. (e.g. [“P”, “S”])

• channel_maps (dict of str) – Data component maps - keys are phases. (e.g. {“P”: “Z”})

• filtered_waveforms (obspy.Stream object) – Filtered and/or resampled and otherwise processed seismic data generated during onset function generation. Only contains waveforms that have passed the quality control criteria, at a unified sampling rate - see sampling_rate.

• availability (dict) – Dictionary with keys “station_phase”, containing 1’s or 0’s corresponding to whether an onset function is available for that station and phase - determined by data availability and quality checks.

• starttime (obspy.UTCDateTime object) – Start time of onset functions.

• endtime (obspy.UTCDateTime object) – End time of onset functions.

• sampling_rate (int) – Sampling rate of filtered waveforms and onset functions.

3.6.1.1.2. quakemigrate.signal.onsets.stalta

The default onset function class - performs some pre-processing on raw seismic data and calculates STA/LTA onset (characteristic) function.

copyright

2020–2024, QuakeMigrate developers.

license

GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

class quakemigrate.signal.onsets.stalta.CentredSTALTAOnset(**kwargs)

Bases: STALTAOnset

QuakeMigrate default onset function class - uses a centred STA/LTA onset.

NOTE: THIS CLASS HAS BEEN DEPRECATED AND WILL BE REMOVED IN A FUTURE UPDATE

class quakemigrate.signal.onsets.stalta.ClassicSTALTAOnset(**kwargs)

Bases: STALTAOnset

QuakeMigrate default onset function class - uses a classic STA/LTA onset.

NOTE: THIS CLASS HAS BEEN DEPRECATED AND WILL BE REMOVED IN A FUTURE UPDATE

class quakemigrate.signal.onsets.stalta.STALTAOnset(**kwargs)

Bases: Onset

QuakeMigrate default onset function class - uses the Short-Term Average to Long-Term Average ratio of the signal energy amplitude.

Raw seismic data will be pre-processed, including re-sampling if necessary to reach the specified uniform sampling raate, checked against a user- specified set of data quality criteria, then used to calculate onset functions for each phase (using seismic channels as specified in channel_maps) by computing the STA/LTA of s^2.

phases

Which phases to calculate onset functions for. This will determine which phases are used for migration/picking. The selected phases must be present in the travel-time look-up table to be used for these purposes.

Type

list of str

bandpass_filters

Butterworth bandpass filter specification - keys are phases. [lowpass (Hz), highpass (Hz), corners*] *NOTE: two-pass filter effectively doubles the number of corners.

Type

dict of [float, float, int]

channel_maps

Data component maps - keys are phases. These are passed into the ObsPy.stream.select() method.

Type

dict of str

channel_counts

Number of channels to be used to calculate the onset function for each phase. Keys are phases.

Type

dict of int

sta_lta_windows

Short-term average (STA) and Long-term average (LTA) window lengths - keys are phases. [STA, LTA] (both in seconds)

Type

dict of [float, float]

all_channels

If True, only calculate an onset function when all requested channels meet the availability criteria. Otherwise, if at least one channel is available (e.g. just the N component for the S phase) the onset function will be calculated from that/those.

Type

bool

allow_gaps

If True, allow gappy data to be used to calculate the onset function. Gappy data will be detrended, tapered and filtered, then gaps padded with zeros. This should help mitigate the expected spikes as data goes on- and off-line, but will not eliminate it. Onset functions for periods with no data will be filled with ~ zeros (smallest possible float, to avoid divide by zero errors). NOTE: This feature is experimental and still under development.

Type

bool

full_timespan

If False, allow data which doesn’t cover the full timespan requested to be used for onset function calculation. This is a subtly different test to allow_gaps; data must be continuous within the timespan, but may not span the whole period. Data will be treated as described in allow_gaps. NOTE: This feature is experimental and still under development.

Type

bool

position

Compute centred STA/LTA (STA window is preceded by LTA window; value is assigned to end of LTA window / start of STA window) or classic STA/LTA (STA window is within LTA window; value is assigned to end of STA & LTA windows). Default: “classic”.

Centred gives less phase-shifted (late) onset function, and is closer to a Gaussian approximation, but is far more sensitive to data with sharp offsets due to instrument failures. We recommend using classic for detect() and centred for locate() if your data quality allows it. This is the default behaviour; override by setting this variable.

Type

str, optional

sampling_rate

Desired sampling rate for input data, in Hz; sampling rate at which the onset functions will be computed.

Type

int

signal_transform

Transformation to apply to the signal before taking the STA/LTA, to ensure the signal is always positive: energy (signal^2), absolute value, envelope (absolute value of the analytic signal), or envelope^2 (analytic - arguably more correct - measure of the energy of the signal). Default: “energy”

Type

{“energy”, “abs”, “env”, “env_squared”}, optional

min_onset_value

Minimum value at which to clip the onset function. This is the equivalent to setting a minimum SNR filter for which observations to include. The appropriate value will depend on the signal and noise characteristics, and the signal_transform selected. Default: 0.4 NOTE: must be greater than 0.01

Type

float, optional

calculate_onsets()

Generate onset functions that represent seismic phase arrivals.

gaussian_halfwidth()

Phase-appropriate Gaussian half-width estimate based on the short-term average window length.

calculate_onsets(data, timespan=None)

Calculate onset functions for the requested stations and phases.

Returns a stacked array of onset functions for the requested phases, and an OnsetData object containing all outputs from the onset function calculation: a dict of the onset functions, a Stream containing the pre-processed input waveforms, and a dict of availability info describing which of the requested onset functions could be calculated (depending on data availability and data quality checks).

Parameters

• data (WaveformData object) – Light class encapsulating data returned by an archive query.

• timespan (float or None, optional) – If the timespan for which the onsets are being generated is provided, this will be used to calculate the tapered window of data at the start and end of the onset function which should be disregarded. This is necessary to accurately set the pick threshold in GaussianPicker, for example.

Returns

• onsets (numpy.ndarray of float) – Stacked onset functions served up for migration, shape(nonsets, nsamples).

• onset_data (OnsetData object) – Light class encapsulating data generated during onset calculation.

gaussian_halfwidth(phase)

Return the phase-appropriate Gaussian half-width estimate based on the short-term average window length.

Parameters

phase ({'P', 'S'}) – Seismic phase for which to serve the estimate.

property onset_centred

Handle deprecated onset_centred kwarg / attribute

property p_bp_filter

Handle deprecated p_bp_filter kwarg / attribute

property p_onset_win

Handle deprecated p_onset_win kwarg / attribute

property post_pad

Post-pad is determined as a function of the max traveltime in the grid and the onset windows

property pre_pad

Pre-pad is determined as a function of the onset windows

property s_bp_filter

Handle deprecated s_bp_filter kwarg / attribute

property s_onset_win

Handle deprecated s_onset_win kwarg / attribute

quakemigrate.signal.onsets.stalta.centred_sta_lta_py(signal, nsta, nlta)

Calculates the ratio of the average of the signal in a short-term (signal) window to a preceding long-term (noise) window. STA/LTA value is assigned to the end of the LTA / one sample before the start of the STA. NOTE: signal must be non-negative.

Parameters

• signal (array-like) – Transformed non-negative seismic waveform.

• nsta (int) – Number of samples in short-term window.

• nlta (int) – Number of samples in long-term window.

Returns

sta / lta – Short-term average / long-term average ratio of the signal amplitude, computed in adjacent STA/LTA windows.

Return type

array-like

quakemigrate.signal.onsets.stalta.overlapping_sta_lta_py(signal, nsta, nlta)

Computes the standard STA/LTA from a given input array signal. The length of the STA window is given by nsta (in samples), nlta is the length of the LTA window (in samples). STA window fully overlaps with the LTA window, and is positioned to the “right” i.e. the end of both of the windows is at the latest point in time; this is where the STA / LTA value is assigned. NOTE: signal must be non-negative.

Parameters

• signal (~numpy.ndarray) – Transformed non-negative seismic waveform.

• nsta (int) – Length of short time average window in samples.

• nlta (int) – Length of long time average window in samples.

Returns

sta/lta – Short-term average / long-term average ratio of the signal amplitude, computed in overlapping STA/LTA windows.

Return type

~numpy.ndarray

quakemigrate.signal.onsets.stalta.pre_process(stream, sampling_rate, resample, upfactor, filter_, starttime, endtime)

Resample raw seismic data, detrend and apply cosine taper and zero phase-shift Butterworth band-pass filter; all carried out using the built-in obspy functions.

By default, data with mismatched sampling rates will only be decimated. If necessary, and if the user has specified resample = True and an upfactor to upsample by upfactor = int for the waveform archive, data can also be upsampled and then, if necessary, subsequently decimated to achieve the desired sampling rate.

For example, for raw input data sampled at a mix of 40, 50 and 100 Hz, to achieve a unified sampling rate of 50 Hz, the user would have to specify an upfactor of 5; 40 Hz x 5 = 200 Hz, which can then be decimated to 50 Hz.

NOTE: data will be detrended and a cosine taper applied before decimation, in order to avoid edge effects when applying the lowpass filter. See resample()

Parameters

• stream (obspy.Stream object) – Waveform data to be pre-processed.

• sampling_rate (int) – Desired sampling rate for data to be used to calculate onset. This will be achieved by resampling the raw waveform data. By default, only decimation will be applied, but data can also be upsampled if specified by the user when creating the Archive object.

• resample (bool, optional) – If true, perform resampling of data which cannot be decimated directly to the desired sampling rate. See resample()

• upfactor (int, optional) – Factor by which to upsample the data to enable it to be decimated to the desired sampling rate, e.g. 40Hz -> 50Hz requires upfactor = 5. See resample()

• filter (list) – Filter specifications, as [lowcut (Hz), highcut (Hz), order]. NOTE - two-pass filter effectively doubles the number of corners (order).

Returns

filtered_waveforms – Pre-processed seismic data.

Return type

obspy.Stream object

Raises

NyquistException – If the high-cut filter specified for the bandpass filter is higher than the Nyquist frequency of the sampling_rate.