4.6.3.1.4. match_filter.Template

class eqcorrscan.core.match_filter.Template(name=None, st=None, lowcut=None, highcut=None, samp_rate=None, filt_order=None, process_length=None, prepick=None, event=None)[source]

Bases: object

Template object holder. Contains waveform data and metadata parameters used to generate the template.

Methods

construct(method, name, lowcut, highcut, ...) Construct a template using a given method.
copy() Returns a copy of the template.
detect(stream, threshold, threshold_type, ...) Detect using a single template within a continuous stream.
read(filename) Read template from tar format with metadata.
same_processing(other) Check is the templates are processed the same.
write(filename[, format]) Write template.
__init__(name=None, st=None, lowcut=None, highcut=None, samp_rate=None, filt_order=None, process_length=None, prepick=None, event=None)[source]
construct(method, name, lowcut, highcut, samp_rate, filt_order, prepick, **kwargs)[source]

Construct a template using a given method.

Parameters:
  • method (str) Method to make the template, see eqcorrscan.core.template_gen for possible methods.
  • name (str) Name for the template
  • 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).
  • prepick (float) Pre-pick time in seconds

Note

methods from_meta_file, from_seishub, from_client and multi_template_gen are not accommodated in this function and must be called from Tribe.construct as these generate multiple templates.

Note

Calls functions from eqcorrscan.core.template_gen, see these functions for details on what further arguments are required.

Example

>>> sac_files = glob.glob(
...     'eqcorrscan/tests/test_data/SAC/2014p611252/*')
>>> template = Template().construct(
...     method='from_sac', name='test', lowcut=2.0, highcut=8.0,
...     samp_rate=20.0, filt_order=4, prepick=0.1, swin='all',
...     length=2.0, sac_files=sac_files)
>>> print(template) 
Template test:
 12 channels;
 lowcut: 2.0 Hz;
 highcut: 8.0 Hz;
 sampling rate 20.0 Hz;
 filter order: 4;
 process length: 300.0 s

This will raise an error if the method is unsupported:

>>> template = Template().construct(
...     method='from_meta_file', name='test', lowcut=2.0, highcut=8.0,
...     samp_rate=20.0, filt_order=4, prepick=0.1, swin='all',
...     length=2.0) 
Traceback (most recent call last):
NotImplementedError: Method is not supported, use         Tribe.construct instead.
copy()[source]

Returns a copy of the template.

Returns:Copy of template

Example

>>> template_a = Template(
...     name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,
...     filt_order=4, process_length=3600, prepick=0.5)
>>> template_b = template_a.copy()
>>> template_a == template_b
True
detect(stream, threshold, threshold_type, trig_int, plotvar, pre_processed=False, daylong=False, parallel_process=True, xcorr_func=None, concurrency=None, cores=None, ignore_length=False, overlap='calculate', debug=0)[source]

Detect using a single template within a continuous stream.

Parameters:
  • stream (obspy.core.stream.Stream) Continuous data to detect within using the Template.
  • threshold (float) Threshold level, if using threshold_type=’MAD’ then this will be the multiple of the median absolute deviation.
  • threshold_type (str) The type of threshold to be used, can be MAD, absolute or av_chan_corr. See Note on thresholding below.
  • trig_int (float) Minimum gap between detections in seconds. If multiple detections occur within trig_int of one-another, the one with the highest cross-correlation sum will be selected.
  • plotvar (bool) Turn plotting on or off, see warning about plotting below
  • pre_processed (bool) Set to True if stream has already undergone processing, in this case eqcorrscan will only check that the sampling rate is correct. Defaults to False, which will use the eqcorrscan.utils.pre_processing routines to resample and filter the continuous data.
  • daylong (bool) Set to True to use the eqcorrscan.utils.pre_processing.dayproc() routine, which preforms additional checks and is more efficient for day-long data over other methods.
  • parallel_process (bool)
  • xcorr_func (str or callable) A str of a registered xcorr function or a callable for implementing a custom xcorr function. For more details see eqcorrscan.utils.correlate.register_array_xcorr().
  • concurrency (str) The type of concurrency to apply to the xcorr function. Options are ‘multithread’, ‘multiprocess’, ‘concurrent’. For more details see eqcorrscan.utils.correlate.get_stream_xcorr().
  • cores (int) Number of workers for processing and detection.
  • ignore_length (bool) If using daylong=True, then dayproc will try check that the data are there for at least 80% of the day, if you don’t want this check (which will raise an error if too much data are missing) then set ignore_length=True. This is not recommended!
  • overlap (float) Either None, “calculate” or a float of number of seconds to overlap detection streams by. This is to counter the effects of the delay-and-stack in calcualting cross-correlation sums. Setting overlap = “calculate” will work out the appropriate overlap based on the maximum lags within templates.
  • debug (int) Debug level from 0-5 where five is more output, for debug levels 4 and 5, detections will not be computed in parallel.
Returns:

Family of detections.

Warning

Plotting within the match-filter routine uses the Agg backend with interactive plotting turned off. This is because the function is designed to work in bulk. If you wish to turn interactive plotting on you must import matplotlib in your script first, when you then import match_filter you will get the warning that this call to matplotlib has no effect, which will mean that match_filter has not changed the plotting behaviour.

Note

Data overlap:

Internally this routine shifts and trims the data according to the offsets in the template (e.g. if trace 2 starts 2 seconds after trace 1 in the template then the continuous data will be shifted by 2 seconds to align peak correlations prior to summing). Because of this, detections at the start and end of continuous data streams may be missed. The maximum time-period that might be missing detections is the maximum offset in the template.

To work around this, if you are conducting matched-filter detections through long-duration continuous data, we suggest using some overlap (a few seconds, on the order of the maximum offset in the templates) in the continous data. You will then need to post-process the detections (which should be done anyway to remove duplicates).

Note

Thresholding:

MAD threshold is calculated as the:

\[threshold {\times} (median(abs(cccsum)))\]

where \(cccsum\) is the cross-correlation sum for a given template.

absolute threshold is a true absolute threshold based on the cccsum value.

av_chan_corr is based on the mean values of single-channel cross-correlations assuming all data are present as required for the template, e.g:

\[av\_chan\_corr\_thresh=threshold \times (cccsum / len(template))\]

where \(template\) is a single template from the input and the length is the number of channels within this template.

Note

See tutorials for example.

read(filename)[source]

Read template from tar format with metadata.

Parameters:filename (str) Filename to read template from.

Example

>>> template_a = Template(
...     name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,
...     filt_order=4, process_length=3600, prepick=0.5)
>>> template_a.write(
...     'test_template_read') 
Template a:
 3 channels;
 lowcut: 2.0 Hz;
 highcut: 8.0 Hz;
 sampling rate 100 Hz;
 filter order: 4;
 process length: 3600 s
>>> template_b = Template().read('test_template_read.tgz')
>>> template_a == template_b
True
same_processing(other)[source]

Check is the templates are processed the same.

Example

>>> template_a = Template(
...     name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,
...     filt_order=4, process_length=3600, prepick=0.5)
>>> template_b = template_a.copy()
>>> template_a.same_processing(template_b)
True
>>> template_b.lowcut = 5.0
>>> template_a.same_processing(template_b)
False
write(filename, format='tar')[source]

Write template.

Parameters:
  • filename (str) Filename to write to, if it already exists it will be opened and appended to, otherwise it will be created.
  • format (str) Format to write to, either ‘tar’ (to retain metadata), or any obspy supported waveform format to just extract the waveform.

Example

>>> template_a = Template(
...     name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,
...     filt_order=4, process_length=3600, prepick=0.5)
>>> template_a.write('test_template') 
Template a:
 3 channels;
 lowcut: 2.0 Hz;
 highcut: 8.0 Hz;
 sampling rate 100 Hz;
 filter order: 4;
 process length: 3600 s
>>> template_a.write('test_waveform.ms',
...                  format='MSEED') 
Template a:
 3 channels;
 lowcut: 2.0 Hz;
 highcut: 8.0 Hz;
 sampling rate 100 Hz;
 filter order: 4;
 process length: 3600 s