`scipy._external.array_api_extra._delegation:cov`

source: build-install/usr/lib/python3.14/site-packages/scipy/_external/array_api_extra/_delegation.py:172

Signature

def cov(m: Array, /, xp: ArrayNamespace | None = None) → Array

Summary

Estimate a covariance matrix (or a stack of covariance matrices).

Extended Summary

Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, $X = [x_{1}, x_{2}, ... x_{N}]^{T}$ , each with M observations, then element $C_{ij}$ of the $N im es N$ covariance matrix is the covariance of $x_{i}$ and $x_{j}$ . The element $C_{ii}$ is the variance of $x_{i}$ .

With the exception of supporting batch input, this provides a subset of the functionality of numpy.cov.

Parameters

m : array: An array of shape (..., N, M) whose innermost two dimensions contain M observations of N variables. That is, each row of m represents a variable, and each column a single observation of all those variables.
xp : array_namespace, optional: The standard-compatible namespace for m. Default: infer.

Returns

: array: An array having shape (..., N, N) whose innermost two dimensions represent the covariance matrix of the variables.

Examples

import array_api_strict as xp
import array_api_extra as xpx

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    import array_api_extra as xpx
ModuleNotFoundError: No module named 'array_api_extra'

Consider two variables, :math:`x_0` and :math:`x_1`, which correlate perfectly, but in opposite directions:

x = xp.asarray([[0, 2], [1, 1], [2, 0]]).T
x

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    x
NameError: name 'x' is not defined

Note how :math:`x_0` increases while :math:`x_1` decreases. The covariance matrix shows this clearly:

xpx.cov(x, xp=xp)

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    xpx.cov(x, xp=xp)
    ^^^
NameError: name 'xpx' is not defined

Note that element :math:`C_{0,1}`, which shows the correlation between :math:`x_0` and :math:`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)

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    xpx.cov(X, xp=xp)
    ^^^
NameError: name 'xpx' is not defined

xpx.cov(x, xp=xp)

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    xpx.cov(x, xp=xp)
    ^^^
NameError: name 'xpx' is not defined

xpx.cov(y, xp=xp)

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    xpx.cov(y, xp=xp)
    ^^^
NameError: name 'xpx' is not defined

Input with more than two dimensions is treated as a stack of two-dimensional input.

stack = xp.stack((X, 2*X))
xpx.cov(stack)

⚠

Traceback (most recent call last):
  File "<doctest scipy._external.array_api_extra._delegation:cov[0]>", line 1, in <module>
    xpx.cov(stack)
    ^^^
NameError: name 'xpx' is not defined

Aliases

scipy.differentiate.xpx.cov