cov

Covariance

Syntax

C = cov(A)

C = cov(A,B)

C = cov(___,w)

C = cov(___,nanflag)

Description

C = cov(A) returns the covariance.

• If A is a vector of observations, C is the scalar-valued variance.

• If A is a matrix whose columns represent random variables and whose rows represent observations, C is the covariance matrix with the corresponding column variances along the diagonal.

• If A is a scalar, cov(A) returns 0. If A is an empty array, cov(A) returns NaN.

C is normalized by the number of observations-1. If there is only one observation, it is normalized by 1.

C = cov(A,B) returns the covariance between two random variables A and B.

• If A and B are vectors of observations with equal length, cov(A,B) is the 2-by-2 covariance matrix.

• If A and B are matrices of observations, cov(A,B) treats A and B as vectors and is equivalent to cov(A(:),B(:)). A and B must be the same size.

• If A and B are scalars, cov(A,B) returns a 2-by-2 block of zeros. If A and B are empty arrays, cov(A,B) returns a 2-by-2 block of NaN.

C = cov(___,w) specifies the normalization weight for any of the previous syntaxes. When w = 0 (default), C is normalized by the number of observations-1. When w = 1, it is normalized by the number of observations.

C = cov(___,nanflag) specifies a condition for handling NaN values in the input arrays. For example, cov(A,"omitrows") omits any rows of A containing one or more NaN values when computing the covariance. By default, cov includes NaN values.

Examples

Covariance of Matrix

Create a 3-by-4 matrix and compute its covariance.

A = [5 0 3 7; 1 -5 7 3; 4 9 8 10];
C = cov(A)

C = 4×4

    4.3333    8.8333   -3.0000    5.6667
    8.8333   50.3333    6.5000   24.1667
   -3.0000    6.5000    7.0000    1.0000
    5.6667   24.1667    1.0000   12.3333

Since the number of columns of A is 4, the result is a 4-by-4 matrix.

Covariance of Two Vectors

Create two vectors and compute their 2-by-2 covariance matrix.

A = [3 6 4];
B = [7 12 -9];
cov(A,B)

ans = 2×2

    2.3333    6.8333
    6.8333  120.3333

Covariance of Two Matrices

Create two matrices of the same size and compute their 2-by-2 covariance.

A = [2 0 -9; 3 4 1];
B = [5 2 6; -4 4 9];
cov(A,B)

ans = 2×2

   22.1667   -6.9333
   -6.9333   19.4667

Specify Normalization Weight

Create a matrix and compute the covariance normalized by the number of rows.

A = [1 3 -7; 3 9 2; -5 4 6];
C = cov(A,1)

C = 3×3

   11.5556    5.1111  -10.2222
    5.1111    6.8889    5.2222
  -10.2222    5.2222   29.5556

Covariance Excluding Missing Values

Create a matrix containing NaN values.

A = [1.77 -0.005 3.98; NaN -2.95 NaN; 2.54 0.19 1.01];

Compute the covariance of the matrix, excluding rows that contain any NaN value.

C = cov(A,"omitrows")

C = 3×3

    0.2964    0.0751   -1.1435
    0.0751    0.0190   -0.2896
   -1.1435   -0.2896    4.4104

Input Arguments

A — Input array

vector | matrix

Input array, specified as a vector or matrix.

Data Types: single | double

B — Additional input array

vector | matrix

Additional input matrix, specified as a vector or matrix. B must be the same size as A.

Data Types: single | double

w — Normalization weight

0 (default) | 1

Normalization weight, specified as one of these values:

• 0 — The output is normalized by the number of observations-1. If there is only one observation, it is normalized by 1.

• 1 — The output is normalized by the number of observations.

Data Types: single | double

nanflag — Missing value condition

"includemissing" (default) | "includenan" | "omitrows" | "partialrows"

Missing value condition, specified as one of these values:

• "includemissing" or "includenan" — Include NaN values in the input arrays when computing the covariance. "includemissing" and "includenan" have the same behavior.

• "omitrows" — Omit any rows of the input arrays containing one or more NaN values when computing the covariance.

• "partialrows" — Omit rows of the input arrays containing NaN values only on a pairwise basis for each two-column covariance calculation.

Output Arguments

C — Covariance

scalar | matrix

Covariance, returned as a scalar or matrix.

• For single matrix input, C has size [size(A,2) size(A,2)] based on the number of random variables (columns) represented by A. The variances of the columns are along the diagonal. If A is a row or column vector, C is the scalar-valued variance.

• For two-vector or two-matrix input, C is the 2-by-2 covariance matrix between the two random variables. The variances are along the diagonal of C.

More About

Covariance

For two random variable vectors A and B, the covariance is defined as

$$\mathrm{cov}(A,B)=\frac{1}{N-1}{\displaystyle \sum _{i=1}^N{(A_i-{\mu }_A)}^{*}(B_i-{\mu }_B)}$$

where μ_A is the mean of A, μ_B is the mean of B, and * denotes the complex conjugate.

The covariance matrix of two random variables is the matrix of pairwise covariance calculations between each variable,

$$C=\left(\begin{array}{cc}\mathrm{cov}(A,A)& \mathrm{cov}(A,B)\\ \mathrm{cov}(B,A)& \mathrm{cov}(B,B)\end{array}\right).$$

For a matrix A whose columns are each a random variable made up of observations, the covariance matrix is the pairwise covariance calculation between each column combination. In other words, $$C(i,j)=\mathrm{cov}\left(A(:,i),A(:,j)\right)$$.

Variance

For a finite-length vector A made up of N scalar observations, the variance is defined as

$$V=\frac{1}{N-1}{\displaystyle \sum _{i=1}^N|A_i-\mu {|}^2}$$

where μ is the mean of A,

$$\mu =\frac{1}{N}{\displaystyle \sum _{i=1}^N{A}_i}.$$

Some definitions of variance use a normalization factor of N instead of N-1, which you can specify by setting w to 1. In either case, the mean is assumed to have the usual normalization factor N.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function supports tall arrays with the limitations:

• A and B must be tall arrays of the same size, even if both are vectors.

• The "partialrows" option is not supported.

For more information, see Tall Arrays for Out-of-Memory Data.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• If the input is variable-size and is [] at run time, the function returns [] not NaN.

• See Variable-Sizing Restrictions for Code Generation of Toolbox Functions (MATLAB Coder).

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The cov function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2023a: Specify missing value condition

Include missing values in the input arrays when computing the covariance by using the "includemissing" option. This option has the same behavior as the "includenan" option.