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, 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, 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: pre_filt : tuple of floats

Pre-filter to apply during the instrument response removal. E.g. (0.03, 0.05, 30., 35.) - all in Hz. (Default None)

water_level : float

Water level to use in instrument response removal. (Default 60)

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_window : float

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”}

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

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

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

remove_full_response : bool

Whether to remove the full response (including the effect of digital FIR filters) or just the instrument transform function (as defined by the PolesZeros Response Stage. Significantly slower. (Default False)

highpass_filter : bool

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

highpass_freq : float

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

bandpass_filter : bool

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

bandpass_lowcut : float

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

bandpass_highcut : float

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

filter_corners : int

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

prominence_multiplier : float

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_multiplier : float

Factor by which to multiply all measured amplitudes.

use_hyp_dist : bool, optional

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

trace_filter : regex expression

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

station_filter : list of str

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

dist_filter : float 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_filter : bool

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

noise_filter : float

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

weighted_mean : bool

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 i/o path information for a given run.

Returns:

event (Event object) – Light class encapsulating waveform data, onset, pick 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, 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.

pre_filt¶

Pre-filter to apply during the instrument response removal. E.g. (0.03, 0.05, 30., 35.) - all in Hz. (Default None)

Type:	tuple of floats

water_level¶

Water level to use in instrument response removal. (Default 60.)

Type:	float

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 or standard deviation of the signal. (Default “RMS”)

Type:	{“RMS”, “STD”}

loc_method¶

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

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

remove_full_response¶

Whether to remove the full response (including the effect of digital FIR filters) or just the instrument transform function (as defined by the PolesZeros Response Stage). Significantly slower. (Default False)

Type:	bool

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.

get_amplitudes(event, lut)[source]

Measure phase amplitudes for an event.

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.

Returns:

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

epi_dist : float

Epicentral distance between the station and the event hypocentre.

z_dist : float

Vertical distance between the station and the event hypocentre.

P_amp : float

Half maximum peak-to-trough amplitude in the P signal window. In millimetres.

P_freq : float

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

P_time : obspy.UTCDateTime object

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

S_amp : float

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

S_freq : float

As for P.

S_time : obspy.UTCDateTime object

As for P.

Noise_amp : float

An estimate of the signal amplitude in the noise window. In millimetres.

is_picked : bool

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

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, 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

calculate_magnitudes(amplitudes)[source]¶

mean_magnitude(magnitudes)[source]¶

plot_amplitudes(event, run)[source]¶

Raises:	`AttributeError` – 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 station file. Columns: epi_dist : float Epicentral distance between the station and the event hypocentre. z_dist : float Vertical distance between the station and the event hypocentre. P_amp : float Half maximum peak-to-trough amplitude in the P signal window. In millimetres. P_freq : float Approximate frequency of the maximum amplitude P-wave signal. Calculated from the peak-to-trough time of the max peak-to-trough amplitude. P_time : obspy.UTCDateTime object Approximate time of amplitude observation (halfway between peak and trough times). S_amp : float As for P, but in the S wave signal window. S_freq : float As for P. S_time : obspy.UTCDateTime object As for P. Noise_amp : float An estimate of the signal amplitude in the noise window. In millimetres. is_picked : bool 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”, ”S_amp”, “S_freq”, “S_time”, “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_Err : float 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) –

Contains P- and S-wave amplitude measurements for each component of each station in the station file, 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 : float

Epicentral distance between the station and the event hypocentre.

z_dist : float

Vertical distance between the station and the event hypocentre.

P_amp : float

Half maximum peak-to-trough amplitude in the P signal window. In millimetres.

P_freq : float

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

P_time : obspy.UTCDateTime object

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

S_amp : float

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

S_freq : float

As for P.

S_time : obspy.UTCDateTime object

As for P.

Noise_amp : float

An estimate of the signal amplitude in the noise window. In millimetres.

is_picked : bool

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

ML : float

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

ML_Err : float

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 station file, 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”,

”S_amp”, “S_freq”, “S_time”, “Noise_amp”, “is_picked”, “ML”, “ML_Err”, “Noise_Filter”, “Trace_Filter”, “Station_Filter”, “Dist_Filter”, “Dist”, “Used”]
event (Event object) – Light class encapsulating waveform data, onset, pick, location and local magnitude 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.