residualise

hypercoil.functional.resid.residualise(Y: Tensor, X: Tensor, rowvar: bool = True, l2: float = 0.0, return_mode: str = 'residual') → Tensor

Residualise a tensor block via ordinary linear least squares.

Warning

When using torch, we have found in some cases that the least-squares fit returned was incorrect for reasons that are not clear. (Incorrect results are returned by torch.linalg.lstsq, although correct results are returned if torch.linalg.pinv is used instead.) Verify that results are reasonable when using this operation.

It is not clear whether the same is true for jax. Caution is advised.

Note

The conditional covariance or conditional correlation may be used instead where appropriate.

Dimension:

Input Y : \((N, *, C_Y, obs)\) or \((N, *, obs, C_Y)\)

N denotes batch size, * denotes any number of intervening dimensions, \(C_Y\) denotes number of data channels or variables, obs denotes number of observations per channel

Input X : \((N, *, C_X, obs)\) or \((N, *, obs, C_X)\)

\(C_X\) denotes number of data channels or variables

Output : \((N, *, C_Y, obs)\) or \((N, *, obs, C_Y)\)

As above.

Parameters:

YTensor

Tensor to be residualised or orthogonalised with respect to X. The vector of observations in each channel is projected into a subspace orthogonal to the span of X.

XTensor

Tensor containing explanatory variables. Any variance in Y that can be explained by variables in X will be removed from Y.

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.

l2float (default 0.0)

L2 regularisation parameter. If non-zero, the least-squares solution will be regularised by adding a penalty term to the cost function.

return_modeLiteral[‘residual’, ‘orthogonal’] (default ‘residual’)

Indicates whether the residual or orthogonal tensor should be returned. The orthogonal tensor is the projection of Y onto the span of X (i.e., the least-squares solution).