5.1.1. lag_calc¶

Functions to generate pick-corrections for events detected by correlation.

copyright:: EQcorrscan developers.
license:: GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

Functions for generating pick-corrections from cross-correlations with a template. Originally this was designed for events detected by matched-filtering, however you can use any well correlated events. Based on the method of Shelly and Hardebeck (2010).

5.1.1.1. Functions¶

eqcorrscan.core.lag_calc.lag_calc(detections, detect_data, template_names, templates, shift_len=0.2, min_cc=0.4, min_cc_from_mean_cc_factor=None, all_vert=False, all_horiz=False, horizontal_chans=['E', 'N', '1', '2'], vertical_chans=['Z'], cores=1, interpolate=False, plot=False, plotdir=None, export_cc=False, cc_dir=None, **kwargs)[source]¶

Cross-correlation derived picking of seismic events.

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 output a obspy.core.event.Catalog of picked events. Pick times are based on the lag-times found at the maximum correlation, providing that correlation is above the min_cc.

Parameters:

detections (list) – List of eqcorrscan.core.match_filter.Detection objects.
detect_data (obspy.core.stream.Stream) – All the data needed to cut from - can be a gappy Stream.
template_names (list) – List of the template names, used to help identify families of events. Must be in the same order as templates.
templates (list) –

List of the templates, templates must be a list of
obspy.core.stream.Stream objects.
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.
min_cc_from_mean_cc_factor (float) – If set to a value other than None, then the minimum cross-correlation value for a trace is set individually for each detection based on: min(detect_val / n_chans * min_cc_from_mean_cc_factor, min_cc).
horizontal_chans (list) – List of channel endings for horizontal-channels, on which S-picks will be made.
vertical_chans (list) – List of channel endings for vertical-channels, on which P-picks will be made.
cores (int) – Number of cores to use in parallel processing, defaults to one.
interpolate (bool) – Interpolate the correlation function to achieve sub-sample precision.
plot (bool) – To generate a plot for every detection or not, defaults to False
plotdir – Path to plotting folder, plots will be output here.
export_cc (bool) – To generate a binary file in NumPy for every detection or not, defaults to False
cc_dir (str) – Path to saving folder, NumPy files will be output here.

Returns:

Catalog of events with picks. No origin information is included. These events can then be written out via obspy.core.event.Catalog.write(), or to Nordic Sfiles using eqcorrscan.utils.sfile_util.eventtosfile() and located externally.

Return type:

obspy.core.event.Catalog

Note

Picks output in catalog are generated relative to the template start-time. For example, if you generated your template with a pre_pick time of 0.2 seconds, you should expect picks generated by lag_calc to occur 0.2 seconds before the true phase-pick. This is because we do not currently store template meta-data alongside the templates.

Warning

Because of the above note, origin times will be consistently shifted by the static pre_pick applied to the templates.

Warning

This routine requires only one template per channel (e.g. you should not use templates with a P and S template on a single channel). If this does occur an error will be raised.

Note

S-picks will be made on horizontal channels, and P picks made on vertical channels - the default is that horizontal channels end in one of: ‘E’, ‘N’, ‘1’ or ‘2’, and that vertical channels end in ‘Z’. The options vertical_chans and horizontal_chans can be changed to suit your dataset.

Note

Individual channel cross-correlations are stored as a obspy.core.event.Comment for each pick, and the summed cross-correlation value resulting from these is stored as a obspy.core.event.Comment in the main obspy.core.event.Event object.

Note

The order of events is preserved (e.g. detections[n] == output[n]), providing picks have been made for that event. If no picks have been made for an event, it will not be included in the output. However, as each detection has an ID associated with it, these can be mapped to the output resource_id for each Event in the output Catalog. e.g.

detections[n].id == output[m].resource_id

if the output[m] is for the same event as detections[n].

Note

The correlation data that are saved to the binary files can be useful to select an appropriate threshold for your data.

eqcorrscan.core.lag_calc.xcorr_pick_family(family, stream, shift_len=0.2, min_cc=0.4, min_cc_from_mean_cc_factor=None, all_vert=False, all_horiz=False, vertical_chans=['Z'], horizontal_chans=['E', 'N', '1', '2'], cores=1, interpolate=False, plot=False, plotdir=None, export_cc=False, cc_dir=None, **kwargs)[source]¶

Compute cross-correlation picks for detections in a family.

Parameters:

family (eqcorrscan.core.match_filter.family.Family) – Family to calculate correlation picks for.
stream (obspy.core.stream.Stream) – Data stream containing data for all (or a subset of) detections in the Family
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.
min_cc_from_mean_cc_factor (float) – If set to a value other than None, then the minimum cross-correlation value for a trace is set individually for each detection based on: min(detect_val / n_chans * min_cc_from_mean_cc_factor, min_cc).
horizontal_chans (list) – List of channel endings for horizontal-channels, on which S-picks will be made.
vertical_chans (list) – List of channel endings for vertical-channels, on which P-picks will be made.
cores (int) – Number of cores to use in parallel processing, defaults to one.
interpolate (bool) – Interpolate the correlation function to achieve sub-sample precision.
plot (bool) – To generate a plot for every detection or not, defaults to False
plotdir (str) – Path to plotting folder, plots will be output here.
export_cc (bool) – To generate a binary file in NumPy for every detection or not, defaults to False
cc_dir (str) – Path to saving folder, NumPy files will be output here.

Returns:

Dictionary of picked events keyed by detection id.

5.1.1.2. Private Functions¶

Note that these functions are not designed for public use and may change at any point.

eqcorrscan.core.lag_calc._concatenate_and_correlate(streams, template, cores)[source]¶

Concatenate a list of streams into one stream and correlate that with a template.

All traces in a stream must have the same length.

eqcorrscan.core.lag_calc._prepare_data(family, detect_data, shift_len, all_vert=False, all_horiz=False, vertical_chans=['Z'], horizontal_chans=['E', 'N', '1', '2'])[source]¶

Prepare data for lag_calc - reduce memory here.

Parameters:

family (eqcorrscan.core.match_filter.family.Family) – The Family containing the template and detections.
detect_data (obspy.core.stream.Stream) – Stream to extract detection streams from.
shift_len (float) – Shift length in seconds allowed for picking.

Returns:

Dictionary of detect_streams keyed by detection id to be worked on

Return type:

dict

eqcorrscan.core.lag_calc._xcorr_interp(ccc, dt, resample_factor=10, use_new_resamp_method=False, **kwargs)[source]¶

Resample correlation-trace and check if there is a better CCC peak for sub-sample precision.

Parameters:

ccc (numpy.ndarray) – Cross-correlation array
dt (float) – sample interval
resample_factor (int) – Factor for upsampling CC-values (only for use_new_resamp_method=True)

Returns:

Position of interpolated maximum in seconds from start of ccc

Return type:

float