6.2.4.1.8. eqcorrscan.utils.clustering.distance_matrix¶

eqcorrscan.utils.clustering.distance_matrix(stream_list, shift_len=0.0, replace_nan_distances_with=None, allow_individual_trace_shifts=True, cores=1)[source]¶

Compute distance matrix for waveforms based on cross-correlations.

Function to compute the distance matrix for all templates - will give distance as 1-abs(cccoh), e.g. a well correlated pair of templates will have small distances, and an equally well correlated reverse image will have the same distance as a positively correlated image - this is an issue.

Parameters:

Parameters:	stream_list (list) – List of the `obspy.core.stream.Stream` to compute the distance matrix for shift_len (float) – How many seconds for templates to shift allow_individual_trace_shifts (bool) – Controls whether templates are shifted by shift_len in relation to the picks as a whole, or whether each trace can be shifted individually. Defaults to True. replace_nan_distances_with (None, 'mean', 'min', or float) – Controls how the clustering handles nan-distances in the distance matrix. None/False only performs a check, while other choices (e.g., 1, ‘mean’, ‘min’ or float) replace nans in the distance matrix. cores (int) – Number of cores to parallel process using, defaults to 1.
Returns:	distance matrix (`numpy.ndarray`) of size len(stream_list)2 shift matrix (`numpy.ndarray`) containing shifts between traces of the sorted streams. Size is len(stream_list)2 * x, where x is 1 for shift_len=0 and/or allow_individual_trace_shifts=False. Missing correlations are indicated by nans. shift dict (`dict`): dictionary of (template_id: trace_dict) where trace_dict contains (trace.id: shift matrix (size len(stream_list)**2) for trace.id)

stream_list (list) – List of the obspy.core.stream.Stream to compute the distance matrix for
shift_len (float) – How many seconds for templates to shift
allow_individual_trace_shifts (bool) – Controls whether templates are shifted by shift_len in relation to the picks as a whole, or whether each trace can be shifted individually. Defaults to True.
replace_nan_distances_with (None, 'mean', 'min', or float) – Controls how the clustering handles nan-distances in the distance matrix. None/False only performs a check, while other choices (e.g., 1, ‘mean’, ‘min’ or float) replace nans in the distance matrix.
cores (int) – Number of cores to parallel process using, defaults to 1.

Returns:

distance matrix (numpy.ndarray) of size len(stream_list)**2
shift matrix (numpy.ndarray) containing shifts between traces of the sorted streams. Size is len(stream_list)**2 * x, where x is 1 for shift_len=0 and/or allow_individual_trace_shifts=False. Missing correlations are indicated by nans.
shift dict (dict): dictionary of (template_id: trace_dict) where trace_dict contains (trace.id: shift matrix (size len(stream_list)**2) for trace.id)

Warning

Because distance is given as \(1-abs(coherence)\), negatively correlated and positively correlated objects are given the same distance.

Note

Requires all traces to have the same sampling rate and same length.