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 xx and yy is given by:

covw(x,y)=i=1N(xixˉ)(yiyˉ)N  1\text{cov}_w(x,y) = \frac{\sum^{N}_{i = 1}(x_{i} - \bar{x})(y_{i} - \bar{y})}{N~-~1}

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

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

covw(x,y)=i=1Nwi(xiμx)(yiμy)i=1Nwi  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}

where ww denotes fweights or aweights based on whichever is provided, or w=fweights×aweightsw = fweights \times aweights if both are provided, and μx=i=1Nwixii=1Nwi\mu_x^* = \frac{\sum^{N}_{i = 1}w_ix_{i} }{\sum^{N}_{i = 1}w_i} is the weighted mean of the variable.


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`.


(Tensor) The covariance matrix of the variables.

See also

torch.corrcoef() normalized covariance matrix.

>>> 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]])


Access comprehensive developer documentation for PyTorch

View Docs


Get in-depth tutorials for beginners and advanced developers

View Tutorials


Find development resources and get your questions answered

View Resources