6.1.4. template_gen

Functions to generate template waveforms and information to go with them for the application of cross-correlation of seismic data for the detection of repeating events.

Note

All functions use obspy filters, which are implemented such that if both highcut and lowcut are set a bandpass filter will be used, but of highcut is not set (None) then a highpass filter will be used and if only the highcut is set then a lowpass filter will be used.

copyright:

EQcorrscan developers.

license:

GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

Routines for cutting waveforms around picks for use as templates for matched filtering.

6.1.4.1. Functions

eqcorrscan.core.template_gen.template_gen(method, lowcut, highcut, samp_rate, filt_order, length, prepick, swin='all', process_len=86400, all_vert=False, all_horiz=False, delayed=True, plot=False, plotdir=None, return_event=False, min_snr=None, parallel=False, num_cores=False, save_progress=False, skip_short_chans=False, vertical_chans=['Z'], horizontal_chans=['E', 'N', '1', '2'], **kwargs)[source]

Generate processed and cut waveforms for use as templates.

Parameters:
  • method (str) – Template generation method, must be one of (‘from_client’, ‘from_sac’, ‘from_meta_file’). - Each method requires associated arguments, see note below.

  • lowcut (float) – Low cut (Hz), if set to None will not apply a lowcut.

  • highcut (float) – High cut (Hz), if set to None will not apply a highcut.

  • samp_rate (float) – New sampling rate in Hz.

  • filt_order (int) – Filter level (number of corners).

  • length (float) – Length of template waveform in seconds.

  • prepick (float) – Pre-pick time in seconds

  • swin (str) – P, S, P_all, S_all or all, defaults to all: see note in eqcorrscan.core.template_gen.template_gen()

  • process_len (int) – Length of data in seconds to download and process.

  • all_vert (bool) – To use all channels defined in vertical_chans for P-arrivals even if there is only a pick on one of them. Defaults to False.

  • all_horiz (bool) – To use both horizontal channels even if there is only a pick on one of them. Defaults to False.

  • delayed (bool) – If True, each channel will begin relative to it’s own pick-time, if set to False, each channel will begin at the same time.

  • plot (bool) – Plot templates or not.

  • plotdir (str) – The path to save plots to. If plotdir=None (default) then the figure will be shown on screen.

  • return_event (bool) – Whether to return the event and process length or not.

  • min_snr (float) – Minimum signal-to-noise ratio for a channel to be included in the template, where signal-to-noise ratio is calculated as the ratio of the maximum amplitude in the template window to the rms amplitude in the whole window given.

  • parallel (bool) – Whether to process data in parallel or not.

  • num_cores (int) – Number of cores to try and use, if False and parallel=True, will use either all your cores, or as many traces as in the data (whichever is smaller).

  • save_progress (bool) – Whether to save the resulting templates at every data step or not. Useful for long-running processes.

  • skip_short_chans (bool) – Whether to ignore channels that have insufficient length data or not. Useful when the quality of data is not known, e.g. when downloading old, possibly triggered data from a datacentre

  • vertical_chans (list) – List of channel endings on which P-picks are accepted.

  • horizontal_chans (list) – List of channel endings for horizontal channels, on which S-picks are accepted.

Returns:

List of obspy.core.stream.Stream Templates

Return type:

list

Note

By convention templates are generated with P-phases on the vertical channel [can be multiple, e.g., Z (vertical) and H (hydrophone) for an ocean bottom seismometer] and S-phases on the horizontal channels. By default, normal seismograph naming conventions are assumed, where Z denotes vertical and N, E, 1 and 2 denote horizontal channels, either oriented or not. To this end we will only use vertical channels if they have a P-pick, and will use one or other horizontal channels only if there is an S-pick on it.

Warning

If there is no phase_hint included in picks, and swin=all, all channels with picks will be used.

Note

If swin=all, then all picks will be used, not just phase-picks (e.g. it will use amplitude picks). If you do not want this then we suggest that you remove any picks you do not want to use in your templates before using the event.

Note

Method specific arguments:

  • from_client requires:
    param str client_id:

    string passable by obspy to generate Client, or any object with a get_waveforms method, including a Client instance.

    param obspy.core.event.Catalog catalog:

    Catalog of events to generate template for

    param float data_pad:

    Pad length for data-downloads in seconds

  • from_sac requires:
    param list sac_files:

    osbpy.core.stream.Stream of sac waveforms, or list of paths to sac waveforms.

    Note

    See eqcorrscan.utils.sac_util.sactoevent for details on how pick information is collected.

  • from_meta_file requires:
    param str meta_file:

    Path to obspy-readable event file, or an obspy Catalog

    param obspy.core.stream.Stream st:

    Stream containing waveform data for template. Note that this should be the same length of stream as you will use for the continuous detection, e.g. if you detect in day-long files, give this a day-long file!

    param bool process:

    Whether to process the data or not, defaults to True.

Note

process_len should be set to the same length as used when computing detections using match_filter.match_filter, e.g. if you read in day-long data for match_filter, process_len should be 86400.

Example

>>> from obspy.clients.fdsn import Client
>>> from eqcorrscan.core.template_gen import template_gen
>>> client = Client('NCEDC')
>>> catalog = client.get_events(eventid='72572665', includearrivals=True)
>>> # We are only taking two picks for this example to speed up the
>>> # example, note that you don't have to!
>>> catalog[0].picks = catalog[0].picks[0:2]
>>> templates = template_gen(
...    method='from_client', catalog=catalog, client_id='NCEDC',
...    lowcut=2.0, highcut=9.0, samp_rate=20.0, filt_order=4, length=3.0,
...    prepick=0.15, swin='all', process_len=300, all_horiz=True)
>>> templates[0].plot(equal_scale=False, size=(800,600)) 
../plots/template_gen.from_client.png

Example

>>> from obspy import read
>>> from eqcorrscan.core.template_gen import template_gen
>>> # Get the path to the test data
>>> import eqcorrscan
>>> import os
>>> TEST_PATH = os.path.dirname(eqcorrscan.__file__) + '/tests/test_data'
>>> st = read(TEST_PATH + '/WAV/TEST_/' +
...           '2013-09-01-0410-35.DFDPC_024_00')
>>> quakeml = TEST_PATH + '/20130901T041115.xml'
>>> templates = template_gen(
...    method='from_meta_file', meta_file=quakeml, st=st, lowcut=2.0,
...    highcut=9.0, samp_rate=20.0, filt_order=3, length=2, prepick=0.1,
...    swin='S', all_horiz=True)
>>> print(len(templates[0]))
10
>>> templates = template_gen(
...    method='from_meta_file', meta_file=quakeml, st=st, lowcut=2.0,
...    highcut=9.0, samp_rate=20.0, filt_order=3, length=2, prepick=0.1,
...    swin='S_all', all_horiz=True)
>>> print(len(templates[0]))
15

Example

>>> from eqcorrscan.core.template_gen import template_gen
>>> import glob
>>> # Get all the SAC-files associated with one event.
>>> sac_files = glob.glob(TEST_PATH + '/SAC/2014p611252/*')
>>> templates = template_gen(
...    method='from_sac', sac_files=sac_files, lowcut=2.0, highcut=10.0,
...    samp_rate=25.0, filt_order=4, length=2.0, swin='all', prepick=0.1,
...    all_horiz=True)
>>> print(templates[0][0].stats.sampling_rate)
25.0
>>> print(len(templates[0]))
15
eqcorrscan.core.template_gen.extract_from_stack(stack, template, length, pre_pick, pre_pad, Z_include=False, pre_processed=True, samp_rate=None, lowcut=None, highcut=None, filt_order=3)[source]

Extract a multiplexed template from a stack of detections.

Function to extract a new template from a stack of previous detections. Requires the stack, the template used to make the detections for the stack, and we need to know if the stack has been pre-processed.

Parameters:
  • stack (obspy.core.stream.Stream) – Waveform stack from detections. Can be of any length and can have delays already included, or not.

  • template (obspy.core.stream.Stream) – Template used to make the detections in the stack. Will use the delays of this for the new template.

  • length (float) – Length of new template in seconds

  • pre_pick (float) – Extract additional data before the detection, seconds

  • pre_pad (float) – Pad used in seconds when extracting the data, e.g. the time before the detection extracted. If using clustering.extract_detections this half the length of the extracted waveform.

  • Z_include (bool) – If True will include any Z-channels even if there is no template for this channel, as long as there is a template for this station at a different channel. If this is False and Z channels are included in the template Z channels will be included in the new_template anyway.

  • pre_processed (bool) – Have the data been pre-processed, if True (default) then we will only cut the data here.

  • samp_rate (float) – If pre_processed=False then this is required, desired sampling rate in Hz, defaults to False.

  • lowcut (float) – If pre_processed=False then this is required, lowcut in Hz, defaults to False.

  • highcut (float) – If pre_processed=False then this is required, highcut in Hz, defaults to False

  • filt_order (int) – If pre_processed=False then this is required, filter order, defaults to False

Returns:

Newly cut template.

Return type:

obspy.core.stream.Stream