pairedcorr: Paired correlation

hypercoil.functional.cov.pairedcorr(X: Tensor, Y: Tensor, rowvar: bool = True, bias: bool = False, ddof: int | None = None, **params) → Tensor

Empirical Pearson correlation between variables in two tensor batches.

The correlation is obtained via normalisation of the covariance. Given a covariance matrix \(\hat{\Sigma} \in \mathbb{R}^{n \times n}\), each entry of the correlation matrix \(R \in \mathbb{R}^{n \times n}\) is defined according to

\(R_{ij} = \frac{\hat{\Sigma}_{ij}}{\sqrt{\hat{\Sigma}_{ii}} \sqrt{\hat{\Sigma}_{jj}}}\)

Danger

The l2 parameter has no effect on this function. It is included only for conformance with the cov function.

Dimension:

Input X: \((N, *, C_X, obs)\) or \((N, *, obs, C_X)\)

N denotes batch size, * denotes any number of intervening dimensions, \(C_X\) denotes number of data channels or variables to be correlated, obs denotes number of observations per channel

Input Y: \((N, *, C_Y, obs)\) or \((N, *, obs, C_Y)\)

\(C_Y\) denotes number of data channels or variables to be correlated (or conditioned on)

Weight : \((obs)\) or \((obs, obs)\)

As above

Output : \((N, *, C_X, C_Y)\)

As above

Parameters:

X, YTensors

Tensors containing samples of multivariate observations. Each slice along the last axis corresponds to an observation, and each slice along the penultimate axis corresponds to a data channel or more generally a variable.

rowvarbool (default True)

Indicates that the last axis of the input tensor is the observation axis and the penultimate axis is the variable axis. If False, then this relationship is transposed.

biasbool (default False)

Indicates that the biased normalisation (i.e., division by N in the unweighted case) should be performed. By default, normalisation of the covariance is unbiased (i.e., division by N - 1).

ddofint or None (default None)

Degrees of freedom for normalisation. If this is specified, it overrides the normalisation factor automatically determined using the bias parameter.

weightTensor or None (default None)

Tensor containing importance or coupling weights for the observations. If this tensor is 1-dimensional, each entry weights the corresponding observation in the covariance computation. If it is 2-dimensional, then it must be square, symmetric, and positive semidefinite. In this case, diagonal entries again correspond to relative importances, while off-diagonal entries indicate coupling factors. For instance, a banded or multi-diagonal tensor can be used to specify inter-temporal coupling for a time series covariance.

l2nonnegative float (default 0)

L2 regularisation term to add to the maximum likelihood estimate of the covariance matrix. This can be set to a positive value to obtain an intermediate for estimating the regularised inverse covariance.

Returns:

RTensor

Paired Pearson correlation matrix of the variables in the input tensor.