partialcorr: Partial correlation

hypercoil.functional.cov.partialcorr(X: Tensor, require_nonsingular: bool = True, **params) → Tensor

Partial Pearson correlation of variables in a tensor batch.

The partial correlation is obtained by conditioning the covariance of each pair of variables on all other observed variables. It can be interpreted as a measurement of the direct relationship between each variable pair. The partial correlation is efficiently computed via successive inversion and normalisation of the covariance matrix, accompanied by negation of off-diagonal entries.

Dimension:

Input : \((N, *, C, obs)\) or \((N, *, obs, C)\)

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

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

As above

Output : \((N, *, C, C)\)

As above

Parameters:

XTensor

Tensor containing a sample 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.

require_nonsingularbool

Indicates that the covariance must be nonsingular. If this is False, then the Moore-Penrose pseudoinverse is computed instead of the inverse.

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

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

See also

corr

Pearson correlation matrix

partialcov

Partial covariance matrix

conditionalcorr

Conditional correlation matrix