4.6.3.1.4. match_filter.Template¶
See notes and warnings on correlations here: correlation_warnings
-
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]¶ Initialize self. See help(type(self)) for accurate signature.
-
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.
- method (str) – Method to make the template,
see
-
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, full_peaks=False)[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.
- full_peaks – See eqcorrscan.utils.findpeaks.find_peaks2_short
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: 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
-