4.2. 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 of these functions work for a single template, however all of them call _template_gen, which takes care of pick association and cutting. If you have many templates in one day of data it would be simple to write a wrapper that cuts multiple templates from one day of processed data rather than re-processing the same day of data for each template.

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:Calum Chamberlain, Chet Hopp.
license:GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)
template_gen._template_gen(picks, st, length, swin=u'all', prepick=0.05, plot=False, debug=0)[source]

Function to generate a cut template in the obspy Stream class from a given set of picks and data, also in an obspy stream class. Should be given pre-processed data (downsampled and filtered).

Parameters:
  • picks (List of obspy.core.event.Pick) – Picks to extract data around
  • st – Stream to etract templates from
  • length (float) – Length of template in seconds
  • swin (string) – P, S or all, defaults to all
  • prepick (float) – Length in seconds to extract before the pick time default is 0.05 seconds
  • plot (bool) – To plot the template or not, default is True
  • debug (int) – Debug output level from 0-5.
Returns:

obspy.Stream Newly cut template.

Note

By convention templates are generated with P-phases on the vertical channel and S-phases on the horizontal channels, normal seismograph naming conventions are assumed, where Z denotes vertical and N, E, R, T, 1 and 2 denote horizontal channels, either oriented or not. To this end we will only use Z 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.

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]

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 (:class:obspy.Stream) – Waveform stack from detections. Can be of any length and can have delays already included, or not.
  • template (:class:obspy.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:

obspy.Stream Newly cut template

template_gen.from_client(catalog, client_id, lowcut, highcut, samp_rate, filt_order, length, prepick, swin, debug=0, plot=False)[source]

Function to generate templates from a SeisHub database.Must be given an obspy.Catalog class and the SeisHub url as input. The function returns a list of obspy.Stream classes containting steams for each desired template.

Parameters:
  • catalog (obspy.Catalog) – Catalog class containing desired template events
  • url (string) – url of SeisHub database instance
  • lowcut (float) – Low cut (Hz), if set to None will look in templatedefaults file
  • lowcut – High cut (Hz), if set to None will look in templatedefaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look intemplate defaults file
  • filt_order (int) – Filter level, if set to None will look intemplate defaults file
  • length (float) – Extract length in seconds, if None will look in templatedefaults file.
  • prepick (float) – Pre-pick time in seconds
  • swin (str) – Either ‘all’, ‘P’ or ‘S’, to select which phases to output.
  • debug (int) – Level of debugging output, higher=more
  • plot (bool) – Plot templates or not.
Returns:

obspy.Stream Newly cut template

template_gen.from_contbase(sfile, contbase_list, lowcut, highcut, samp_rate, filt_order, length, prepick, swin, debug=0, plot=False)[source]

Function to read in picks from sfile then generate the template from the picks within this and the wavefiles from the continous database of day-long files. Included is a section to sanity check that the files are daylong and that they start at the start of the day. You should ensure this is the case otherwise this may alter your data if your data are daylong but the headers are incorrectly set.

Parameters:
  • sfile (string) – sfilename must be the path to a seisan nordic type s-file containing waveform and pick information, all other arguments can be numbers save for swin which must be either P, S or all (case-sensitive).
  • contbase_list (List of tuple of string) – List of tuples of the form [‘path’, ‘type’, ‘network’]. Where path is the path to the continuous database, type is the directory structure, which can be either Yyyyy/Rjjj.01, which is the standard IRIS Year, julian day structure, or, yyyymmdd which is a single directory for every day.
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • lowcut – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • length (float) – Extract length in seconds, if None will look in template defaults file.
  • prepick (float) – Pre-pick time in seconds
  • swin (str) – Either ‘all’, ‘P’ or ‘S’, to select which phases to output.
  • debug (int) – Level of debugging output, higher=more
  • plot (bool) – Turns template plotting on or off.
Returns:

obspy.Stream Newly cut template

template_gen.from_quakeml(quakeml, st, lowcut, highcut, samp_rate, filt_order, length, prepick, swin, debug=0, plot=False)[source]

Function to generate a template from a local quakeml file and an obspy.Stream object.

Parameters:
  • quakeml (string) – QuakeML file containing pick information, can contain multiple events.
  • st (class: obspy.Stream) – Stream containing waveform data for template (hopefully). 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!
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • lowcut – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • length (float) – Extract length in seconds, if None will look in template defaults file.
  • prepick (float) – Pre-pick time in seconds
  • swin (str) – Either ‘all’, ‘P’ or ‘S’, to select which phases to output.
  • debug (int) – Level of debugging output, higher=more
  • plot (bool) – Display template plots or not
Returns:

list of obspy.Stream Newly cut templates

Warning

We suggest giving this function a full day of data, to ensure templates are generated with exactly the same processing as the continuous data. Not doing this will result in slightly reduced cross-correlation values.

template_gen.from_sac(sac_files, lowcut, highcut, samp_rate, filt_order, length, swin, prepick=0.05, debug=0, plot=False)[source]

Function to read picks and waveforms from SAC data, and generate a template from these. Usually sac_files is a list of all single-channel SAC files for a given event, a single, multi-channel template will be created from these traces.

Parameters:
  • sac_files (list or stream) – List or stream of sac waveforms, or list of paths to sac waveforms.
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • highcut (float) – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • swin (str) – Either ‘all’, ‘P’ or ‘S’, to select which phases to output.
  • length (float) – Extract length in seconds, if None will look in template defaults file.
  • prepick (float) – Length to extract prior to the pick in seconds.
  • debug (int) – Debug level, higher number=more output.
  • plot (bool) – Turns template plotting on or off.
Returns:

obspy.Stream Newly cut template

Note

This functionality is not supported for obspy versions below 1.0.0 as references times are not read in by SACIO, which are needed for defining pick times.

template_gen.from_seishub(catalog, url, lowcut, highcut, samp_rate, filt_order, length, prepick, swin, debug=0, plot=False)[source]

Function to generate templates from a SeisHub database.Must be given an obspy.Catalog class and the SeisHub url as input. The function returns a list of obspy.Stream classes containting steams for each desired template.

Parameters:
  • catalog (obspy.Catalog) – Catalog class containing desired template events
  • url (string) – url of SeisHub database instance
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • lowcut – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • length (float) – Extract length in seconds, if None will look in template defaults file.
  • prepick (float) – Pre-pick time in seconds
  • swin (str) – Either ‘all’, ‘P’ or ‘S’, to select which phases to output.
  • debug (int) – Level of debugging output, higher=more
  • plot (bool) – Plot templates or not.
Returns:

obspy.Stream Newly cut template

template_gen.from_sfile(sfile, lowcut, highcut, samp_rate, filt_order, length, swin, prepick=0.05, debug=0, plot=False)[source]

Function to read in picks from sfile then generate the template from the picks within this and the wavefile found in the pick file.

Parameters:
  • sfile (string) – sfilename must be the path to a seisan nordic type s-file containing waveform and pick information.
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • highcut (float) – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • swin (str) – Either ‘all’, ‘P’ or ‘S’, to select which phases to output.
  • length (float) – Extract length in seconds, if None will look in template defaults file.
  • prepick (float) – Length to extract prior to the pick in seconds.
  • debug (int) – Debug level, higher number=more output.
  • plot (bool) – Turns template plotting on or off.
Returns:

obspy.Stream Newly cut template

Warning

This will use whatever data is pointed to in the s-file, if this is not the coninuous data, we recommend using other functions. Differences in processing between short files and day-long files (inherent to resampling) will produce lower cross-correlations.

template_gen.multi_template_gen(catalog, st, length, swin=u'all', prepick=0.05, plot=False, debug=0)[source]

Thin wrapper around _template_gen to generate multiple templates from one stream of continuous data.

Parameters:
  • catalog
  • st
  • length (float) – Length of template in seconds
  • swin (string) – P, S or all, defaults to all
  • prepick (float) – Length in seconds to extract before the pick time default is 0.05 seconds
  • plot (bool) – To plot the template or not, default is True
  • debug (int) – Debug output level from 0-5.
Returns:

list of :class: obspy.core.Stream newly cut templates

Note

By convention templates are generated with P-phases on the vertical channel and S-phases on the horizontal channels, normal seismograph naming conventions are assumed, where Z denotes vertical and N, E, R, T, 1 and 2 denote horizontal channels, either oriented or not. To this end we will only use Z 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.