3.1. bright_lights — EQcorrscan 0.1.0 documentation

# 3.1. bright_lights

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

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

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

Copyright 2015, 2016 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)

  Function to compute the cumulative network response by reading 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

  Note

  This is an internal function to ease parallel processing and should not be called directly.

`bright_lights.` `_find_detections`(cum_net_resp, nodes, threshold, thresh_type, samp_rate, realstations, length)

  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

  Note

  This is an internal function to ease parallel processing and should not be called directly.

`bright_lights.` `_node_loop`(stations, lags, stream, clip_level, i=0, mem_issue=False, instance=0, plot=False)

  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. clip_level (float) – Upper limit for energy as a multiplier to the mean energy. 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))

  Note

  This is an internal function to ease parallel processing and should not be called directly.

`bright_lights.` `_read_tt`(path, stations, phase, phaseout=u'S', ps_ratio=1.68, lags_switch=True)

  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, np.ndarray of 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.

  Note

  This function currently needs comma seperated grid files in NonLinLoc format. Only certain versions of NonLinLoc write these csv files, however it should be possible to read the binary files directly. If you find you need this capability let us know and we can try and impliment it.

`bright_lights.` `_resample_grid`(stations, nodes, lags, mindepth, maxdepth, corners, resolution)

  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 lonitude 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. mindepth (float) – 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.

  Note

  This is an internal function and should not be called directly.

`bright_lights.` `_rm_similarlags`(stations, nodes, lags, threshold)

  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.

  Note

  This is an internal function and should not be called directly.

`bright_lights.` `_rms`(array)

  Calculate RMS of array

  Note

  Just a lazy function using numpy functions.

`bright_lights.` `brightness`(stations, nodes, lags, stream, threshold, thresh_type, template_length, template_saveloc, coherence_thresh, coherence_stations=[u'all'], coherence_clip=False, gap=2.0, clip_level=100, instance=0, pre_pick=0.2, plotsave=True, cores=1)

  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. template_length (float) – Length of template to extract in seconds template_saveloc (str) – Path of where to save the templates. 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 coherence_stations (list) – List of stations to use in the coherance thresholding - defaults to ‘all’ which uses all the stations. coherence_clip (Start and end in seconds of data to window around, defaults to False, which uses all the data given.) – tuple pre_pick (float) – Seconds before the detection time to include in template plotsave (bool) – Save or show plots, if False will try and show the plots on screen - as this is designed for bulk use this is set to True to save any plots rather than show them if you create them - changes the backend of matplotlib, so if is set to False you will see NO PLOTS! core – Number of cores to use, defaults to 1. clip_level (float) – Multiplier applied to the mean deviation of the energy as an upper limit, used to remove spikes (earthquakes, lightning, electircal spikes) from the energy stack. gap (float) – Minimum inter-event time in seconds for detections
  Returns: | list of templates as :class: obspy.Stream objects

`bright_lights.` `coherence`(stream_in, stations=[u'all'], clip=False)

  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