obspy.signal.cross_correlation.correlation_detector

correlation_detector(stream, templates, heights, distance, template_times=None, template_magnitudes=None, template_names=None, similarity_func=<function _calc_mean>, details=None, plot=None, **kwargs)[source]

Detector based on the cross-correlation of waveforms.

This detector cross-correlates the stream with each of the template streams (compare with correlate_stream_template()). A similarity is defined, by default it is the mean of all cross-correlation functions for each template. If the similarity exceeds the height threshold a detection is triggered. This peak finding utilizes the SciPy function find_peaks() with parameters height and distance. For a SciPy version smaller than 1.1 it uses a custom function for peak finding.

Parameters:

  • stream – Stream with data traces.

  • templates – List of streams with template traces. Each template stream should be shorter than the data stream. This argument can also be a single template stream.

  • heights – Similarity values to trigger a detection, one for each template. This argument can also be a single value.

  • distance – The distance in seconds between two detections.

  • template_times – UTCDateTimes associated with template event (e.g. origin times, default are the start times of the template streams). This argument can also be a single value.

  • template_magnitudes – Magnitudes of the template events. If provided, amplitude ratios between templates and detections will be calculated and the magnitude of detections will be estimated. This argument can also be a single value. This argument can be set to True, then only amplitude ratios will be calculated.

  • template_names – List of template names, the corresponding template name will be inserted into the detection.

  • similarity_func – By default, the similarity will be calculated by the mean of cross-correlations. If provided, similarity_func will be called with the stream of cross correlations and the returned trace will be used as similarity. See the tutorial for an example.

  • details – If set to True detections include detailed information.

  • plot – Plot detections together with the data of the supplied stream. The default plot=None does not plot anything. plot=True plots the similarity traces together with the detections. If a stream is passed as argument, the traces in the stream will be plotted together with the similarity traces and detections.

  • kwargs – Suitable kwargs are passed to correlate_template() function. All other kwargs are passed to find_peaks().

Returns:

List of event detections sorted chronologically and list of similarity traces - one for each template. Each detection is a dictionary with the following keys: time, similarity, template_id, amplitude_ratio, magnitude (if template_magnitudes is provided), template_name (if template_names is provided), cross-correlation values, properties returned by find_peaks (if details are requested)

Example

>>> from obspy import read, UTCDateTime
>>> data = read().filter('highpass', freq=5)
>>> pick = UTCDateTime('2009-08-24T00:20:07.73')
>>> template = data.slice(pick, pick + 10)
>>> detections, sims = correlation_detector(data, template, 0.5, 10)
>>> print(detections)   
[{'time': UTCDateTime(2009, 8, 24, 0, 20, 7, 730000),
  'similarity': 0.99999999999999944,
  'template_id': 0}]

A more advanced tutorial is available.