cholcov

Cholesky-like covariance decomposition

collapse all in page

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.

example

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

example

[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

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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])

Figure contains an axes object. The axes object with xlabel X1, ylabel X2 contains an object of type scatter.

Input Arguments

collapse all

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

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

collapse all

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.

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

collapse all

Extended Capabilities

expand all

Version History

Introduced in R2007a

expand all

See Also

| |