erlab.analysis.correlation

Macros for correlation analysis.

Functions

acf2(arr[, mode, method])

Calculate the autocorrelation function (ACF) of a 2D array including NaNs.

acf2stack(arr[, stack_dims, mode, method])

Calculate two-dimensional autocorrelation across a stack.

xcorr1d(in1, in2[, method])

Calculate the one-dimensional cross-correlation of two DataArrays.
erlab.analysis.correlation.acf2(arr, mode='full', method='fft')[source]

Calculate the autocorrelation function (ACF) of a 2D array including NaNs.

Parameters:

  • arr – The input array for which the ACF needs to be calculated.

  • mode (str, default: 'full') – The mode of the ACF calculation, by default "full". For more information, see scipy.signal.correlate.

  • method (str, default: 'fft') – The method used for ACF calculation, by default "fft". For more information, see scipy.signal.correlate.

Returns:

xarray.DataArray – The ACF of the input array.

Examples

>>> import numpy as np
>>> import xarray as xr
>>> np.random.seed(0)  # Set the random seed for reproducibility
>>> arr = xr.DataArray(np.random.rand(10, 10), dims=("kx", "ky"))
>>> acf = acf2(arr)
>>> acf
<xarray.DataArray (qx: 19, qy: 19)> Size: 3kB
8.403e-05 0.01495 0.01979 0.02734 0.03215 ... 0.02734 0.01979 0.01495 8.403e-05
Coordinates:
* qx       (qx) int64 152B -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9
* qy       (qy) int64 152B -9 -8 -7 -6 -5 -4 -3 -2 -1 0 1 2 3 4 5 6 7 8 9
erlab.analysis.correlation.acf2stack(arr, stack_dims=('eV',), mode='full', method='fft')[source]

Calculate two-dimensional autocorrelation across a stack.

Parameters:

  • arr – Input DataArray. For input with three or more dimensions, exactly two dimensions must remain after stack_dims are excluded. Those two dimensions require uniformly spaced coordinates with at least two values.

  • stack_dims (default: ('eV',)) – Dimensions that identify independent two-dimensional slices. Their order, sizes, and dimension coordinates are retained. This argument is ignored for a two-dimensional input.

  • mode (str, default: 'full') – Output-size mode passed to scipy.signal.correlate(). "full" gives each correlation dimension a length of 2 * n - 1. "same" retains the input length.

  • method (str, default: 'fft') – Correlation method passed to scipy.signal.correlate().

Returns:

xarray.DataArray – Autocorrelation values with the input dimension order. Stack dimensions retain their coordinates. Each correlation coordinate contains signed lags in the units of the corresponding input coordinate. Dimensions named kx and ky are renamed to qx and qy when both are present. Input attributes are retained. The result is backed by an in-memory NumPy array.

For input with three or more dimensions, mode="same" also retains other compatible coordinates and the input name. A two-dimensional input and modes that allocate a new array retain only the documented dimension coordinates and do not retain the input name.

Notes

Each slice is processed independently with joblib. NaN values are excluded through a correlated validity mask. For a slice with a finite, nonzero zero-lag value, the autocorrelation is normalized to one at zero lag. A two-dimensional input delegates to acf2().

erlab.analysis.correlation.xcorr1d(in1, in2, method='direct')[source]

Calculate the one-dimensional cross-correlation of two DataArrays.

Parameters:

  • in1 (DataArray) – Reference data. It must have one dimension with a uniformly spaced coordinate that contains at least two values.

  • in2 (DataArray) – Data to correlate with in1. It is first interpolated to the coordinates of in1. Values outside its coordinate range and NaN values in either input are treated as zero.

  • method (default: 'direct') – Correlation method passed to scipy.signal.correlate().

Returns:

xarray.DataArray – Unnormalized cross-correlation with the same shape, dimension name, attributes, name, and compatible auxiliary coordinates as in1. The dimension coordinate is shifted so that the zero-lag sample has coordinate value zero. The result is backed by an in-memory NumPy array, and the inputs are not modified.

Notes

The correlation uses mode="same".