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)[source]

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()[source]: Generate onset functions that represent seismic phase arrivals

pad(timespan)[source]: Create appropriate padding to include the taper.

abstract calculate_onsets()[source]: Method stub for calculation of onset functions.

gaussian_halfwidth(phase)[source]: Method stub for Gaussian half-width estimate.

pad(timespan)[source]

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)[source]

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–2023, 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)[source]

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)[source]

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)[source]

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

calculate_onsets()[source]: Generate onset functions that represent seismic phase arrivals.

gaussian_halfwidth()[source]: Phase-appropriate Gaussian half-width estimate based on the short-term average window length.

calculate_onsets(data, log=True, timespan=None)[source]

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.
log (bool) – Calculate log(onset) if True, otherwise calculate the raw onset.
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)[source]

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.pre_process(stream, sampling_rate, resample, upfactor, filter_, starttime, endtime)[source]

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.

quakemigrate.signal.onsets.stalta.sta_lta_centred(signal, nsta, nlta)[source]

Calculates the ratio of the average of a^2 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.

Parameters

signal (array-like) – Signal array
nsta (int) – Number of samples in short-term window
nlta (int) – Number of samples in long-term window

Returns

sta / lta – Ratio of a^2 in a short term average window to a preceding long term average window. STA/LTA value is assigned to end of LTA window / one sample before the start of STA window – “centred”.

Return type

array-like