`precision`: Inverse covariance (precision)#

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

Empirical precision of variables in a tensor batch.

The precision matrix is the inverse of the covariance matrix.

..note::: The precision matrix is not defined for singular covariance matrices. If the number of input observations is less than the number of variables, the covariance matrix can be regularised to ensure it is non-singular. This is done by setting the l2 parameter to a positive value. Alternatively, the require_nonsingular parameter can be set to False to use the Moore-Penrose pseudoinverse of the covariance matrix.

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:

omegaTensor: Precision matrix of the variables in input tensor X.

precision: Inverse covariance (precision)#

`precision`: Inverse covariance (precision)#