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.1.1. quakemigrate.signal.onsets
- 3.6.1.1.1. quakemigrate.signal.onsets.base
- 3.6.1.1.2. quakemigrate.signal.onsets.stalta
CentredSTALTAOnset
ClassicSTALTAOnset
STALTAOnset
STALTAOnset.phases
STALTAOnset.bandpass_filters
STALTAOnset.channel_maps
STALTAOnset.channel_counts
STALTAOnset.sta_lta_windows
STALTAOnset.all_channels
STALTAOnset.allow_gaps
STALTAOnset.full_timespan
STALTAOnset.position
STALTAOnset.sampling_rate
STALTAOnset.calculate_onsets()
STALTAOnset.gaussian_halfwidth()
STALTAOnset.calculate_onsets()
STALTAOnset.gaussian_halfwidth()
STALTAOnset.onset_centred
STALTAOnset.p_bp_filter
STALTAOnset.p_onset_win
STALTAOnset.post_pad
STALTAOnset.pre_pad
STALTAOnset.s_bp_filter
STALTAOnset.s_onset_win
pre_process()
sta_lta_centred()
- 3.6.1.2. quakemigrate.signal.pickers
- 3.6.1.2.1. quakemigrate.signal.pickers.base
- 3.6.1.2.2. quakemigrate.signal.pickers.gaussian
GaussianPicker
GaussianPicker.phase_picks
GaussianPicker.threshold_method
GaussianPicker.percentile_pick_threshold
GaussianPicker.mad_pick_threshold
GaussianPicker.plot_picks
GaussianPicker.pick_phases()
GaussianPicker.DEFAULT_GAUSSIAN_FIT
GaussianPicker.fraction_tt
GaussianPicker.pick_phases()
GaussianPicker.pick_threshold
GaussianPicker.plot()
- 3.6.1.3. quakemigrate.signal.local_mag
- 3.6.1.3.1. quakemigrate.signal.local_mag.local_mag
- 3.6.1.3.2. quakemigrate.signal.local_mag.amplitude
Amplitude
Amplitude.signal_window
Amplitude.noise_window
Amplitude.noise_measure
Amplitude.loc_method
Amplitude.highpass_filter
Amplitude.highpass_freq
Amplitude.bandpass_filter
Amplitude.bandpass_lowcut
Amplitude.bandpass_highcut
Amplitude.filter_corners
Amplitude.prominence_multiplier
Amplitude.get_amplitudes()
Amplitude.get_amplitudes()
Amplitude.pad()
- 3.6.1.3.3. quakemigrate.signal.local_mag.magnitude
Magnitude
Magnitude.A0
Magnitude.use_hyp_dist
Magnitude.amp_feature
Magnitude.station_corrections
Magnitude.amp_multiplier
Magnitude.weighted_mean
Magnitude.trace_filter
Magnitude.noise_filter
Magnitude.station_filter
Magnitude.dist_filter
Magnitude.pick_filter
Magnitude.r2_only_used
Magnitude.calculate_magnitudes()
Magnitude.mean_magnitude()
Magnitude.plot_amplitudes()
Magnitude.calculate_magnitudes()
Magnitude.mean_magnitude()
Magnitude.plot_amplitudes()
3.6.2. quakemigrate.signal.scan
Module to perform core QuakeMigrate functions: detect() and locate().
- copyright
2020–2023, 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
- real_waveform_units
Units to output real cut waveforms.
- Type
{“displacement”, “velocity”}
- 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_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: the last sample returned will be that which immediately precedes this timestamp.
- 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.
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–2023, 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 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
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
- 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
- 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
- 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
- trigger(starttime, endtime, region=None, interactive_plot=False)[source]
Trigger candidate earthquakes from decimated detect scan results.
- Raises
ValueError – If min_event_interval < 2 * marginal_window.
InvalidTriggerThresholdMethodException – If an invalid threshold method is passed in by the user.
TimeSpanException – If the user supplies a starttime that is after the endtime.
- property min_event_interval
Get and set the minimum event interval.
- property minimum_repeat
Handler for deprecated attribute name ‘minimum_repeat’.
- 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.