UnaryCovarianceUW#

class hypercoil.nn.cov.UnaryCovarianceUW(estimator: Callable, dim: int, min_lag: int = 0, max_lag: int = 0, out_channels: int = 1, rowvar: bool = True, biased: bool = False, ddof: int | None = None, l2: float = 0, *, key: 'jax.random.PRNGKey' | None = None)[source]#

Covariance measures of a single tensor, without learnable weights.

The input tensor is interpreted as a set of multivariate observations. A covariance estimator computes some measure of statistical dependence among the variables in each observation, with the potential addition of stochastic noise and dropout to re-weight observations and regularise the model.

Dimension:
Input : \((N, *, C, O)\)

N denotes batch size, * denotes any number of intervening dimensions, C denotes number of data channels or variables, O denotes number of time points or observations per channel

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

W denotes number of sets of weights.

Parameters:
estimatorcallable

Covariance estimator, e.g. from hypercoil.functional.cov. The estimator must be unary: it should accept a single tensor rather than multiple tensors. Some available options are:

dimint

Number of observations O per data instance. This determines the dimension of each slice of the covariance weight tensor.

min_lag , max_lagint or None (default 0)

Minimum and maximum lags to include in the weight matrix. If these parameters are not None, the structure of the weight matrix is constrained to allow nonzero entries only along diagonals that are a maximum offset of (min_lag, max_lag) from the main diagonal. The default value of 0 permits weights only along the main diagonal.

out_channelsint (default 1)

Number of weight sets W to include. For each weight set, the module produces an output channel.

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.

biasedbool (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 biased parameter.

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 intermediate for estimating the regularised inverse covariance or to an ensure that the covariance matrix is non-singular (if, for instance, it needs to be inverted or projected into a tangent space).