`conditionalcov`: Conditional covariance#

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

Conditional covariance of variables in a tensor batch.

The conditional covariance is the covariance of one set of variables X conditioned on another set of variables Y. The conditional covariance is computed from the covariance \(\Sigma_{{XX}}\) of X , the covariance \(\Sigma_{{YY}}\) of Y, and the covariance \(\Sigma_{{XY}}\) between X and Y. It is defined as the Schur complement of \(\Sigma_{{YY}}\):

\(\Sigma_{X|Y} = \Sigma_{XX} - \Sigma_{XY} \Sigma_{YY}^{{-1}} \Sigma_{XY}^\intercal\)

The conditional covariance is equivalent to the covariance of the first set of variables after residualising them with respect to the second set of variables (plus an intercept term). This can be interpreted as the covariance of variables of interest (the first set) after controlling for the effects of confounds or nuisance variables (the second set).

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:

XTensor: Tensor containing samples of multivariate observations, with those variables whose influence we wish to control for removed and separated out into tensor Y. 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.
YTensor: Tensor containing samples of multivariate observations, limited to nuisance or confound variables whose influence we wish to control for. 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: Conditional empirical covariance matrix of the variables in input tensor X conditioned on the variables in input tensor Y.

conditionalcov: Conditional covariance#

`conditionalcov`: Conditional covariance#