`partialcov`: Partial covariance#

hypercoil.functional.cov.partialcov(X: Tensor, require_nonsingular: bool = True, **params) → Tensor[source]#

Partial covariance of variables in a tensor batch.

The partial covariance 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 covariance is computed via inversion of the covariance matrix, followed 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:

sigmaTensor: Partial covariance matrix of the variables in the input tensor.

partialcov: Partial covariance#

`partialcov`: Partial covariance#