5.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.
5.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))
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: