Table of Contents
Shortcuts

# torch.cov

torch.cov(input, *, correction=1, fweights=None, aweights=None) → Tensor

  Estimates the covariance matrix of the variables given by the `input` matrix, where rows are the variables and columns are the observations.

  A covariance matrix is a square matrix giving the covariance of each pair of variables. The diagonal contains the variance of each variable (covariance of a variable with itself). By definition, if `input` represents a single variable (Scalar or 1D) then its variance is returned.

  The unbiased sample covariance of the variables x x x and y y y is given by:

  cov w(x,y)=∑i=1 N(x i−x ˉ)(y i−y ˉ)N − 1\text{cov}_w(x,y) = \frac{\sum^{N}_{i = 1}(x_{i} - \bar{x})(y_{i} - \bar{y})}{N~-~1} cov w​(x,y)=N − 1∑i=1 N​(x i​−x ˉ)(y i​−y ˉ​)​

  where x ˉ\bar{x}x ˉ and y ˉ\bar{y}y ˉ​ are the simple means of the x x x and y y y respectively.

  If `fweights` and/or `aweights` are provided, the unbiased weighted covariance is calculated, which is given by:

  cov w(x,y)=∑i=1 N w i(x i−μ x∗)(y i−μ y∗)∑i=1 N w i − 1\text{cov}_w(x,y) = \frac{\sum^{N}_{i = 1}w_i(x_{i} - \mu_x^*)(y_{i} - \mu_y^*)}{\sum^{N}_{i = 1}w_i~-~1} cov w​(x,y)=∑i=1 N​w i​ − 1∑i=1 N​w i​(x i​−μ x∗​)(y i​−μ y∗​)​

  where w w w denotes `fweights` or `aweights` based on whichever is provided, or w=f w e i g h t s×a w e i g h t s w = fweights \times aweights w=f w e i g h t s×a w e i g h t s if both are provided, and μ x∗=∑i=1 N w i x i∑i=1 N w i\mu_x^* = \frac{\sum^{N}_{i = 1}w_ix_{i} }{\sum^{N}_{i = 1}w_i}μ x∗​=∑i=1 N​w i​∑i=1 N​w i​x i​​ is the weighted mean of the variable.

  Parameters:

    input (Tensor) – A 2D matrix containing multiple variables and observations, or a Scalar or 1D vector representing a single variable.

  Keyword Arguments:

    - correction (int, optional) – difference between the sample size and sample degrees of freedom. Defaults to Bessel’s correction, `correction = 1` which returns the unbiased estimate, even if both `fweights` and `aweights` are specified. `correction = 0` will return the simple average. Defaults to `1`.

    - fweights (tensor, optional) – A Scalar or 1D tensor of observation vector frequencies representing the number of times each observation should be repeated. Its numel must equal the number of columns of `input`. Must have integral dtype. Ignored if `None`. Defaults to ``None`.

    - aweights (tensor, optional) – A Scalar or 1D array of observation vector weights. These relative weights are typically large for observations considered “important” and smaller for observations considered less “important”. Its numel must equal the number of columns of `input`. Must have floating point dtype. Ignored if `None`. Defaults to ``None`.

  Returns:

    (Tensor) The covariance matrix of the variables.

  See also

  `torch.corrcoef()` normalized covariance matrix.

  Example::

        >>> x = torch.tensor([[0, 2], [1, 1], [2, 0]]).T
        >>> x
        tensor([[0, 1, 2],
                [2, 1, 0]])
        >>> torch.cov(x)
        tensor([[ 1., -1.],
                [-1.,  1.]])
        >>> torch.cov(x, correction=0)
        tensor([[ 0.6667, -0.6667],
                [-0.6667,  0.6667]])
        >>> fw = torch.randint(1, 10, (3,))
        >>> fw
        tensor([1, 6, 9])
        >>> aw = torch.rand(3)
        >>> aw
        tensor([0.4282, 0.0255, 0.4144])
        >>> torch.cov(x, fweights=fw, aweights=aw)
        tensor([[ 0.4169, -0.4169],
                [-0.4169,  0.4169]])

## Docs

Access comprehensive developer documentation for PyTorch

View Docs

## Tutorials

Get in-depth tutorials for beginners and advanced developers

View Tutorials

## Resources

Find development resources and get your questions answered

View Resources

To analyze traffic and optimize your experience, we serve cookies on this site. By clicking or navigating, you agree to allow our usage of cookies. As the current maintainers of this site, Facebook’s Cookies Policy applies. Learn more, including about available controls: Cookies Policy.