cholcov

Cholesky-like covariance decomposition

Syntax

T = cholcov(X)

[T,num] = cholcov(X)

[T,num] = cholcov(X,AllowPosSemiDef)

Description

T = cholcov(X) computes the Cholesky factor T of the matrix X such that X = T'*T. The input matrix X must be symmetric positive definite or symmetric positive semi-definite. Otherwise, T is empty. For more information, see Symmetric Positive Definite Matrix.

If your input matrix X is positive definite, you can also use the chol function to compute its Cholesky factor.

[T,num] = cholcov(X) also returns the number of negative eigenvalues of X.

[T,num] = cholcov(X,AllowPosSemiDef) returns T as empty and num as an arbitrary positive integer when AllowPosSemiDef is false and X is positive semi-definite.

Examples

Cholesky Factor of Positive Definite Matrix

Create a symmetric positive definite 3-by-3 matrix of integers.

rng(0,"twister")  % For reproducibility
A = randi([0 2],3,3);
X = A'*A

X = 3×3

     8     6     2
     6     5     1
     2     1     5

Compute the Cholesky factor T such that X = T'*T.

T = cholcov(X)

T = 3×3

    2.8284    2.1213    0.7071
         0    0.7071   -0.7071
         0         0    2.0000

Because X is positive definite, T is a square, upper triangular matrix.

Verify that X = T'*T.

all(isapprox(X,T'*T),"all")

ans = logical
   1

Cholesky Factor of Positive Semi-Definite Matrix

Create a symmetric positive semi-definite 3-by-3 matrix of integers.

rng(0,"twister")  % For reproducibility
v1 = randi([0 2],3,1);
v2 = randi([0 2],3,1);
X = v1*v1.' + v2*v2.'

X = 3×3

     8     6     0
     6     5     0
     0     0     0

Compute the eigenvalues of X.

eig(X)

ans = 3×1

         0
    0.3153
   12.6847

X is positive semi-definite because it has no negative eigenvalues and at least one zero eigenvalue.

Compute the Cholesky factor T such that X = T'*T. Also return the number of negative eigenvalues num in X.

[T,num]= cholcov(X)

T = 2×3

   -0.3456    0.4426         0
    2.8072    2.1918         0

num = 
0

Because X is positive semi-definite, T is not a square matrix.

Verify that X = T'*T.

all(isapprox(X,T'*T),"all")

ans = logical
   1

Generate Correlated Samples Using Cholesky Decomposition

Create a column vector of means mu and a positive definite covariance matrix Sigma.

mu = [-4; 0; 4];
Sigma = [2 1 0; 1 2 1; 0 1 2];

Calculate the Cholesky factor of the covariance matrix.

T = cholcov(Sigma)

T = 3×3

    1.4142    0.7071         0
         0    1.2247    0.8165
         0         0    1.1547

Generate 200 random deviates from a standard normal distribution and transform them using the means mu and the Cholesky factor T.

rng(0,"twister")  % For reproducibility
n = 200;
Z = randn(length(mu),n); % Standard normal deviates
X = T*Z + mu;
X = X';

X is a 200-by-3 matrix of correlated samples drawn from the set of means mu using the covariance matrix Sigma.

Create a 3-D scatter plot of the samples.

scatter3(X(:,1),X(:,2),X(:,3));
xlabel("X1")
ylabel("X2")
zlabel("X3")
view([230 45])

Input Arguments

X — Input matrix

numeric matrix

Input matrix, specified as a numeric matrix. The input matrix X must be symmetric positive definite or symmetric positive semi-definite. Otherwise, the Cholesky factor T is empty.

Data Types: single | double

AllowPosSemiDef — Flag to compute T when X is positive semi-definite

true or 1 (default) | false or 0

Flag to compute T when X is positive semi-definite, specified as logical 0 (false) or 1 (true). If AllowPosSemiDef is false and X is positive semi-definite, then T is empty and num is an arbitrary positive integer.

Data Types: single | double | logical

Output Arguments

T — Cholesky factor

numeric matrix

Cholesky factor, returned as a numeric matrix.

• If X is positive definite, then T is the square, upper triangular Cholesky factor matrix.

• If X is positive semi-definite, and AllowPosSemiDef is true (the default), the function computes T from an eigenvalue decomposition of X. In this case, T is not necessarily triangular or square. Any eigenvectors whose corresponding eigenvalue is close to zero (within a small tolerance) are omitted. If any remaining eigenvalues are negative, then T is empty.

T is empty if any of the following are true:

• X is not symmetric.

• X is not positive definite or positive semi-definite.

• X is not positive definite and AllowPosSemiDef is false.

num — Number of negative eigenvalues of X

nonnegative integer

Number of negative eigenvalues of X, returned as a nonnegative integer.

• If num = 0, then X is positive definite or positive semi-definite.

• If num > 0 and AllowPosSemiDef is true (the default), then X is not positive definite or positive semi-definite, and num is the number of negative eigenvalues of X.

• If num > 0 and AllowPosSemiDef is false, then X is not positive definite, and num is an arbitrary positive integer.

• If num is NaN, then X is not symmetric.

More About

Symmetric Positive Definite Matrix

A symmetric positive definite matrix is a symmetric matrix with all positive eigenvalues.

For any real invertible matrix A, you can construct a symmetric positive definite matrix with the product X = A'*A. The Cholesky factorization reverses this formula by saying that any symmetric positive definite matrix X can be factored into the product T'*T.

A symmetric positive semi-definite matrix is defined in a similar manner, except that the eigenvalues must all be positive or zero.

The line between positive definite and positive semi-definite matrices is blurred in the context of numeric computation. It is rare for eigenvalues to be exactly equal to zero, but they can be numerically zero (on the order of machine precision). For this reason, cholcov might be able to return a square, triangular Cholesky factor for one positive semi-definite matrix, but could fail with another matrix that has very similar eigenvalues.

Extended Capabilities

Thread-Based Environment

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

The cholcov 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).

Version History

Introduced in R2007a

R2024a: cholcov returns num on the CPU

Starting in R2024a, cholcov returns the num output argument on the CPU when you specify gpuArray input arguments. In previous releases, the num output argument was returned on the GPU.