Core

Core programs for the EQcorrscan project.

bright_lights

Code to determine the birghtness function of seismic data according to a three-dimensional travel-time grid. This travel-time grid should be generated usingthe grid2time function of the NonLinLoc package by Anthony Lomax which can befound here: http://alomax.free.fr/nlloc/ and is not distributed within thispackage as this is a very useful stand-alone library for seismic event location.

This code is based on the method of Frank & Shapiro 2014

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

bright_lights._cum_net_resp(node_lis, instance=0)[source]

Function to compute the cumulative network response by reading the saved energy .npy files

Parameters:
  • node_lis (np.ndarray) – List of nodes (ints) to read from
  • instance (Int) – Instance flag for parallelisation, defaults to 0.
Returns:

np.ndarray cum_net_resp, list of indeces used
bright_lights._find_detections(cum_net_resp, nodes, threshold, thresh_type, samp_rate, realstations, length)[source]

Function to find detections within the cumulative network response according to Frank et al. (2014).

Parameters:
  • cum_net_resp (np.ndarray) – Array of cumulative network response for nodes
  • nodes (list of tuples) – Nodes associated with the source of energy in the cum_net_resp
  • threshold (float) – Threshold value
  • thresh_type (str) – Either MAD (Median Absolute Deviation) or abs (absolute) or RMS (Root Mean Squared)
  • samp_rate (float) – Sampling rate in Hz
  • realstations (list of str) – List of stations used to make the cumulative network response, will be reported in the DETECTION
  • length (float) – Maximum length of peak to look for in seconds
Returns:

detections as :class: DETECTION
bright_lights._node_loop(stations, lags, stream, i=0, mem_issue=False, instance=0, plot=False)[source]

Internal function to allow for parallelisation of brightness

Parameters:
  • stations (list) – List of stations to use
  • lags (np.ndarray) – List of lags where lags[i[:]] are the lags for stations[i]
  • stream – Data stream to find the brightness for
  • i (int) – Index of loop for parallelisation
  • mem_issue (bool) – If True will write to disk rather than storing data in RAM
  • instance (int) – instance for bulk parallelisation, only used if mem_issue=true
  • plot (bool) – Turn plotting on or off, defaults to False
Returns:

(i, energy (np.ndarray))
bright_lights._read_tt(path, stations, phase, phaseout='S', ps_ratio=1.68, lags_switch=True)[source]

Function to read in .csv files of slowness generated from Grid2Time (part of NonLinLoc by Anthony Lomax) and convert this to a useful format here.

It should be noted that this can read either P or S travel-time grids, not both at the moment.

Parameters:
  • path (str) – The path to the .csv Grid2Time outputs
  • stations (list) – List of station names to read slowness files for.
  • phaseout (str) – What phase to return the lagtimes in
  • ps_ratio (float) – p to s ratio for coversion
  • lags_switch (Bool) – Return lags or raw travel-times, if set to true will return lags.
Returns:

list stations, list of lists of tuples nodes, :class: ‘numpy.array’ lags station[1] refers to nodes[1] and lags[1] nodes[1][1] refers to station[1] and lags[1][1] nodes[n][n] is a tuple of latitude, longitude and depth
bright_lights._resample_grid(stations, nodes, lags, mindepth, maxdepth, corners, resolution)[source]

Function to resample the lagtime grid to a given volume. For use if the grid from Grid2Time is too large or you want to run a faster, downsampled scan.

Parameters:
  • stations (list) – List of station names from in the form where stations[i] refers to nodes[i][:] and lags[i][:]
  • nodes (list, tuple) – List of node points where nodes[i] referes to stations[i] and nodes[:][:][0] is latitude in degrees, nodes[:][:][1] is longitude in degrees, nodes[:][:][2] is depth in km.
  • lags – Array of arrays where lags[i][:] refers to stations[i]. lags[i][j] should be the delay to the nodes[i][j] for stations[i] in seconds :type mindepth: float
  • mindepth – Upper limit of volume
  • maxdepth (float) – Lower limit of volume
  • corners (matplotlib.Path) – matplotlib path of the corners for the 2D polygon to cut to in lat and long
Returns:

list stations, list of lists of tuples nodes, :class: ‘numpy.array’ lags station[1] refers to nodes[1] and lags[1] nodes[1][1] refers to station[1] and lags[1][1] nodes[n][n] is a tuple of latitude, longitude and depth.
bright_lights._rm_similarlags(stations, nodes, lags, threshold)[source]

Function to remove those nodes that have a very similar network moveout to another lag.

Will, for each node, calculate the difference in lagtime at each station at every node, then sum these for each node to get a cumulative difference in network moveout. This will result in an array of arrays with zeros on the diagonal.

Parameters:
  • stations (list) – List of station names from in the form where stations[i] refers to nodes[i][:] and lags[i][:]
  • nodes (list, tuple) – List of node points where nodes[i] referes to stations[i] and nodes[:][:][0] is latitude in degrees, nodes[:][:][1] is longitude in degrees, nodes[:][:][2] is depth in km.
  • lags – Array of arrays where lags[i][:] refers to stations[i]. lags[i][j] should be the delay to the nodes[i][j] for stations[i] in seconds
  • threshold – Threshold for removal in seconds
Returns:

list stations, list of lists of tuples nodes, :class: ‘numpy.array’ lags station[1] refers to nodes[1] and lags[1] nodes[1][1] refers to station[1] and lags[1][1] nodes[n][n] is a tuple of latitude, longitude and depth.
bright_lights.brightness(stations, nodes, lags, stream, threshold, thresh_type, coherence_thresh, instance=0, matchdef=False, defaults=False, pre_pick=0.2)[source]

Function to calculate the brightness function in terms of energy for a day of data over the entire network for a given grid of nodes.

Note data in stream must be all of the same length and have the same sampling rates.

Parameters:
  • stations (list) – List of station names from in the form where stations[i] refers to nodes[i][:] and lags[i][:]
  • nodes (list, tuple) – List of node points where nodes[i] referes to stations[i] and nodes[:][:][0] is latitude in degrees, nodes[:][:][1] is longitude in degrees, nodes[:][:][2] is depth in km.
  • lags – Array of arrays where lags[i][:] refers to stations[i]. lags[i][j] should be the delay to the nodes[i][j] for stations[i] in seconds.
  • data – Data through which to look for detections.
  • threshold (float) – Threshold value for detection of template within the brightness function
  • thresh_type (str) – Either MAD or abs where MAD is the Median Absolute Deviation and abs is an absoulte brightness.
  • coherence_thresh (tuple of floats) – Threshold for removing incoherant peaks in the network response, those below this will not be used as templates. Must be in the form of (a,b) where the coherence is given by: a-kchan/b where kchan is the number of channels used to compute the coherence
  • pre_pick (float) – Seconds before the detection time to include in template
Returns:

list of templates as :class: obspy.Stream objects
bright_lights.coherence(stream_in, stations=['all'], clip=False)[source]

Function to determine the average network coherence of a given template or detection. You will want your stream to contain only signal as noise will reduce the coherence (assuming it is incoherant random noise).

Parameters:
  • stream (obspy.Stream) – The stream of seismic data you want to calculate the coherence for.
  • stations (List of String) – List of stations to use for coherence, default is all
  • clip (Tuple of Float) – Default is to use all the data given - tuple of start and end in seconds from start of trace
Returns:

float - coherence, int number of channels used

template_gen

Function to generate template waveforms and information to go with them for theapplication of cross-correlation of seismic data for the detection of repeatingevents.

Part of the EQcorrscan module to read nordic format s-filesEQcorrscan 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/>.

template_gen._template_gen(picks, st, length, swin, prepick=0.05, plot=False)[source]

Function to generate a cut template in the obspy Stream class from a given set of picks and data, also in an obspy stream class. Should be given pre-processed data (downsampled and filtered)

Parameters:
  • picks – Picks to extract data around
  • st – Stream to etract templates from
  • length (float) – Length of template in seconds
  • swin (string) – P, S or all
  • prepick (float) – Length in seconds to extract before the pick time default is 0.05 seconds
  • plot (bool) – To plot the template or not, default is True
template_gen.from_contbase(sfile, lowcut=None, highcut=None, samp_rate=None, filt_order=None, length=None, prepick=None)[source]

Function to read in picks from sfile then generate the template from the picks within this and the wavefiles from the continous database of day-long files. Included is a section to sanity check that the files are daylong and that they start at the start of the day. You should ensure this is the case otherwise this may alter your data if your data are daylong but the headers are incorrectly set.

Parameters:
  • sfile (string) – sfilename must be the path to a seisan nordic type s-file containing waveform and pick information, all other arguments can be numbers save for swin which must be either P, S or all (case-sensitive).
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • lowcut – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • length (float) – Extract length in seconds, if None will look in template defaults file.
  • prepick (float) – Pre-pick time in seconds
template_gen.from_sfile(sfile, lowcut=None, highcut=None, samp_rate=None, filt_order=None, length=None)[source]

Function to read in picks from sfile then generate the template from the picks within this and the wavefile found in the pick file.

Parameters:
  • sfile (string) – sfilename must be the path to a seisan nordic type s-file containing waveform and pick information.
  • lowcut (float) – Low cut (Hz), if set to None will look in template defaults file
  • lowcut – High cut (Hz), if set to None will look in template defaults file
  • samp_rate (float) – New sampling rate in Hz, if set to None will look in template defaults file
  • filt_order (int) – Filter level, if set to None will look in template defaults file
  • length (float) – Extract length in seconds, if None will look in template defaults file.

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)[source]

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)[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
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, 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
match_filter.match_filter(template_names, templates, stream, threshold, threshold_type, trig_int, plotvar, tempdir=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:
  • 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.
  • stream – 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.
  • threshold (float) – A threshold value set based on the threshold_type :type threshold_type: str
  • threshold_type – 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.
  • tempdir (String or False) – Directory to put temporary files, or False
Returns:

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

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:

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.

lag_calc

Functions to generate lag-times for events detected by correlation.

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

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

The match-filter routine described here was used a previous Matlab code for the Chamberlain et al. 2014 G-cubed publication. The basis for the lag-time generation 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/>.

lag_calc._channel_loop(detection, template, i=0)[source]

Utility function to take a stream of data for the detected event and parse the correct data to lag_gen

Parameters:
  • detection (obspy.Stream) – Stream of data for the slave event detected using template
  • template (obspy.Stream) – Stream of data as the template for the detection.
  • i (int, optional) – Used to track which process has occured when running in parallel
Returns:

picks, a tuple of (lag in s, cross-correlation value, station, chan)
lag_calc.day_loop(detection_streams, template)[source]

Function to loop through multiple detections for one template - ostensibly designed to run for the same day of data for I/O simplicity, but as you are passing stream objects it could run for all the detections ever, as long as you have the RAM!

Parameters:
  • detection_streams (List of obspy.Stream) – List of all the detections for this template that you want to compute the optimum pick for.
  • template (obspy.Stream) – The original template used to detect the detections passed
Returns:

lags - List of List of tuple: lags[i] corresponds to detection[i], lags[i][j] corresponds to a channel of detection[i], within this tuple is the lag (in seconds), normalised correlation, station and channel.
lag_calc.lag_calc(detections, detect_data, templates, shift_len=0.2, min_cc=0.4)[source]

Overseer function to take a list of detection objects, cut the data for them to lengths of the same length of the template + shift_len on either side. This will then write out SEISAN s-file for the detections with pick times based on the lag-times found at the maximum correlation, providing that correlation is above the min_cc.

Parameters:
  • detections (List of DETECTION) – List of DETECTION objects
  • detect_data (obspy.Stream) – All the data needed to cut from - can be a gappy Stream
  • templates (List of tuple of String, obspy.Stream) – List of the templates used as tuples of template name, template
  • shift_len (float) – Shift length allowed for the pick in seconds, will be plus/minus this amount - default=0.2
  • min_cc (float) – Minimum cross-correlation value to be considered a pick, default=0.4