correlation_shift

mdcraft.algorithm.correlation.correlation_shift(x: ndarray[float | complex], y: ndarray[float | complex] = None, /, axis: int = None, *, average: bool = False, double: bool = False, vector: bool = False) → ndarray[float | complex][source]

Evaluates the autocorrelation functions (ACF) \(\mathrm{R_\mathbf{XX}}(\tau)\) or cross-correlation functions (CCF) \(\mathrm{R_\mathbf{XY}}(\tau)\) of time series \(\mathbf{X}(t)\) and \(\mathbf{Y}(t)\) directly by using sliding windows.

The ACF for a data set \(\mathbf{X}(t)\) can be computed using

\[\mathrm{R}_{\mathbf{XX}}(\tau) =\langle\mathbf{X}(t_0+\tau)\cdot\mathbf{X}^*(t_0)\rangle =\dfrac{1}{N_\tau}\sum_{j=1}^{N_\tau} \textbf{X}(t_j+\tau)\cdot\textbf{X}^*(t_j)\]

where \(\tau\) is the time lag, \(t_j\) is an arbitrary reference time, \(N_\tau\) is the number of possible reference times, and the asterisk (\(^*\)) denotes the complex conjugate.

Similarly, the CCF for data sets \(\mathbf{X}(t)\) and \(\mathbf{Y}(t)\) can be computed using

\[\mathrm{R}_{\mathbf{XY}}(\tau) =\langle\mathbf{X}(t_0+\tau)\cdot\mathbf{Y}^*(t_0)\rangle =\dfrac{1}{N_\tau}\sum_{j=1}^{N_\tau} \textbf{X}(t_j+\tau)\cdot\textbf{Y}^*(t_j)\]

To minimize statistical noise, the ACF/CCF is calculated for and averaged over all possible reference times \(t_0\). As such, this algorithm has a time complexity of \(\mathcal{O}(N^2)\). With large data sets, this approach is too slow to be useful. If your machine supports fast Fourier transforms (FFT), use the much more performant FFT-based algorithm implemented in mdcraft.algorithm.correlation.correlation_fft() instead.

Parameters:
xnumpy.ndarray, positional-only

Time evolution of \(d\)-dimensional data for \(N\) entities over \(N_\mathrm{b}\) blocks of \(N_t\) times each.

Shape:

  • Scalar: \((N_t,)\), \((N_t,\,N)\), \((N_\mathrm{b},\,N_t)\), or \((N_\mathrm{b},\,N_t,\,N)\).

  • Vector: \((N_t,\,d)\), \((N_t,\,N,\,d)\), \((N_\mathrm{b},\,N_t,\,d)\), or \((N_\mathrm{b},\,N_t,\,N,\,d)\).

ynumpy.ndarray, positional-only, optional

Time evolution of \(d\)-dimensional data for another \(N\) entities over \(N_\mathrm{b}\) blocks of \(N_t\) times each. If provided, the CCF for x and y is calculated. Otherwise, the ACF for x is calculated.

Shape: Same as x.

axisint, optional

Axis along which time evolves. If not specified, the axis is determined automatically using the shape of x.

averagebool, keyword-only, default: True

Determines whether the ACF/CCF is averaged over all entities. Only available if x and y contain information for multiple entities.

doublebool, keyword-only, default: False

Determines whether the ACF is doubled or the negative and positive time lags are combined for the CCF.

vectorbool, keyword-only, default: False

Specifies whether x and y contain vectors. If True, the ACF/CCF is summed over the last axis.

Returns:
corrnumpy.ndarray

ACF or CCF.

Shape:

For ACF, the shape is that of x but with the following modifications:

  • If average=True, the axis containing the \(N\) entities is removed.

  • If vector=True, the last axis is removed.

For CCF, the shape is that of x but with the following modifications:

  • If average=True, the axis containing the \(N\) entities is removed.

  • If double=False, the axis containing the \(N_t\) times now has a length of \(2N_t-1\) to accomodate negative and positive time lags.

  • If vector=True, the last axis is removed.