cholcov

Cholesky-like covariance decomposition

Syntax

T = cholcov(SIGMA)
[T,num] = cholcov(SIGMA)
[T,num] = cholcov(SIGMA,0)


Description

T = cholcov(SIGMA) computes T such that SIGMA = T'*T. SIGMA must be square, symmetric, and positive semi-definite. If SIGMA is positive definite, then T is the square, upper triangular Cholesky factor. If SIGMA is not positive definite, T is computed from an eigenvalue decomposition of SIGMA. T is not necessarily triangular or square in this case. Any eigenvectors whose corresponding eigenvalue is close to zero (within a small tolerance) are omitted. If any remaining eigenvalues are negative, T is empty.

[T,num] = cholcov(SIGMA) returns the number num of negative eigenvalues of SIGMA, and T is empty if num is positive. If num is zero, SIGMA is positive semi-definite. If SIGMA is not square and symmetric, num is NaN and T is empty.

[T,num] = cholcov(SIGMA,0) returns num equal to zero if SIGMA is positive definite, and T is the Cholesky factor. If SIGMA is not positive definite, num is a positive integer and T is empty. [...] = cholcov(SIGMA,1) is equivalent to [...] = cholcov(SIGMA).

Examples

The following 4-by-4 covariance matrix is rank-deficient:

C1 = [2 1 1 2;1 2 1 2;1 1 2 2;2 2 2 3]
C1 =
     2     1     1     2
     1     2     1     2
     1     1     2     2
     2     2     2     3
rank(C1)
ans =
     3

Use cholcov to factor C1:

T = cholcov(C1)
T =
   -0.2113    0.7887   -0.5774         0
    0.7887   -0.2113   -0.5774         0
    1.1547    1.1547    1.1547    1.7321

C2 = T'*T
C2 =
    2.0000   1.0000   1.0000   2.0000
    1.0000   2.0000   1.0000   2.0000
    1.0000   1.0000   2.0000   2.0000
    2.0000   2.0000   2.0000   3.0000

Use T to generate random data with the specified covariance:

C3 = cov(randn(1e6,3)*T)
C3 =
    1.9973    0.9982    0.9995    1.9975
    0.9982    1.9962    0.9969    1.9956
    0.9995    0.9969    1.9980    1.9972
    1.9975    1.9956    1.9972    2.9951

Extended Capabilities

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

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.