qfeval_functions.functions.covar

covar(x, y, dim=-1, keepdim=False, ddof=1)[source]

Compute covariance between two tensors along a specified dimension.

This function calculates the covariance between tensors x and y along the specified dimension. Covariance measures how much two variables change together. Unlike numpy.cov, this function computes element-wise covariance for each batch index rather than producing a covariance matrix.

The covariance is computed as:

\[\text{Cov}(X, Y) = \frac{1}{N - \text{ddof}} \sum_{i=1}^{N} (X_i - \bar{X})(Y_i - \bar{Y})\]

where \(\bar{X}\) and \(\bar{Y}\) are the means of x and y respectively along the specified dimension, and \(N\) is the number of elements along that dimension.

The function is memory-efficient when broadcasting tensors. For example, when operating on tensors with shapes (N, 1, D) and (1, M, D), the space complexity remains O(ND + MD) instead of O(NMD).

Parameters:

  • x (Tensor) – The first input tensor.

  • y (Tensor) – The second input tensor. Must be broadcastable with x.

  • dim (int) – The dimension along which to compute the covariance. Default is -1 (the last dimension).

  • keepdim (bool) – Whether the output tensor has dim retained or not. Default is False.

  • ddof (int) – Delta degrees of freedom. The divisor used in the calculation is N - ddof, where N represents the number of elements. Default is 1.

Returns:

The covariance values. The shape depends on the input dimensions and the keepdim parameter.

Return type:

Tensor

Example

>>> x = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0])
>>> y = torch.tensor([2.0, 4.0, 6.0, 8.0, 10.0])
>>> QF.covar(x, y, dim=0)
tensor(5.)

>>> x = torch.tensor([[1.0, 2.0, 3.0],
...                   [4.0, 5.0, 6.0]])
>>> y = torch.tensor([[2.0, 4.0, 5.0],
...                   [8.0, 10.0, 12.0]])
>>> QF.covar(x, y, dim=1)
tensor([1.5000, 2.0000])
>>> QF.covar(x, y, dim=1, keepdim=True, ddof=0)
tensor([[1.0000],
        [1.3333]])