Engee documentation

cov

Covariance.

Library

EngeeDSP

Syntax

Function call

  • C = cov(A) — returns covariance.

    • If A — the vector of observations, then C — scalar value variances.

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

    • If A — scalar, cov(A) returns 0. If A — empty array, cov(A) returns NaN.

    Output argument C normalizes to the number of observations minus 1. If the observation is the only one, then C normalizes to 1.

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

    • If A and B — observation vectors of the same length, then C — covariance matrix of size 2 on 2.

    • If A and B — matrices of observations, then the function cov examines arguments A and B as vectors, and this call is equivalent to cov(A[:],B[:]). Input arguments A and B they must be the same size.

    • If A and B — scalars, cov(A,B) returns a block of zeros in size 2 on 2. If A and B — empty arrays, cov(A,B) returns a block of values NaN size 2 on 2.

  • C = cov(___,w) — sets the normalization weight for any of the previous syntaxes. By w = 0 (default) output argument C normalizes to the number of observations minus 1. By w = 1 — exactly the number of observations.

  • C = cov(___,nanflag) — sets a condition for processing values NaN in the input arrays. For example, cov(A,"omitrows") ignores any array rows. A containing one or more values NaN. The default function is cov takes into account the values NaN.

Arguments

Input arguments

# A — input array

+ vector | the matrix

Details

An input array specified as a vector or matrix.

Типы данных

Float32, Float64

# B — additional input array

+ vector | the matrix

Details

An additional input array specified as a vector or matrix. Argument B must have the same size as A.

Типы данных

Float32, Float64

# w is the normalization weight

+ 0 (default) | 1

Details

Normalization weight, set as:

  • 0 — the output argument is normalized to the number of observations minus 1. If the observation is the only one, then on 1.

  • 1 — the output argument is normalized to the number of observations.

Типы данных

Float32, Float64

# nanflag — condition for missing value

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

Details

The condition for missing a value, set as:

  • "includemissing" or "includenan" — the function takes into account the values NaN in the input arrays when calculating the covariance. Values "includemissing" and "includenan" they behave the same way.

  • "omitrows" — the function ignores all input array lines containing one or more values. NaN, when calculating the covariance.

  • "partialrows" — the function ignores input array strings containing values NaN, only in pairs for each calculation of the covariance in two columns.

Output arguments

# C — covariance

+ scalar | the matrix

Details

Covariance, returned as a scalar or matrix.

  • For one input matrix, the argument C has a size of [size(A,2) size(A,2)] based on the number of random variables (columns) represented in the matrix A. The column variances are located along the diagonal. If A — row vector or column vector, then C — this is a scalar variance.

  • For two input vectors or matrices, the argument C — this is a covariance matrix of size 2 on 2 between two random variables. The variances are located along the diagonal of the matrix C.

Examples

Covariance of the matrix

Details

Let’s create a matrix with the size 3 on 4 and calculate its covariance.

import EngeeDSP.Functions: cov

A = [5 0 3 7; 1 -5 7 3; 4 9 8 10]
C = cov(A)
4×4 Matrix{Float64}:
  4.33333   8.83333  -3.0   5.66667
  8.83333  50.3333    6.5  24.1667
 -3.0       6.5       7.0   1.0
  5.66667  24.1667    1.0  12.3333

Since the number of columns of the matrix is A equally 4, the result is a matrix 4 on 4.

Covariance of two vectors

Details

Let’s create two vectors and calculate their covariance matrix of size 2 on 2.

import EngeeDSP.Functions: cov

A = [3 6 4]
B = [7 12 -9]
cov(A, B)
2×2 Matrix{Float64}:
 2.33333    6.83333
 6.83333  120.333

Covariance of two matrices

Details

Let’s create two matrices of the same size and calculate their covariance in size 2 on 2.

import EngeeDSP.Functions: cov

A = [2 0 -9; 3 4 1]
B = [5 2 6; -4 4 9]
cov(A, B)
2×2 Matrix{Float64}:
 22.1667   -6.93333
 -6.93333  19.4667

Setting the normalization weight

Details

Let’s create a matrix and calculate its covariance, normalized by the number of rows.

import EngeeDSP.Functions: cov

A = [1 3 -7; 3 9 2; -5 4 6]
C = cov(A, 1)
3×3 Matrix{Float64}:
  11.5556   5.11111  -10.2222
   5.11111  6.88889    5.22222
 -10.2222   5.22222   29.5556

Covariance excluding missing values

Details

Create a matrix containing the values NaN.

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

Calculate the covariance of the matrix by excluding rows containing values NaN.

import EngeeDSP.Functions: cov

C = cov(A, "omitrows")
3×3 Matrix{Float64}:
  0.29645    0.075075   -1.14345
  0.075075   0.0190125  -0.289575
 -1.14345   -0.289575    4.41045

Additional Info

Covariance

Details

For two vectors of random variables and The covariance is defined as follows:

where — the average value , — the average value , and denotes a complex conjugation.

The covariance matrix of two random variables is a matrix of calculations of the covariance between each pair of variables.,

For the matrix , the columns of which are random variables consisting of observations, the covariance matrix is a pairwise calculation of the covariance between each combination of columns. In other words,

Variance

Details

For the vector of finite length, consisting of For scalar observations, the variance is defined as follows:

where — the average value ,

Some definitions of variance use a normalization factor. Instead of , which can be set by setting for the argument w meaning 1. In any case, it is assumed that the average value has the usual normalization factor. .