Cross-correlation matrix

Cross-correlation matrix#

Cross-correlation matrix in time domain.

class covseisnet.correlation.CrossCorrelationMatrix(input_array: ndarray, stats: list[Stats] | list[dict] | None = None, stft: ShortTimeFourierTransform | None = None, pairs: list[tuple[str, str]] | list[str] | None = None)[source]#

Bases: ndarray

Cross-correlation matrix in the time domain.

The correlation matrix is stored with pairwise correlations along the first axis. Pair metadata are stored explicitly in the pairs attribute, because the station-pair axis is a compressed representation of the upper triangular part of the original covariance matrix.

Create a cross-correlation matrix.

Parameters:

  • input_array (numpy.ndarray) -- Correlation array. The first axis is expected to represent station pairs whenever pair metadata are provided.

  • stats (list, optional) -- Station metadata inherited from the covariance matrix.

  • stft (ShortTimeFourierTransform, optional) -- STFT parameters inherited from the covariance matrix.

  • pairs (list, optional) -- Pair metadata associated with the first axis. Each pair should be a tuple (station_i, station_j). For metadata-free objects, strings such as "pair 0" are also accepted.

property stations: list[str] | None#

Return station names when station metadata are available.

property pair_indices: dict[tuple[str, str] | str, int]#

Dictionary mapping pair metadata to first-axis indices.

pair(station_i: str, station_j: str) → ndarray[source]#

Return one pairwise cross-correlation.

The returned object is a plain numpy.ndarray, because the pair axis has been consumed and the result is no longer a CrossCorrelationMatrix.

select_pairs(pairs: list[tuple[str, str] | str]) → CrossCorrelationMatrix[source]#

Return a correlation matrix restricted to selected pairs.

The pair metadata are updated consistently with the first axis.

property sampling_rate: float#

Return the sampling rate in Hz.

envelope(**kwargs) → CrossCorrelationMatrix[source]#

Hilbert envelope of the correlation matrix.

taper(max_percentage: float = 0.1) → CrossCorrelationMatrix[source]#

Taper the correlation matrix along the lag axis.

smooth(sigma: float = 1, **kwargs) → CrossCorrelationMatrix[source]#

Use a Gaussian kernel to smooth the correlation matrix.

flat()[source]#

Flatten all dimensions except the lag axis.

bandpass(frequency_band: tuple | list, filter_order: int = 4) → CrossCorrelationMatrix[source]#

Bandpass filter the correlation functions.

covseisnet.correlation.calculate_cross_correlation_matrix(covariance_matrix: CovarianceMatrix, include_autocorrelation: bool = True) → tuple[ndarray, list, CrossCorrelationMatrix][source]#

Extract correlation in time domain from the given covariance matrix.

The returned CrossCorrelationMatrix stores the pair metadata in its pairs attribute, so pairwise correlations can be retrieved with CrossCorrelationMatrix.pair() or selected with CrossCorrelationMatrix.select_pairs().