array_api_extra.cov

array_api_extra.cov(m, /, *, xp)

Estimate a covariance matrix.

Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, \(X = [x_1, x_2, ... x_N]^T\), then the covariance matrix element \(C_{ij}\) is the covariance of \(x_i\) and \(x_j\). The element \(C_{ii}\) is the variance of \(x_i\).

This provides a subset of the functionality of numpy.cov.

Parameters:

• m (array) – A 1-D or 2-D array containing multiple variables and observations. Each row of m represents a variable, and each column a single observation of all those variables.

• xp (array_namespace) – The standard-compatible namespace for m.

Returns:

res – The covariance matrix of the variables.

Return type:

array

Examples

>>> import array_api_strict as xp
>>> import array_api_extra as xpx

Consider two variables, \(x_0\) and \(x_1\), which correlate perfectly, but in opposite directions:

>>> x = xp.asarray([[0, 2], [1, 1], [2, 0]]).T
>>> x
Array([[0, 1, 2],
       [2, 1, 0]], dtype=array_api_strict.int64)

Note how \(x_0\) increases while \(x_1\) decreases. The covariance matrix shows this clearly:

>>> xpx.cov(x, xp=xp)
Array([[ 1., -1.],
       [-1.,  1.]], dtype=array_api_strict.float64)

Note that element \(C_{0,1}\), which shows the correlation between \(x_0\) and \(x_1\), is negative.

Further, note how x and y are combined:

>>> x = xp.asarray([-2.1, -1,  4.3])
>>> y = xp.asarray([3,  1.1,  0.12])
>>> X = xp.stack((x, y), axis=0)
>>> xpx.cov(X, xp=xp)
Array([[11.71      , -4.286     ],
       [-4.286     ,  2.14413333]], dtype=array_api_strict.float64)

>>> xpx.cov(x, xp=xp)
Array(11.71, dtype=array_api_strict.float64)

>>> xpx.cov(y, xp=xp)
Array(2.14413333, dtype=array_api_strict.float64)