`scipy._lib.array_api_extra._delegation:cov`

source: /scipy/_lib/array_api_extra/_delegation.py :83

Signature

def cov ( m : Array , / , xp : ModuleType | 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

⚠

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

⚠

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

xpx.cov(x, xp=xp)

⚠

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)

⚠

xpx.cov(x, xp=xp)

⚠

xpx.cov(y, xp=xp)

⚠

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

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

⚠

[[ 46.84 , -17.144 ], [-17.144 , 8.57653333]]], dtype=array_api_strict.float64)

Aliases

scipy.differentiate.xpx.cov