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

Parameters:

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)

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.