6. XCOR object

class enveloc.core.XCOR(st, model=None, grid_size=None, detrend=True, regrid=False, phase_types=['s', 'S'], normType=1, plot=True, interact=True, output=1, minimize_type='correlation', Cmin=0.5, Cmax=0.995, sta_min=3, dx_min=0.1, dt=3.0, bootstrap=1, bootstrap_prct=0.04, lookup_type='cubic', rotation=None, dTmax_s=None, rd_freq=None, raw_traces=[], env_hp=[], edge_control=0.03, num_processors=1, tt_file=None, waveform_loc=False, model_dir=None, gap_value=-123454321)

Bases: object

XCOR is the main class object that needs to be set up in order to get a location. Most of the paramaters will self-assign, and in many cases that is fine. The only essential variable is the obspy stream st, but you will likely want to give thought and care to the grid and velocity model.

Parameters:

• st (stream, required) – Obspy stream of envelopes. Each trace must have stats.coordinates.latitude/longitude

• model (str, optional) – Obspy taup model or model file from which to calculate travel times. If this is not provided, a default file will be called.

• model_dir (str, optional) – Directory where model.npz file is place by obspy’s taup program If not provided, it will default to within the enveloc module directory

• grid_size (dict, optional) – A dict with keys lats, lons, and deps each of which are 1D monotonic numpy arrays. If unprovided, this will be created internally based on the extent of the input stations.

• detrend (bool, optional) – True/False to force a demean on obspy stream st or not. Default = True

• regrid (bool, optional) – Whether to reinterpolate location on finer grid. Default = True

• phase_types (list, optional) – list of phases for which to calculate travel times. Ultimate travel time used for each grid node for each station will be the minimum calculated from the phases in the list provided. Also accepts [‘Nkmps’] where N is a constant velocity in km/s. This would be useful for inputing a surface wave velocity, for example. See obspy taup documentation for more details on phase nomenclature. Default = [ ‘s’, ‘S’ ]

• minimize_type (str, optional) – ‘correlation’ to minimize the difference between the observed Cmax and predicted C ‘time’ to minimize the difference between the observed and predicted dt Default = ‘correlation

• normType (int, optional) – Integer 1 or 2 to use an L1 or L2 norm. Default = 1

• plot (bool, optional) – Boolean flag to plot or not. Default = True

• interact (bool, optional) – Boolean flag to interact with plot or not. Default = True

• output (int, optional) – Interger from 0-3 controlling increasing level of messages the code produces Default = 1

• Cmin (float, optional) – Minimum normalized cross-correlation coefficient to be considered. Default = 0.5

• Cmax (float, optional) – Maximum normalized cross-correlation coefficient to be considered. Not always necessary, but could be for removing correlated noise spikes, for example. Default = 0.995

• sta_min (int, optional) – Minimum number of stations needed to obtain a location. Default = 3

• dx_min (float, optional) – Minimum horizontal distance (km) between channels required to consider th cross-correlation. Useful to exclude correlations between multiple channels at the same station. Default = 0.1

• bootstrap (int, optional) – Number of iterations for each location. For each iteration, bootstrap_prct of the CC values will be zeroed out, and the resulting station contributions are adjusted accordingly to obtain a new location. These iterated locations provide a measure of location scatter, which is recorded in the location object. The final location will use all of the data (no CC values zeroed out). Thus, if boootstrap=N, it will bootstrap N times and get a location using all the data on the N+1 iteration. If bootstrap==1, the data are only located once with all the data, and no horizontal scatter is estimated. Default = 1

• bootstrap_prct (float, optional) – Value between 0 and 1 determining the fraction of cc data to throw out in each bootstrap iteration. Default = 0.04 (4%)

• lookup_type (str, optional) – Type of interpolation method to use when getting a predicted cross-correlation value for each channel pair for each grid (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’). See scipy.interpolate.interp1d for details. Default=’cubic’

• rotation (dict, optinal) – Dictionary defining desired rotated grid. Needs keys x (x grid nodes), y (y grid nodes), z (depth grid nodes), lat0 & lon0 (origin lat/lon), az, rotation azimuth (counterclockwise from East) Default = None

• dTmax_s (float, optional) –

  Maximum cross-correlation shift in seconds. Defaults to the smaller of

  1. 1/2 of the obspy stream window length

  2. the maximum predicted inter-station differential time + dt

• dt (float, optional) – Seconds of additional allowed cross-correlation shifts beyond the maximumpredicted interchannel differential time. Default = 3.0

• rd_freq (float, optional) – Frequency at which to calculate surface wave reduced displacement using the velocity from the top layer of the velocity model. If not set, body wave reduced displacement will be calculated. Default = None

• raw_traces (stream, optional) – Obpsy stream of non-envelope traces matching the input st variable. Used to calculate reduced displacement. Default = []

• env_hp (stream, optional) – Obspy stream of second envelopes with traces matchin the input st variable. This would typically be envelopes generated in a different passband than st. If a location is obtained for st, it will also check env_hp and set a flag. This can be useful for weeding out earthquake detections or correlated noise spikes when you are only interested in detecting a band-limited signal. It essentially gives you a way to flag windows where you have coherent energy in two different passbands. Kind of a niche-use case, but necessary for my needs. Default = []

• edge_control (float, optional) – Value between 0 and 1 defining a percentage from the window edge to not allow the peak trace energy. That is, if any trace’s peak amplitude occurs between a with a percentage of the window edge, it is removed. Useful when autolocating. Default = 0.03

• num_processors (int, optional) – Number of processors to use if you are iterating through sliding windows to get locations. This can also be set in the locate() method. Default = 1.

• tt_file (str, optional) – Path to a .npz file containing pre-calculated traveltimes for this station set on this grid. Calulated using save_traveltimes() method. Default = None

• waveform_loc (bool, optional) – Boolean flag to optionally locate waveforms rather than envelopes. This flag exists to bypass some of the built in envelope quailty control Default = False

• gap_value (int, optional) – Value used to flag data gaps identified in preprocessing. Default = -123454321

• return (object) –

calculate_traveltimes()

Calculate travel times based on the model and grid provided in the XCOR object

save_traveltimes(outfile)

Save an .npz file containing the model and grid. The variables should be created using the calculate_traveltimes() method, which is called internally when initiating an XCOR object with a model and grid.

Parameters:

file (str, required) – The .npz file you wish to save, ideally with full path provided.

load_traveltimes(file)

Load an .npz file containing a model and grid, and assign the appropriate times to each trace in the object. The .npz file can be created initially using the save_traveltimes() method after XCOR has run calculate_traveltimes() with a model and grid.

Parameters:

file (str, required) – The path/filename to the .npz file you wish to load

locate(window_list=[], window_length=None, step=None, offset=0, include_partial_windows=False, nearest_sample=True, dTmax_s=None, num_processors=None)

Main method to locate data provided. This method is actually a wrapper to call main envelope cross correlation location algorithm XC_locate().

If using this to locate a single window of data, simply call locate() with no input parameters. All of the relevant details (plot, interact, map_resolution) are properties set in the initial object creation.

If using this to iterate over a list of user-provided windows, the following parameter must be set:

Parameters:

window_list (list, optional) – list containting 2x tuples of start and end times (Obspy UTCDatetime format) generated externally

If using this to create and iterate over windows internally, the following parameters must be set:

Parameters:

• window_length (float, optional) – Length of each sub-window in seconds. Default = None

• step (float, optional) – The step between the start times of two successive windows in seconds. Can be negative if an offset is given. Default = None

These parameters are optional:

Parameters:

• offset (float, optional) – The offset of the first window in seconds relative to the start time of the whole interval. Default = 0

• include_partial_windows (bool, optional) – Determines if sub-windows that are shorter then 99.9 % of the desired length are returned. Default = False

• nearest_sample (bool, optional) – If set to True, the closest sample is selected, if set to False, the inner (next sample for a start time border, previous sample for an end time border) sample containing the time is selected. Default = True

• dTmax_s (float, optional) –

  Maximum cross-correlation shift in seconds. Defaults to the smaller of

  1. 1/2 of the obspy stream sub-window length

  2. the maximum predicted inter-station differential time + ‘dt’, set during initial object creation

• num_processors (int, optional) – Number of processors to use in parallel Default = None