match_filter — EQcorrscan 0.0.8 documentation

# match_filter

Function to cross-correlate templates generated by template_gen function withdata and output the detecitons. The main component of this script is thenormxcorr2 function from the openCV image processing package. This is a highlyoptimized and accurate normalized cross-correlation routine. The details ofthis code can be found here:* http://www.cs.ubc.ca/research/deaton/remarks_ncc.htmlThe cpp code was first tested using the Matlab mex wrapper, and has since beenported to a python callable dynamic library.

Part of the EQcorrscan module to integrate seisan nordic files into a fullcross-channel correlation for detection routine.EQcorrscan is a python module designed to run match filter routines forseismology, within it are routines for integration to seisan and obspy.With obspy integration (which is necessary) all main waveform formats can beread in and output.

This main section contains a script, LFE_search.py which demonstrates the usageof the built in functions from template generation from picked waveformsthrough detection by match filter of continuous data to the generation of lagtimes to be used for relative locations.

The match-filter routine described here was used a previous Matlab code for theChamberlain et al. 2014 G-cubed publication. The basis for the lag-timegeneration section is outlined in Hardebeck & Shelly 2011, GRL.

Code generated by Calum John Chamberlain of Victoria University of Wellington,2015.

Note

Pre-requisites:

  - gcc - for the installation of the openCV correlation routine

  - python-cv2 - Python bindings for the openCV routines

  - python-joblib - used for parallel processing

  - python-obspy - used for lots of common seismological processing
      - requires:
          - numpy
          - scipy
          - matplotlib

  - NonLinLoc - used outside of all codes for travel-time generation

Copyright 2015 Calum Chamberlain

This file is part of EQcorrscan.

> EQcorrscan is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

> EQcorrscan is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

> You should have received a copy of the GNU General Public License along with EQcorrscan. If not, see <http://www.gnu.org/licenses/>.

class `match_filter.` `DETECTION`(template_name, detect_time, no_chans, detect_val, threshold, typeofdet, chans=None)

  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

`match_filter.` `_channel_loop`(templates, stream, cores=1, debug=0)

  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

`match_filter.` `_template_loop`(template, chan, station, channel, debug=0, i=0)

  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

`match_filter.` `match_filter`(template_names, templates, st, threshold, threshold_type, trig_int, plotvar, plotdir='.', cores=1, tempdir=False, debug=0, plot_format='jpg')

  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: | templates (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 the stream you input 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
  Returns: |
  class: | ‘DETECTIONS’ detections for each channel formatted as :class: ‘obspy.UTCDateTime’ objects.

  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.

`match_filter.` `normxcorr2`(template, image)

  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.