3.6. quakemigrate.signal

The quakemigrate.signal module handles the core of the QuakeMigrate methods. This includes:

  • Generation of onset functions from raw data.

  • Picking of waveforms from onset functions.

  • Migration of onsets for detect() and locate().

  • Measurement of phase amplitudes and calculation of local earthquake magnitudes.

copyright

2020–2023, QuakeMigrate developers.

license

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

3.6.1. Subpackages

3.6.2. quakemigrate.signal.scan

Module to perform core QuakeMigrate functions: detect() and locate().

copyright

2020–2024, QuakeMigrate developers.

license

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

class quakemigrate.signal.scan.QuakeScan(archive, lut, onset, run_path, run_name, **kwargs)[source]

Bases: object

QuakeMigrate scanning class.

Provides an interface for the wrapped compiled C functions, used to perform the continuous scan (detect) or refined event migrations (locate).

Parameters

  • archive (Archive object) – Details the structure and location of a data archive and provides methods for reading data from file.

  • lut (LUT object) – Contains the traveltime lookup tables for seismic phases, computed for some pre-defined velocity model.

  • onset (Onset object) – Provides callback methods for calculation of onset functions.

  • run_path (str) – Points to the top level directory containing all input files, under which the specific run directory will be created.

  • run_name (str) – Name of the current QuakeMigrate run.

  • kwargs (**dict) – See QuakeScan Attributes for details. In addition to these:

continuous_scanmseed_write

Option to continuously write the .scanmseed file output by detect() at the end of every time step. Default behaviour is to write in day chunks where possible. Default: False.

Type

bool

cut_waveform_format

File format used when writing waveform data. We support any format also supported by ObsPy - “MSEED” (default), “SAC”, “SEGY”, “GSE2”.

Type

str, optional

log

Toggle for logging. If True, will output to stdout and generate a log file. Default is to only output to stdout.

Type

bool, optional

loglevel

Toggle to set the logging level: “debug” will print out additional diagnostic information to the log and stdout. (Default “info”)

Type

{“info”, “debug”}, optional

mags

Provides methods for calculating local magnitudes, performed during locate.

Type

LocalMag object, optional

marginal_window

Half-width of window centred on the maximum coalescence time. The 4-D coalescence functioned is marginalised over time across this window such that the earthquake location and associated uncertainty can be appropriately calculated. It should be an estimate of the time uncertainty in the earthquake origin time, which itself is some combination of the expected spatial uncertainty and uncertainty in the seismic velocity model used. Default: 2 seconds.

Type

float, optional

picker

Provides callback methods for phase picking, performed during locate.

Type

PhasePicker object, optional

plot_all_stns

If true, plot all stations in the LUT. Otherwise, only plot stations which were used for migration (i.e. omitting stations for which there was no data, or data did not pass the specified quality checks). Default: True.

Type

bool, optional

plot_event_summary

Plot event summary figure - see quakemigrate.plot for more details. Default: True.

Type

bool, optional

plot_event_video

Plot coalescence video for each located earthquake. Default: False.

Type

bool, optional

post_pad

Additional amount of data to read in after the timestep, used to ensure the correct coalescence is calculated at every sample.

Type

float

pre_pad

Additional amount of data to read in before the timestep, used to ensure the correct coalescence is calculated at every sample.

Type

float

real_waveform_units

Units to output real cut waveforms.

Type

{“displacement”, “velocity”}

run

Light class encapsulating i/o path information for a given run.

Type

Run object

scan_rate

Sampling rate at which the 4-D coalescence map will be calculated. Currently fixed to be the same as the onset function sampling rate (not user-configurable).

Type

int, optional

threads

The number of threads for the C functions to use on the executing host. Default: 1 thread.

Type

int, optional

timestep

Length (in seconds) of timestep used in detect(). Note: total detect run duration should be divisible by timestep. Increasing timestep will increase RAM usage during detect, but will slightly speed up overall detect run. Default: 120 seconds.

Type

float, optional

wa_waveform_units

Units to output Wood-Anderson simulated cut waveforms.

Type

{“displacement”, “velocity”}

write_cut_waveforms

Write raw cut waveforms for all data read from the archive for each event located by locate(). See ~quakemigrate.io.data.Archive parameter read_all_stations. Default: False. NOTE: this data has not been processed or quality-checked!

Type

bool, optional

write_marginal_coalescence

Write the marginalised 3-D coalescence map to file (in .npy format). Default: False.

Type

bool, optional

write_coalescence

Write the raw 4-D coalescence map from locate to file (in .npy format). Default: False.

Type

bool, optional

write_real_waveforms

Write real cut waveforms for all data read from the archive for each event located by locate(). See ~quakemigrate.io.data.Archive parameter read_all_stations. Default: False. NOTE: the units of this data (displacement or velocity) are controlled by real_waveform_units. NOTE: this data has not been processed or quality-checked! NOTE: no padding has been added to take into account the taper applied during response removal.

Type

bool, optional

write_wa_waveforms

Write Wood-Anderson simulated cut waveforms for all data read from the archive for each event located by locate(). See ~quakemigrate.io.data.Archive parameter read_all_stations. Default: False. NOTE: the units of this data (displacement or velocity) are controlled by wa_waveform_units. NOTE: this data has not been processed or quality-checked! NOTE: no padding has been added to take into account the taper applied during response removal.

Type

bool, optional

xy_files

Path to comma-separated value file (.csv) containing a series of coordinate files to plot. Columns: [“File”, “Color”, “Linewidth”, “Linestyle”], where “File” is the absolute path to the file containing the coordinates to be plotted. E.g: “/home/user/volcano_outlines.csv,black,0.5,-“. Each .csv coordinate file should contain coordinates only, with columns: [“Longitude”, “Latitude”]. E.g.: “-17.5,64.8”. Lines pre-pended with # will be treated as a comment - this can be used to include references. See the Volcanotectonic_Iceland example XY_files for a template.

Note

Do not include a header line in either file.

Type

str, optional

+++ TO BE REMOVED TO ARCHIVE CLASS +++
pre_cut

Specify how long before the event origin time to cut the waveform data from.

Type

float, optional

post_cut

Specify how long after the event origin time to cut the waveform. data to

Type

float, optional

+++ TO BE REMOVED TO ARCHIVE CLASS +++
detect(starttime, endtime)[source]

Core detection method – compute decimated 3-D coalescence continuously throughout entire time period; output as .scanmseed (in mSEED format).

locate(starttime, endtime) or locate(file)[source]

Core locate method – compute 3-D coalescence over short time window around candidate earthquake triggered from continuous detect output; output location & uncertainties (.event file), phase picks (.picks file), plus multiple optional plots / data for further analysis and processing.

Raises

  • OnsetTypeError – If an object is passed in through the onset argument that is not derived from the Onset base class.

  • PickerTypeError – If an object is passed in through the picker argument that is not derived from the PhasePicker base class.

  • RuntimeError – If the user does not supply the locate function with valid arguments.

  • TimeSpanException – If the user supplies a starttime that is after the endtime.

detect(starttime, endtime)[source]

Scans through data calculating coalescence in a (decimated) 3-D grid by continuously migrating onset functions.

Parameters

  • starttime (str) – Timestamp from which to run continuous scan.

  • endtime (str) – Timestamp up to which to run continuous scan. Note: if the duration is not divisible by the specified timestep, the endtime will be extended to accommodate. If the endtime is set to midnight, then it will be automatically adjusted to one sample prior.

locate(starttime=None, endtime=None, trigger_file=None)[source]

Re-computes the coalescence on an undecimated grid for a short time window around each candidate earthquake triggered from the (decimated) continuous detect scan. Calculates event location and uncertainties, makes phase arrival picks, plus multiple optional plotting / data outputs for further analysis and processing.

Parameters

  • starttime (str, optional) – Timestamp from which to include events in the locate scan.

  • endtime (str, optional) – Timestamp up to which to include events in the locate scan. Note: if the endtime is set to midnight, then only events during the previous day will be included.

  • trigger_file (str, optional) – File containing triggered events to be located.

property n_cores

Handler for deprecated attribute name ‘n_cores’

property sampling_rate

Get sampling_rate

property scan_rate

Get scan_rate

property time_step

Handler for deprecated attribute name ‘time_step’

3.6.3. quakemigrate.signal.trigger

Module to perform the trigger stage of QuakeMigrate.

copyright

2020–2024, QuakeMigrate developers.

license

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

class quakemigrate.signal.trigger.Trigger(lut, run_path, run_name, **kwargs)[source]

Bases: object

QuakeMigrate triggering class.

Triggers candidate earthquakes from the continuous maximum coalescence through time data output by the decimated detect scan, ready to be run through locate().

Parameters

  • lut (LUT object) – Contains the traveltime lookup tables for the selected seismic phases, computed for some pre-defined velocity model.

  • run_path (str) – Points to the top level directory containing all input files, under which the specific run directory will be created.

  • run_name (str) – Name of the current QuakeMigrate run.

  • kwargs (**dict) –

    See Trigger Attributes for details. In addition to these: log : bool, optional

    Toggle for logging. If True, will output to stdout and generate a log file. Default is to only output to stdout.

    loglevel{“info”, “debug”}, optional

    Toggle to set the logging level: “debug” will print out additional diagnostic information to the log and stdout. (Default “info”)

    trigger_namestr

    Optional name of a sub-run - useful when testing different trigger parameters, for example.

mad_window_length

Length of window within which to calculate the Median Absolute Deviation, for the “mad” trigger threshold method. Default: 3600 seconds (1 hour).

Type

float, optional

mad_multiplier

A scaling factor for the MAD output to determine the number of median absolute deviations above the median value of the coalescence trace to set the trigger threshold; for the “mad” trigger threshold method. Default: 8.0.

Type

float, optional

marginal_window

Half-width of window centred on the maximum coalescence time. The 4-D coalescence functioned is marginalised over time across this window such that the earthquake location and associated uncertainty can be appropriately calculated. It should be an estimate of the time uncertainty in the earthquake origin time, which itself is some combination of the expected spatial uncertainty and uncertainty in the seismic velocity model used. Default: 2 seconds.

Type

float, optional

min_event_interval

Minimum time interval between triggered events. Must be at least twice the marginal window. Default: 4 seconds.

Type

float, optional

median_window_length

Length of window within which to calculate the median of the coalescence trace, for the “median_ratio” trigger threshold method. Default: 3600 seconds (1 hour).

Type

float, optional

median_multiplier

A scaling factor by which to multiply the median of the coalescence trace to set the trigger threshold; for the “median ratio” trigger threshold method. Default: 1.2.

Type

float, optional

normalise_coalescence

If True, triggering is performed on the maximum coalescence normalised by the mean coalescence value in the 3-D grid. Default: False.

Type

bool, optional

pad

Additional time padding to ensure events close to the starttime/endtime are not cut off and missed. Default: 120 seconds.

Type

float, optional

plot_trigger_summary

Plot triggering through time for each batched segment. Default: True.

Type

bool, optional

run

Light class encapsulating i/o path information for a given run.

Type

Run object

static_threshold

Static threshold value above which to trigger candidate events.

Type

float, optional

threshold_method

Toggle between a “static” threshold and a selection of dynamic threshold methods; either based on the Median Absolute Deviation (“mad”) or a multiple of the median value of the coalescence trace (“median_ratio”). Default: “static”.

Type

str, optional

smooth_coa

Whether to apply a gaussian smoothing to the coalescence trace before applying the trigger threshold to identify candidate events. Default: False

Type

bool, optional

smoothing_kernel_sigma

Sigma (standard deviation) of the Gaussian kernel to convolve with the coalescence trace, to be used with ‘smooth_coa’. Default: 0.2 seconds.

Type

float, optional

smoothing_kernel_width

Number of standard deviations at which to truncate the Gaussian kernel. See ~scipy.ndimage.gaussian_filter1d for more information. To be used with ‘smooth_coa’. Default: 4.0.

Type

float, optional

xy_files

Path to comma-separated value file (.csv) containing a series of coordinate files to plot. Columns: [“File”, “Color”, “Linewidth”, “Linestyle”], where “File” is the absolute path to the file containing the coordinates to be plotted. E.g: “/home/user/volcano_outlines.csv,black,0.5,-“. Each .csv coordinate file should contain coordinates only, with columns: [“Longitude”, “Latitude”]. E.g.: “-17.5,64.8”. Lines pre-pended with # will be treated as a comment - this can be used to include references. See the Volcanotectonic_Iceland example XY_files for a template.

Note

Do not include a header line in either file.

Type

str, optional

plot_all_stns

If true, plot all stations used for detect. Otherwise, only plot stations which for which some data was available during the trigger time window. NOTE: if no station availability data is found, all stations in the LUT will be plotted. (Default: True)

Type

bool, optional

write_event_time_windows

If true, write out the MinTime and MaxTime of the trigger window for each triggered event (corresponding to the minimum event interval plus the window during which the coalescence value is above the trigger threshold). This option is mainly a convenience for post-hoc plotting.

Type

bool, optional

trigger(starttime, endtime, region=None, interactive_plot=False)[source]

Trigger candidate earthquakes from decimated detect scan results.

Raises
property min_event_interval

Get and set the minimum event interval.

property minimum_repeat

Handler for deprecated attribute name ‘minimum_repeat’.

property threshold_method

Get and set the threshold method.

trigger(starttime, endtime, region=None, interactive_plot=False)[source]

Trigger candidate earthquakes from decimated scan data.

Parameters

  • starttime (str) – Timestamp from which to trigger events.

  • endtime (str) – Timestamp up to which to trigger events.

  • region (list of floats, optional) –

    Only retain triggered events located within this region. Format is:

    [Xmin, Ymin, Zmin, Xmax, Ymax, Zmax]

    As longitude / latitude / depth (units corresponding to the lookup table grid projection; in positive-down frame).

  • interactive_plot (bool, optional) – Toggles whether to produce an interactive plot. Default: False.

Raises

TimeSpanException – If starttime is after endtime.

quakemigrate.signal.trigger.chunks2trace(a, new_shape)[source]

Create a trace filled with chunks of the same value.

3.6. Parameters:

aarray-like

Array of chunks.

new_shapetuple of ints

(number of chunks, chunk_length).

3.6. Returns:

barray-like

Single array of values contained in a.