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.
  • Raw scan for detect and locate.
  • Measurement of amplitudes and calculation of local earthquake magnitudes.
copyright:2020, QuakeMigrate developers.
license:GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.html)

3.6.2. quakemigrate.signal.scan

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

copyright:2020, 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_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
run

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

Type:Run object
sampling_rate

Desired sampling rate of input data; sampling rate at which to compute the coalescence function. Default: 50 Hz.

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
write_cut_waveforms

Write raw cut waveforms for all data found in the archive for each event located by locate(). Default: False. Note: this data has not been processed or quality-checked!

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 coastream; 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 does not derive from the Onset base class.
  • PickerTypeError – If an object is passed in through the picker argument that does not derive 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.
  • NoMagObjectError – If the user selects to calculate magnitudes but does not provide a LocalMag object.
detect(starttime, endtime)[source]

Scans through continuous data calculating coalescence on a (decimated) 3-D grid by back-migrating onset (characteristic) functions.

Parameters:
  • starttime (str) – Timestamp from which to run continuous scan (detect).
  • endtime (str) – Timestamp up to which to run continuous scan (detect). Note: the last sample returned will be that which immediately precedes this timestamp.
locate(starttime=None, endtime=None, trigger_file=None)[source]

Re-computes the 3-D 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.
  • trigger_file (str, optional) – File containing triggered events to be located.
n_cores

Handler for deprecated attribute name ‘n_cores’

sampling_rate

Get sampling_rate

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, 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 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 P- and S-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_name : str
    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 Average Deviation. Default: 3600 seconds (1 hour).

Type:float, optional
mad_multiplier

A scaling factor for the MAD output to make the calculated MAD factor a consistent estimation of the standard deviation of the distribution. Default: 1.4826, which is the appropriate scaling factor for a normal distribution.

Type:float, optional
marginal_window

Time window over which to marginalise the coalescence, making it solely a function of the spatial dimensions. This should be an estimate of the time error, as derived from an estimate of the spatial error and error in the velocity model. 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
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
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 “dynamic” threshold, based on the Median Average Deviation. Default: “static”.

Type:str, 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
trigger(starttime, endtime, region=None, savefig=True)[source]

Trigger candidate earthquakes from decimated detect scan results.

Raises:
  • ValueError – If min_event_interval < 2 * marginal_window.
  • InvalidThresholdMethodException – If an invalid threshold method is passed in by the user.
  • TimeSpanException – If the user supplies a starttime that is after the endtime.
min_event_interval

Get and set the minimum event interval.

minimum_repeat

Handler for deprecated attribute name ‘minimum_repeat’.

trigger(starttime, endtime, region=None, savefig=True)[source]

Trigger candidate earthquakes from decimated scan data.

Parameters:
  • starttime (str) – Timestamp from which to trigger.
  • endtime (str) – Timestamp up to which to trigger.
  • region (list of floats, optional) –

    Only write triggered events within this region to the triggered events csv file (for use in locate.) Format is:

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

    Units are longitude / latitude / metres (in positive-down frame).

  • savefig (bool, optional) – Save triggered events figure (default) or open interactive view.
Raises:

TimeSpanException – If starttime is after endtime.
quakemigrate.signal.trigger.calculate_mad(x, scale=1.4826)[source]

Calculates the Median Absolute Deviation (MAD) of the input array x.

Parameters:
  • x (array-like) – Coalescence array in.
  • scale (float, optional) – A scaling factor for the MAD output to make the calculated MAD factor a consistent estimation of the standard deviation of the distribution.
Returns:

scaled_mad – Array of scaled mean absolute deviation values for the input array, x, scaled to provide an estimation of the standard deviation of the distribution.
Return type:

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

Create a trace filled with chunks of the same value.

a : array-like
Array of chunks.
new_shape : tuple of ints
(number of chunks, chunk_length)
b : array-like
Single array of values contained in a.