Cross-correlation matrix

Cross-correlation matrix#

Cross-correlation matrix in time domain.

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

Bases: ndarray

Mathematical definition

This class is used to store the correlation matrix in the time domain. The cross-correlation is defined as the inverse Fourier transform of the covariance. Given a covariance matrix \(C_{ij}(f)\), the correlation matrix \(R_{ij}(\tau)\) is defined as:

\[R_{ij}(\tau) = \mathcal{F}^{-1} \{ C_{ij}(f) \}\]

where \(\mathcal{F}^{-1}\) is the inverse Fourier transform, \(\tau\) is the lag time, and \(i\) and \(j\) are the station indices. Note that the correlation matrix is a symmetric matrix, with the diagonal elements being the auto-correlation. Therefore, we do not store the lower triangular part of the matrix.

Practical implementation

The correlation matrix is stored as a 3D array with the first dimension being the number of pairs, the second dimension the number of windows, and the third dimension the number of lags. The correlation matrix can be visualized as a 2D array with the pairs and windows in the first dimension and the lags in the second dimension with the method flat().

Tip

The correlation matrix is usually calculated from the covariance matrix using the method calculate_cross_correlation_matrix(). The method returns a CrossCorrelationMatrix object with adequate attributes.

Note

If for some reason you need to create a CrossCorrelationMatrix object from a numpy array, you have the several solutions provided by the numpy subclassing mechanism. We recommend using the contructor of the class, which allows to pass the stats and stft attributes, as in the following example:

>>> import numpy as np
>>> from covseisnet.correlation import CrossCorrelationMatrix
>>> correlation = CrossCorrelationMatrix(
...     np.random.rand(10, 5, 100),
...     stats=None,
...     stft=None,
... )
property sampling_rate: float#

Return the sampling rate in Hz.

The sampling rate is extracted from the first stats in the list of stats extracted from the covariance matrix. Note that if the covariance matrix was calculated with the calculate_covariance_matrix(), all streams must be synchronized and have the same sampling rate.

Returns:

float -- The sampling rate in Hz.

Raises:

ValueError -- If the stats attribute is not set.

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

Hilbert envelope of the correlation matrix.

The Hilbert envelope is calculated using the Hilbert transform of the pairwise cross-correlation:

\[E_{ij}(\tau) = | R_{ij}(\tau) + i \mathcal{H} R_{ij}(\tau) |\]

where \(\mathcal{H}\) is the Hilbert transform, and \(i\) is the imaginary unit. The Hilbert envelope is the absolute value of the Hilbert transform of the correlation matrix.

Parameters:

**kwargs (dict) -- Additional arguments to pass to hilbert(). By default, the axis is set to the last axis (lags).

Returns:

CrossCorrelationMatrix -- The Hilbert envelope of the correlation matrix.

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

Taper the correlation matrix.

Taper the correlation matrix with the given taper. The taper is applied to the last axis (lags) of the correlation matrix. The tapered correlation matrix is defined as:

\[R'_{ij}(\tau) = w_T(\tau) R_{ij}(\tau)\]

where \(w_T(\tau)\) is the taper of maximum duration \(T\).

Parameters:

max_percentage (float) -- The maximum percentage of the taper. The taper is a Tukey window with the given percentage of the window duration. Default is 0.1.

Returns:

CrossCorrelationMatrix -- The tapered correlation matrix.

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

Use a Gaussian kernel to smooth the correlation matrix.

This function is usually applied to the envelope of the correlation matrix to smooth the envelope. The smoothing is done using a Gaussian kernel with a standard deviation \(\sigma\). The smoothing is done along the last axis (lags). The smoothed correlation matrix is \(R'\) is defined as:

\[R'_{ij}(\tau) = G_{\sigma} * R_{ij}(\tau)\]

where \(G_{\sigma}\) is the Gaussian kernel with standard deviation \(\sigma\).

Parameters:

  • sigma (float) -- Standard deviation of the Gaussian kernel. The larger the value, the smoother the correlation matrix. Default is 1.

  • **kwargs (dict) -- Additional arguments passed to gaussian_filter1d().

Returns:

CrossCorrelationMatrix -- The smoothed cross-correlation matrix.

flat()[source]#

Flatten the first dimensions.

The shape of the pairwise cross-correlation is at maximum 3D, with the first dimension being the number of pairs, the second dimension the number of windows, and the third dimension the number of lags. This method flattens the first two dimensions to have a 2D array with the pairs and windows in the first dimension and the lags in the second dimension. This method also works for smaller dimensions.

Returns:

np.ndarray -- The flattened pairwise cross-correlation.s

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

Bandpass filter the correlation functions.

Apply a Butterworth bandpass filter to the correlation functions. Uses butter() and filtfilt() to avoid phase shift.

Parameters:

  • frequency_band (tuple) -- The frequency band to filter in Hz.

  • filter_order (int, optional) -- The order of the Butterworth filter.

Returns:

CrossCorrelationMatrix -- The bandpass filtered 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.

This method calculates the correlation in the time domain from the given covariance matrix. The covariance matrix is expected to be obtained from the method calculate_covariance_matrix(), in the CovarianceMatrix class.

The method first duplicate the covariance matrix to have a two-sided covariance matrix and perform the inverse Fourier transform to obtain the correlation matrix. The attributes of the covariance matrix are used to calculate the lags and pairs names of the correlation matrix.

For more details, see the CrossCorrelationMatrix class, in the rubric Mathematical definition.

Parameters:

  • covariance_matrix (CovarianceMatrix) -- The covariance matrix.

  • include_autocorrelation (bool, optional) -- Include the auto-correlation in the correlation matrix. Default is True.

Returns: