correlation_detector(stream, templates, heights, distance, template_times=None, template_magnitudes=None, template_names=None, similarity_func=<function _calc_mean at 0x46bfedf4>, 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.

  • 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().

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)


>>> 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.