5.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:

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