3.6.1.3. quakemigrate.signal.local_mag

The quakemigrate.local_mag extension module handles the calculation of local magnitudes from Wood-Anderson simulated waveforms.

Warning

The local_mag modules are an ongoing work in progress. We hope to continue to extend their functionality, which may result in some API changes. If you have comments or suggestions, please contact the QuakeMigrate developers at: quakemigrate.developers@gmail.com, or submit an issue on GitHub.

copyright: 2020–2023, QuakeMigrate developers.
license: GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

3.6.1.3.1. quakemigrate.signal.local_mag.local_mag

Module containing methods to calculate the local magnitude for an event located by QuakeMigrate.

copyright: 2020–2023, QuakeMigrate developers.
license: GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

class quakemigrate.signal.local_mag.local_mag.LocalMag(amp_params, mag_params, plot_amplitudes=True)[source]

Bases: object

QuakeMigrate extension class for calculating local magnitudes.

Provides functions for measuring amplitudes of earthquake waveforms and using these to calculate local magnitudes.

Parameters

amp_params (dict) –
All keys are optional, including: signal_window : float

Length of S-wave signal window, in addition to the time window associated with the marginal_window and traveltime uncertainty. (Default 0 s)

noise_windowfloat
Length of the time window before the P-wave signal window in which to measure the noise amplitude. (Default 10 s)

noise_measure{“RMS”, “STD”, “ENV”}
Method by which to measure the noise amplitude; root-mean-quare, standard deviation or average amplitude of the envelope of the signal. (Default “RMS”)

loc_method{“spline”, “gaussian”, “covariance”}
Which event location estimate to use. (Default “spline”)

highpass_filterbool
Whether to apply a highpass filter to the data before measuring amplitudes. (Default False)

highpass_freqfloat
High-pass filter frequency. Required if highpass_filter is True.

bandpass_filterbool
Whether to apply a band-pass filter before measuring amplitudes. (Default: False)

bandpass_lowcutfloat
Band-pass filter low-cut frequency. Required if bandpass_filter is True.

bandpass_highcutfloat
Band-pass filter high-cut frequency. Required if bandpass_filter is True.

filter_cornersint
Number of corners for the chosen filter. Default: 4.

prominence_multiplierfloat
To set a prominence filter in the peak-finding algorithm. (Default 0. = off). NOTE: not recommended for use in combination with a filter; filter gain corrections can lead to spurious results. Please see the scipy.signal.find_peaks documentation for further guidance.
mag_params (dict) –
Required keys: A0 : str or func

Name of the attenuation function to use. Available options include {“Hutton-Boore”, “keir2006”, “UK”, …}. Alternatively specify a function which returns the attenuation factor at a specified (epicentral or hypocentral) distance. (Default “Hutton-Boore”)

All other keys are optional, including: station_corrections : dict {str : float}

Dictionary of trace_id : magnitude-correction pairs. (Default None)

amp_feature{“S_amp”, “P_amp”}
Which phase amplitude measurement to use to calculate local magnitude. (Default “S_amp”)

amp_multiplierfloat
Factor by which to multiply all measured amplitudes.

use_hyp_distbool, optional
Whether to use the hypocentral distance instead of the epicentral distance in the local magnitude calculation. (Default False)

trace_filterregex expression
Expression by which to select traces to use for the mean_magnitude calculation. E.g. ‘.*H[NE]$’. (Default None)

station_filterlist of str
List of stations to exclude from the mean_magnitude calculation. E.g. [“KVE”, “LIND”]. (Default None)

dist_filterfloat or False
Whether to only use stations less than a specified (epicentral or hypocentral) distance from an event in the mean_magnitude() calculation. Distance in kilometres. (Default False)

pick_filterbool
Whether to only use stations where at least one phase was picked by the autopicker in the mean_magnitude calculation. (Default False)

noise_filterfloat
Factor by which to multiply the measured noise amplitude before excluding amplitude observations below the noise level. (Default 1.)

weighted_meanbool
Whether to do a weighted mean of the magnitudes when calculating the mean_magnitude. (Default False)
plot_amplitudes (bool, optional) – Plot amplitudes vs. distance plot for each event. (Default True)

amp

The Amplitude object for this instance of LocalMag. Contains functions to measure Wood-Anderson corrected displacement amplitudes for an event.

Type: Amplitude object

mag

The Magnitude object for this instance of LocalMag. Contains functions to calculate magnitudes from Wood-Anderson corrected displacement amplitudes, and to combine them into a single magnitude estimate for the event.

Type: Magnitude object

calc_magnitude(event, lut, run)[source]

calc_magnitude(event, lut, run)[source]

Wrapper function to calculate the local magnitude of an event by first making Wood-Anderson corrected displacement amplitude measurements on each trace, then calculating magnitudes from these individual measurements, and a network-averaged (weighted) mean magnitude estimate and associated uncertainty.

Additional functionality includes calculating an r^2 fit of the predicted amplitude with distance curve to the observed amplitudes, and an associated plot of amplitudes vs. distance.

Parameters

event (Event object) – Light class encapsulating waveform data, onset, pick and location information for a given event.
lut (LUT object) – Contains the traveltime lookup tables for seismic phases, computed for some pre-defined velocity model.
run (Run object) – Light class encapsulating waveforms, coalescence information, picks and location information for a given event.

Returns

event (Event object) – Light class encapsulating waveforms, coalescence information, picks and location information for a given event. Now also contains local magnitude information.
mag (float) – Network-averaged local magnitude estimate for this event.

3.6.1.3.2. quakemigrate.signal.local_mag.amplitude

Module containing methods to measure Wood-Anderson corrected waveform amplitudes to be used for local magnitude calculation.

copyright: 2020–2023, QuakeMigrate developers.
license: GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

class quakemigrate.signal.local_mag.amplitude.Amplitude(amplitude_params={})[source]

Bases: object

Part of the QuakeMigrate LocalMag class; measures Wood-Anderson corrected waveform amplitudes to be used for local magnitude calculation.

Simulates the Wood-Anderson waveforms using a user-supplied set of response removal parameters, then measures the maximum peak-to-trough amplitude in time windows around the P and S phase arrivals. These windows are calculated from the phase pick times from the autopicker, if available, or from the modelled pick times. The length of the S-wave signal window is calculated according to a user-specified signal_window parameter.

The user may optionally specify a filter to apply to the waveforms before amplitudes are measured, in order (for example) to reduce the impact of high-amplitude noise associated with the oceanic microseisms on the measurement of low-amplitude wavetrains associated with microseismic events. Note this will generally result in an underestimate of the true earthquake waveform amplitude, even when the filter gain is corrected for.

A measurement of the signal amplitude in a window preceding the P-wave arrival is used to characterise the “noise” amplitude. This can be used to filter out null observations, and to provide an estimate of the uncertainty on the max amplitude measurements contributed by extraneous noise.

signal_window

Length of S-wave signal window, in addition to the time window associated with the marginal_window and traveltime uncertainty. (Default 0 s)

Type: float

noise_window

Length of the time window before the P-wave signal window in which to measure the noise amplitude. (Default 5 s)

Type: float

noise_measure

Method by which to measure the noise amplitude; root-mean-quare, standard deviation or average amplitude of the envelope of the signal. (Default “RMS”)

Type: {“RMS”, “STD”, “ENV”}

loc_method

Which event location estimate to use. (Default “spline”)

Type: {“spline”, “gaussian”, “covariance”}

highpass_filter

Whether to apply a high-pass filter before measuring amplitudes. (Default False)

Type: bool

highpass_freq

High-pass filter frequency. Required if highpass_filter is True.

Type: float

bandpass_filter

Whether to apply a band-pass filter before measuring amplitudes. (Default False)

Type: bool

bandpass_lowcut

Band-pass filter low-cut frequency. Required if bandpass_filter is True.

Type: float

bandpass_highcut

Band-pass filter high-cut frequency. Required if bandpass_filter is True.

Type: float

filter_corners

number of corners for the chosen filter. (Default 4)

Type: int

prominence_multiplier

To set a prominence filter in the peak-finding algorithm. (Default 0. = off) NOTE: not recommended for use in combination with a filter; filter gain corrections can lead to spurious results. Please see the scipy.signal.find_peaks documentation for further guidance.

Type: float

get_amplitudes(event, lut)[source]

Raises

AttributeError – If both highpass_filter and bandpass_filter are selected, or if the user selects to apply a filter but does not provide the relevant frequencies.
AttributeError – If response removal parameters are provided here instead of to the Archive object.

get_amplitudes(event, lut)[source]

Measure phase amplitudes for an event.

Parameters

event (Event object) – Light class encapsulating waveforms, coalescence information, picks and location information for a given event.
lut (LUT object) – Contains the traveltime lookup tables for seismic phases, computed for some pre-defined velocity model.

Returns

amplitudes – P- and S-wave amplitude measurements for each component of each station in the look-up table. Columns:

epi_distfloat
Epicentral distance between the station and the event hypocentre.

z_distfloat
Vertical distance between the station and the event hypocentre.

P_ampfloat
Half maximum peak-to-trough amplitude in the P signal window. In millimetres. Corrected for filter gain, if applicable.

P_freqfloat
Approximate frequency of the maximum amplitude P-wave signal. Calculated from the peak-to-trough time interval of the max peak-to-trough amplitude.

P_timeobspy.UTCDateTime object
Approximate time of amplitude observation (halfway between peak and trough times).

P_avg_ampfloat
Average amplitude in the P signal window, measured by the same method as the Noise_amp (see noise_measure) and corrected for the same filter gain as P_amp. In millimetres.

P_filter_gainfloat or NaN
Filter gain at P_freq - which has been corrected for in the P_amp measurements - if a filter was applied prior to amplitude measurement; Else NaN.

S_ampfloat
As for P, but in the S wave signal window.

S_freqfloat
As for P.

S_timeobspy.UTCDateTime object
As for P.

S_avg_ampfloat
As for P.

S_filter_gainfloat or NaN.
As for P.

Noise_ampfloat
The average signal amplitude in the noise window. In millimetres. See noise_measure parameter.

is_pickedbool
Whether at least one of the phase arrivals was picked by the autopicker.

Index = Trace ID (see obspy.Trace object property ‘id’)

Return type

pandas.DataFrame object

pad(marginal_window, max_tt, fraction_tt)[source]

Calculate padding, including an allowance for the taper applied when filtering/ removing instrument response, to ensure the noise and signal window amplitude measurements are not affected by the taper.

Parameters

marginal_window (float) – Half-width of window centred on the maximum coalescence time of the event over which the 4-D coalescence function is marginalised. Used here as an estimate of the origin time uncertainity when calculating the signal windows.
max_tt (float) – Maximum traveltime in the look-up table.
fraction_tt (float) – An estimate of the uncertainty in the velocity model as a function of a fraction of the traveltime. (Default 0.1 == 10%)

Returns

pre_pad (float) – Time window by which to pre-pad the data when reading from the waveform archive.
post_pad (float) – Time window by which to post-pad the data when reading from the waveform archive.

3.6.1.3.3. quakemigrate.signal.local_mag.magnitude

Module that supplies functions to calculate magnitudes from observations of trace amplitudes, earthquake location, station locations, and an estimated attenuation curve for the region of interest.

copyright: 2020–2023, QuakeMigrate developers.
license: GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

class quakemigrate.signal.local_mag.magnitude.Magnitude(magnitude_params={})[source]

Bases: object

Part of the QuakeMigrate LocalMag class; calculates local magnitudes from Wood-Anderson corrected waveform amplitude measurements.

Takes waveform amplitude measurements from the LocalMag Amplitude class, and from these calculates local magnitude estimates using a local magnitude attenuation function. Magnitude corrections for individual stations and channels thereof can be applied, if provided.

Individual estimates are then combined to calculate a network-averaged (weighted) mean local magnitude for the event. Also includes the function to measure the r-squared statistic assessing the goodness of fit between the predicted amplitude with distance from the nework-averaged local magnitude for the event and chosen attenuation function, and the observed amplitudes. This, provides a tool to distinguish between real microseismic events and artefacts.

A summary plot illustrating the amplitude observations, their uncertainties, and the predicted amplitude with distance for the network-averaged local magnitude (and its uncertainties) can optionally be output.

A0

Name of the attenuation function to use. Available options include {“Hutton-Boore”, “keir2006”, “UK”, …}. Alternatively specify a function which returns the attenuation factor at a specified (epicentral or hypocentral) distance. (Default “Hutton-Boore”)

Type: str or func

use_hyp_dist

Whether to use the hypocentral distance instead of the epicentral distance in the local magnitude calculation. (Default False)

Type: bool, optional

amp_feature

Which phase amplitude measurement to use to calculate local magnitude. (Default “S_amp”)

Type: {“S_amp”, “P_amp”}

station_corrections

Dictionary of trace_id : magnitude-correction pairs. (Default None)

Type: dict {str : float}

amp_multiplier

Factor by which to multiply all measured amplitudes.

Type: float

weighted_mean

Whether to use a weighted mean to calculate the network-averaged local magnitude estimate for the event. (Default False)

Type: bool

trace_filter

Expression by which to select traces to use for the mean_magnitude calculation. E.g. “.*H[NE]$” . (Default None)

Type: regex expression

noise_filter

Factor by which to multiply the measured noise amplitude before excluding amplitude observations below the noise level. (Default 1.)

Type: float

station_filter

List of stations to exclude from the mean_magnitude calculation. E.g. [“KVE”, “LIND”]. (Default None)

Type: list of str

dist_filter

Whether to only use stations less than a specified (epicentral or hypocentral) distance from an event in the mean_magnitude() calculation. Distance in kilometres. (Default False)

Type: float or False

pick_filter

Whether to only use stations where at least one phase was picked by the autopicker in the mean_magnitude calculation. (Default False)

Type: bool

r2_only_used

Whether to only use amplitude observations which were used for the mean magnitude calculation when calculating the r-squared statistic for the goodness of fit between the measured and predicted amplitudes. Default: True; False is an experimental feature - use with caution.

Type: bool

calculate_magnitudes(amplitudes)[source]

mean_magnitude(magnitudes)[source]

plot_amplitudes(event, run)[source]

Raises

TypeError – If the user does not specify an A0 attenuation curve.
ValueError – If the user specifies an invalid A0 attenuation curve.

calculate_magnitudes(amplitudes)[source]

Calculate magnitude estimates from amplitude measurements on individual stations /components.

Parameters

amplitudes (pandas.DataFrame object) –

P- and S-wave amplitude measurements for each component of each station in the look-up table. Columns:

epi_distfloat
Epicentral distance between the station and the event hypocentre.

z_distfloat
Vertical distance between the station and the event hypocentre.

P_ampfloat
Half maximum peak-to-trough amplitude in the P signal window. In millimetres. Corrected for filter gain, if applicable.

P_freqfloat
Approximate frequency of the maximum amplitude P-wave signal. Calculated from the peak-to-trough time interval of the max peak-to-trough amplitude.

P_timeobspy.UTCDateTime object
Approximate time of amplitude observation (halfway between peak and trough times).

P_avg_ampfloat
Average amplitude in the P signal window, measured by the same method as the Noise_amp (see noise_measure) and corrected for the same filter gain as P_amp. In millimetres.

P_filter_gainfloat or NaN
Filter gain at P_freq - which has been corrected for in the P_amp measurements - if a filter was applied prior to amplitude measurement; Else NaN.

S_ampfloat
As for P, but in the S wave signal window.

S_freqfloat
As for P.

S_timeobspy.UTCDateTime object
As for P.

S_avg_ampfloat
As for P.

S_filter_gainfloat or NaN.
As for P.

Noise_ampfloat
The average signal amplitude in the noise window. In millimetres. See noise_measure parameter.

is_pickedbool
Whether at least one of the phase arrivals was picked by the autopicker.

Index = Trace ID (see obspy.Trace object property ‘id’)

Returns

magnitudes – The original amplitudes DataFrame, with columns containing the calculated magnitude and an associated error now added. Columns = [“epi_dist”, “z_dist”, “P_amp”, “P_freq”, “P_time”,

”P_avg_amp”, “P_filter_gain”, “S_amp”, “S_freq”, “S_time”, “S_avg_amp”, “S_filter_gain”, “Noise_amp”, “is_picked”, “ML”, “ML_Err”]

Index = Trace ID (see obspy.Trace.id) Additional fields: ML : float

Magnitude calculated from the chosen amplitude measurement, using the specified attenuation curve and station_corrections.

ML_Errfloat: Estimate of the error on the calculated magnitude, based on potential errors in the maximum amplitude measurement according to the measured noise amplitude.

Return type

pandas.DataFrame object

Raises

AttributeError – If A0 attenuation correction is not specified.

mean_magnitude(magnitudes)[source]

Calculate the network-averaged local magnitude for an event based on the magnitude estimates calculated from amplitude measurements made on each component of each station.

The user may specify distance, station, channel and a number of other filters to restrict which observations are included in this best estimate of the local magnitude of the event.

Parameters

magnitudes (pandas.DataFrame object) –

Contains P- and S-wave amplitude measurements for each component of each station in the look-up table, and local magnitude estimates calculated from them (output by calculate_magnitudes()). Note that the amplitude observations are raw, but the ML estimates derived from them include station corrections, if provided. Columns:

epi_distfloat
Epicentral distance between the station and the event hypocentre.

z_distfloat
Vertical distance between the station and the event hypocentre.

P_ampfloat
Half maximum peak-to-trough amplitude in the P signal window. In millimetres. Corrected for filter gain, if applicable.

P_freqfloat
Approximate frequency of the maximum amplitude P-wave signal. Calculated from the peak-to-trough time interval of the max peak-to-trough amplitude.

P_timeobspy.UTCDateTime object
Approximate time of amplitude observation (halfway between peak and trough times).

P_avg_ampfloat
Average amplitude in the P signal window, measured by the same method as the Noise_amp (see noise_measure) and corrected for the same filter gain as P_amp. In millimetres.

P_filter_gainfloat or NaN
Filter gain at P_freq - which has been corrected for in the P_amp measurements - if a filter was applied prior to amplitude measurement; Else NaN.

S_ampfloat
As for P, but in the S wave signal window.

S_freqfloat
As for P.

S_timeobspy.UTCDateTime object
As for P.

S_avg_ampfloat
As for P.

S_filter_gainfloat or NaN.
As for P.

Noise_ampfloat
The average signal amplitude in the noise window. In millimetres. See noise_measure parameter.

is_pickedbool
Whether at least one of the phase arrivals was picked by the autopicker.

MLfloat
Magnitude calculated from the chosen amplitude measurement, using the specified attenuation curve and station_corrections.

ML_Errfloat
Estimate of the error on the calculated magnitude, based on potential errors in the maximum amplitude measurement according to the measured noise amplitude.

Index = Trace ID (see obspy.Trace object property ‘id’)

Returns

mean_mag (float or NaN) – Network-averaged local magnitude estimate for the event. Mean (or weighted mean) of the magnitude estimates calculated from each individual channel after optionally removing some observations based on trace ID, distance, etcetera.
mean_mag_err (float or NaN) – Standard deviation (or weighted standard deviation) of the magnitude estimates calculated from individual channels which contributed to the calculation of the (weighted) mean magnitude.
mag_r_squared (float or NaN) – r-squared statistic describing the fit of the amplitude vs. distance curve predicted by the calculated mean_mag and chosen attenuation model to the measured amplitude observations. This is intended to be used to help discriminate between ‘real’ events, for which the predicted amplitude vs. distance curve should provide a good fit to the observations, from artefacts, which in general will not.

plot_amplitudes(magnitudes, event, run, unit_conversion_factor, noise_measure='RMS')[source]

Plot a figure showing the measured amplitude with distance vs. predicted amplitude with distance derived from mean_mag and the chosen attenuation model.

The amplitude observations (both for noise and signal amplitudes) are corrected according to the same station corrections that were used in calculating the individual local magnitude estimates that were used to calculate the network-averaged local magnitude for the event.

Parameters

magnitudes (pandas.DataFrame object) –
Contains P- and S-wave amplitude measurements for each component of each station in the look-up table, and local magnitude estimates calculated from them (output by calculate_magnitudes()). Note that the amplitude observations are raw, but the ML estimates derived from them include station corrections, if provided. Columns = [“epi_dist”, “z_dist”, “P_amp”, “P_freq”, “P_time”, “P_avg_amp”,

”P_filter_gain”, “S_amp”, “S_freq”, “S_time”, “S_avg_amp”, “S_filter_gain”, “Noise_amp”, “is_picked”, “ML”, “ML_Err”, “Noise_Filter”, “Trace_Filter”, “Station_Filter”, “Dist_Filter”, “Dist”, “Used”]
event (Event object) – Light class encapsulating waveforms, coalescence information, picks and location information for a given event.
run (Run object) – Light class encapsulating i/o path information for a given run.
unit_conversion_factor (float) – A conversion factor based on the lookup table grid projection, used to ensure the location uncertainties have units of kilometres.