var

Variance

Syntax

V = var(A)

V = var(A,w)

V = var(A,w,"all")

V = var(A,w,dim)

V = var(A,w,vecdim)

V = var(___,nanflag)

[V,M] = var(___)

Description

V = var(A) returns the variance of the elements of A along the first array dimension whose size does not equal 1. By default, the variance is normalized by N-1, where N is the number of observations

• If A is a vector of observations, then V is a scalar.

• If A is a matrix whose columns are random variables and whose rows are observations, then V is a row vector containing the variance corresponding to each column.

• If A is a multidimensional array, then var(A) operates along the first array dimension whose size does not equal 1, treating the elements as vectors. The size of V in this dimension becomes 1 while the sizes of all other dimensions are the same as A.

• If A is a scalar, then V is 0.

• If A is a 0-by-0 empty array, then V is NaN.

V = var(A,w) specifies a weighting scheme. When w = 0 (default), the variance is normalized by N-1, where N is the number of observations. When w = 1, the variance is normalized by the number of observations. w can also be a weight vector containing nonnegative elements. In this case, the length of w must equal the length of the dimension over which var is operating.

V = var(A,w,"all") computes the variance over all elements of A when w is either 0 or 1. This syntax is valid for MATLAB^® versions R2018b and later.

V = var(A,w,dim) returns the variance along the dimension dim. To maintain the default normalization while specifying the dimension of operation, set w = 0 in the second argument.

V = var(A,w,vecdim) computes the variance over the dimensions specified in the vector vecdim when w is 0 or 1. For example, if A is a matrix, then var(A,0,[1 2]) computes the variance over all elements in A, since every element of a matrix is contained in the array slice defined by dimensions 1 and 2.

V = var(___,nanflag) specifies whether to include or omit NaN values from the calculation for any of the previous syntaxes. For example, var(A,"includenan") includes all NaN values in A while var(A,"omitnan") ignores them.

[V,M] = var(___) also returns the mean of the elements of A used to calculate the variance. If V is the weighted variance, then M is the weighted mean. This syntax is valid for MATLAB versions R2022a and later.

Examples

Variance of Matrix

Create a matrix and compute its variance.

A = [4 -7 3; 1 4 -2; 10 7 9];
var(A)

ans = 1×3

   21.0000   54.3333   30.3333

Variance of Array

Create a 3-D array and compute its variance.

A(:,:,1) = [1 3; 8 4];
A(:,:,2) = [3 -4; 1 2];
var(A)

ans = 
ans(:,:,1) =

   24.5000    0.5000


ans(:,:,2) =

     2    18

Specify Variance Weight Vector

Create a matrix and compute its variance according to a weight vector w.

A = [5 -4 6; 2 3 9; -1 1 2];
w = [0.5 0.25 0.25];
var(A,w)

ans = 1×3

    6.1875    9.5000    6.1875

Specify Dimension for Variance

Create a matrix and compute its variance along the first dimension.

A = [4 -2 1; 9 5 7];
var(A,0,1)

ans = 1×3

   12.5000   24.5000   18.0000

Compute the variance of A along the second dimension.

var(A,0,2)

ans = 2×1

     9
     4

Variance of Array Page

Create a 3-D array and compute the variance over each page of data (rows and columns).

A(:,:,1) = [2 4; -2 1];
A(:,:,2) = [9 13; -5 7];
A(:,:,3) = [4 4; 8 -3];
V = var(A,0,[1 2])

V = 
V(:,:,1) =

    6.2500


V(:,:,2) =

    60


V(:,:,3) =

   20.9167

Variance Excluding NaN

Create a vector and compute its variance, excluding NaN values.

A = [1.77 -0.005 3.98 -2.95 NaN 0.34 NaN 0.19];
V = var(A,"omitnan")

V = 5.1970

Variance and Mean

Create a matrix and compute the variance and mean of each column.

A = [4 -7 3; 1 4 -2; 10 7 9];
[V,M] = var(A)

V = 1×3

   21.0000   54.3333   30.3333

M = 1×3

    5.0000    1.3333    3.3333

Create a matrix and compute the weighted variance and weighted mean of each column according to a weight vector w.

A = [5 -4 6; 2 3 9; -1 1 2];
w = [0.5 0.25 0.25];
[V,M] = var(A,w)

V = 1×3

    6.1875    9.5000    6.1875

M = 1×3

    2.7500   -1.0000    5.7500

Input Arguments

A — Input array

vector | matrix | multidimensional array

Input array, specified as a vector, matrix, or multidimensional array. If A is a scalar, then var(A) returns 0. If A is a 0-by-0 empty array, then var(A) returns NaN.

Data Types: single | double
Complex Number Support: Yes

w — Weight

0 (default) | 1 | vector

Weight, specified as one of:

• 0 — Normalize by N-1, where N is the number of observations. If there is only one observation, then the weight is 1.

• 1 — Normalize by N.

• Vector made up of nonnegative scalar weights corresponding to the dimension of A along which the variance is calculated.

Data Types: single | double

dim — Dimension to operate along

positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If you do not specify the dimension, then the default is the first array dimension of size greater than 1.

Dimension dim indicates the dimension whose length reduces to 1. The size(V,dim) is 1, while the sizes of all other dimensions remain the same.

Consider an m-by-n input matrix, A:

• var(A,0,1) computes the variance of the elements in each column of A and returns a 1-by-n row vector.

  

• var(A,0,2) computes the variance of the elements in each row of A and returns an m-by-1 column vector.

  

If dim is greater than ndims(A), then var(A) returns an array of zeros the same size as A.

vecdim — Vector of dimensions

vector of positive integers

Vector of dimensions, specified as a vector of positive integers. Each element represents a dimension of the input array. The lengths of the output in the specified operating dimensions are 1, while the others remain the same.

Consider a 2-by-3-by-3 input array, A. Then var(A,0,[1 2]) returns a 1-by-1-by-3 array whose elements are the variances computed over each page of A.

nanflag — NaN condition

"includenan" (default) | "omitnan"

NaN condition, specified as one of these values:

• "includenan" — The variance of input containing NaN values is also NaN.

• "omitnan" — All NaN values appearing in either the input array or weight vector are ignored.

Data Types: char

Output Arguments

V — Variance

scalar | vector | matrix | multidimensional array

Variance, returned as a scalar, vector, matrix, or multidimensional array.

• If A is a vector of observations, then V is a scalar.

• If A is a matrix whose columns are random variables and whose rows are observations, then V is a row vector containing the variance corresponding to each column.

• If A is a multidimensional array, then var(A) operates along the first array dimension whose size does not equal 1, treating the elements as vectors. The size of V in this dimension becomes 1 while the sizes of all other dimensions are the same as A.

• If A is a scalar, then V is 0.

• If A is a 0-by-0 empty array, then V is NaN.

M — Mean

scalar | vector | matrix | multidimensional array

Mean, returned as a scalar, vector, matrix, or multidimensional array.

• If A is a vector of observations, then M is a scalar.

• If A is a matrix whose columns are random variables and whose rows are observations, then M is a row vector containing the mean corresponding to each column.

• If A is a multidimensional array, then var(A) operates along the first array dimension whose size does not equal 1, treating the elements as vectors. The size of M in this dimension becomes 1 while the sizes of all other dimensions are the same as A.

• If A is a scalar, then M is equal to A.

• If A is a 0-by-0 empty array, then M is NaN.

If V is the weighted variance, then M is the weighted mean.

More About

Variance

For a random variable 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 can be specified by setting w to 1. In either case, the mean is assumed to have the usual normalization factor N.

Weighted Variance

For a random variable vector A made up of N scalar observations and weighting scheme w, the weighted variance is defined as

$$V_w=\frac{{\displaystyle \sum _{i=1}^N{w}_i|A_i-{\mu }_w{|}^2}}{{\displaystyle \sum _{i=1}^N{w}_i}}$$

where μ_w is the weighted mean of A.

Weighted Mean

For a random variable vector A made up of N scalar observations and weighting scheme w, the weighted mean is defined as

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

Extended Capabilities

Tall Arrays

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

This function supports tall arrays with the limitation:

• The weighting scheme cannot be a vector.

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:

• C++ code generation supports the following syntaxes:

  • V = var(A)

  • V = var(A,w)

  • V = var(A,w,"all")

  • V = var(A,w,dim)

  • V = var(A,w,vecdim)

  • V = var(__,nanflag)

• When specified, dimension must be a constant.

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

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• If specified, dim must be a constant.

• GPU code generation supports the following syntaxes:

  • V = var(A)

  • V = var(A,w)

  • V = var(A,w,"all")

  • V = var(A,w,dim)

  • V = var(A,w,vecdim)

  • V = var(__,nanflag)

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™.

This function fully supports GPU arrays. 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

R2022a: Return mean or weighted mean

The var function can now return the mean of the input elements used to calculate the variance by using a second output argument M. If a weighting scheme is specified, then var returns the weighted mean.