6.1.2.2.1.1.1. eqcorrscan.core.match_filter.matched_filter.match_filter

eqcorrscan.core.match_filter.matched_filter.match_filter(template_names, template_list, st, threshold, threshold_type, trig_int, plot=False, plotdir=None, xcorr_func=None, concurrency=None, cores=None, plot_format='png', output_cat=False, extract_detections=False, arg_check=True, full_peaks=False, peak_cores=None, export_cccsums=False, **kwargs)[source]

Main matched-filter detection function.

Over-arching code to run the correlations of given templates with a day of seismic data and output the detections based on a given threshold. For a functional example see the tutorials.

Parameters:

  • template_names (list) – List of template names in the same order as template_list

  • template_list (list) – A list of templates of which each template is a obspy.core.stream.Stream of obspy traces containing seismic data and header information.

  • st (obspy.core.stream.Stream) – A Stream object containing all the data available and required for the correlations with templates given. For efficiency this should contain no excess traces which are not in one or more of the templates. This will now remove excess traces internally, but will copy the stream and work on the copy, leaving your input stream untouched.

  • threshold (float) – A threshold value set based on the threshold_type

  • 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 from one template in seconds. If multiple detections occur within trig_int of one-another, the one with the highest cross-correlation sum will be selected.

  • plot (bool) – Turn plotting on or off

  • plotdir (str) – Path to plotting folder, plots will be output here, defaults to None, and plots are shown on screen.

  • xcorr_func (str or callable) – A str of a registered xcorr function or a callable for implementing a custom xcorr function. For more information 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 cores to use

  • plot_format (str) – Specify format of output plots if saved

  • output_cat (bool) – Specifies if matched_filter will output an obspy.Catalog class containing events for each detection. Default is False, in which case matched_filter will output a list of detection classes, as normal.

  • output_event (bool) – Whether to include events in the Detection objects, defaults to True, but for large cases you may want to turn this off as Event objects can be quite memory intensive.

  • extract_detections (bool) – Specifies whether or not to return a list of streams, one stream per detection.

  • arg_check (bool) – Check arguments, defaults to True, but if running in bulk, and you are certain of your arguments, then set to False.

  • full_peaks (bool) – See :func: eqcorrscan.utils.findpeaks.find_peaks_compiled

  • peak_cores (int) – Number of processes to use for parallel peak-finding (if different to cores).

  • spike_test (bool) – If set True, raise error when there is a spike in data. defaults to True.

  • copy_data (bool) – Whether to copy data to keep it safe, otherwise will edit your templates and stream in place.

  • export_cccsums (bool) – Whether to save the cross-correlation statistic.

Note

When using the “fftw” correlation backend the length of the fft can be set. See eqcorrscan.utils.correlate for more info.

Note

Returns:

If neither output_cat or extract_detections are set to True, then only the list of eqcorrscan.core.match_filter.Detection’s will be output:

return:

eqcorrscan.core.match_filter.Detection detections for each detection made.

rtype:

list

If output_cat is set to True, then the obspy.core.event.Catalog will also be output:

return:

Catalog containing events for each detection, see above.

rtype:

obspy.core.event.Catalog

If extract_detections is set to True then the list of obspy.core.stream.Stream’s will also be output.

return:

list of obspy.core.stream.Stream’s for each detection, see above.

rtype:

list

Note

If your data contain gaps these must be padded with zeros before using this function. The eqcorrscan.utils.pre_processing functions will provide gap-filled data in the appropriate format. Note that if you pad your data with zeros before filtering or resampling the gaps will not be all zeros after filtering. This will result in the calculation of spurious correlations in the gaps.

Note

Detections are not corrected for pre-pick, the detection.detect_time corresponds to the beginning of the earliest template channel at detection.

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

The output_cat flag will create an obspy.core.event.Catalog containing one event for each eqcorrscan.core.match_filter.Detection’s generated by match_filter. Each event will contain a number of comments dealing with correlation values and channels used for the detection. Each channel used for the detection will have a corresponding obspy.core.event.Pick which will contain time and waveform information. HOWEVER, the user should note that the pick times do not account for the prepick times inherent in each template. For example, if a template trace starts 0.1 seconds before the actual arrival of that phase, then the pick time generated by match_filter for that phase will be 0.1 seconds early.