4.3. match_filter

Function to cross-correlate templates generated by template_gen function with data and output the detecitons. The central component of this is the match_template function from the openCV image processing package. This is a highly optimized and accurate normalized cross-correlation routine. The details of this code can be found here: http://www.cs.ubc.ca/research/deaton/remarks_ncc.html

The matched-filter routine described here was used a previous Matlab code for the Chamberlain et al. 2014 G-cubed publication.

copyright:Calum Chamberlain, Chet Hopp.
license:GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)
class match_filter.DETECTION(template_name, detect_time, no_chans, detect_val, threshold, typeofdet, chans=None, event=None)[source]

Bases: object

Information required for a full detection based on cross-channel correlation sums.

Attributes:
type template_name:
 

str

param template_name:
 

The name of the template for which this detection was made.

type detect_time:
 
class:‘obspy.UTCDateTime’
param detect_time:
 

Time of detection as an obspy UTCDateTime object

type no_chans:

int

param no_chans:

The number of channels for which the cross-channel correlation sum was calculated over.

type chans:

list of str

param chans:

List of stations for the detection

type cccsum_val:
 

float

param cccsum_val:
 

The raw value of the cross-channel correlation sum for this detection.

type threshold:

float

param threshold:
 

The value of the threshold used for this detection, will be the raw threshold value related to the cccsum.

type typeofdet:

str

param typeofdet:
 

Type of detection, STA, corr, bright

Todo

Use Obspy.core.event class instead of detection. Requires internal knowledge of template parameters - which needs changes to how templates are stored.

match_filter._channel_loop(templates, stream, cores=1, debug=0)[source]

Loop to generate cross channel correaltion sums for a series of templates hands off the actual correlations to a sister function which can be run in parallel.

Parameters:
  • templates – A list of templates, where each one should be an obspy.Stream object containing multiple traces of seismic data and the relevant header information.
  • stream – A single obspy.Stream object containing daylong seismic data to be correlated through using the templates. This is in effect the image.
  • core (int) – Number of cores to loop over
  • debug (int) – Debug level.
Returns:

New list of :class: ‘numpy.array’ objects. These will contain the correlation sums for each template for this day of data.

Returns:

list of ints as number of channels used for each cross-correlation.

Returns:

list of list of tuples of station, channel for all cross-correlations.

match_filter._template_loop(template, chan, station, channel, debug=0, i=0)[source]

Sister loop to handle the correlation of a single template (of multiple channels) with a single channel of data.

Parameters:i (int) – Optional argument, used to keep track of which process is being run.
Returns:tuple of (i, ccc) with ccc as an ndarray

Note

This function currently assumes only one template-channel per data-channel, while this is normal for a standard matched-filter routine, if we wanted to impliment a subspace detector, this would be the function to change, I think. E.g. where I currently take only the first matching channel, we could loop through all the matching channels and then sum the correlation sums - however I haven’t yet implimented detection based on that. More reading of the Harris document required.

match_filter.detections_to_catalog(detections)[source]

Helper to convert from list of detections to obspy catalog.

Parameters:detections (list) – list of eqcorrscan.core.match_filter.detection
Returns:obspy.core.event.Catalog
match_filter.extract_from_stream(stream, detections, pad=2.0, length=30.0)[source]

Extract a list of detections from a stream.

Parameters:
  • stream (osbpy.core.Stream) – Stream containing the detections.
  • detections (list) – list of eqcorrscan.core.match_filter.detection
  • pad (float) – Pre-detection extract time in seconds.
  • length (float) – Total extracted length in seconds.
Returns:

list of obspy.core.Stream

match_filter.match_filter(template_names, template_list, st, threshold, threshold_type, trig_int, plotvar, plotdir=u'.', cores=1, tempdir=False, debug=0, plot_format=u'jpg', output_cat=False, extract_detections=False)[source]

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.

Parameters:
  • template_names (list) – List of template names in the same order as template_list
  • template_list (list :class: 'obspy.Stream') – A list of templates of which each template is a Stream of obspy traces containing seismic data and header information.
  • st – An obspy.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. MAD threshold is calculated as the threshold*(median(abs(cccsum))) where cccsum is the cross-correlation sum for a given template. absolute threhsold 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*(cccsum/len(template)) where template is a single template from the input and the length is the number of channels within this template.
  • trig_int (float) – Minimum gap between detections in seconds.
  • plotvar (bool) – Turn plotting on or off
  • plotdir (str) – Path to plotting folder, plots will be output here, defaults to run location.
  • tempdir (String or False) – Directory to put temporary files, or False
  • cores (int) – Number of cores to use
  • debug (int) – Debug output level, the bigger the number, the more the output.
  • 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.
  • extract_detections (bool) – Specifies whether or not to return a list of streams, one stream per detection.
Returns:

class:‘DETECTIONS’ detections for each channel formatted as
class:‘obspy.UTCDateTime’ objects.

Returns:

class:obspy.Catalog containing events for each detection.

Returns:

list of :class: obspy.Stream objects for each detection.

Note

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

The output_cat flag will create an :class: obspy.Catalog containing one event for each :class: ‘DETECTIONS’ 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 :class: Pick which will contain time and waveform information. HOWEVER, the user should note that, at present, 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. We are looking towards a solution which will involve saving templates alongside associated metadata.

match_filter.normxcorr2(template, image)[source]

Base function to call the c++ correlation routine from the openCV image processing suite. Requires you to have installed the openCV python bindings, which can be downloaded on Linux machines using: sudo apt-get install python-openCV.

Here we use the cv2.TM_CCOEFF_NORMED method within openCV to give the normalized cross-correaltion. Documentation on this function can be found here:

http://docs.opencv.org/modules/imgproc/doc/object_detection.html?highlight=matchtemplate#cv2.matchTemplate

Parameters:
  • template – Template array
  • image – image to scan the template through. The order of these matters, if you put the template after the image you will get a reversed correaltion matrix
Returns:

New :class: ‘numpy.array’ object of the correlation values for the correlation of the image with the template.