chol

R Base 3.6.2

Compute the Choleski factorization of a real symmetric positive-definite square matrix.

Syntax

chol(x, &#8230;)<p></p><p># S3 method for default
chol(x, pivot = FALSE,  LINPACK = FALSE, tol = -1, &#8230;)</p>

Arguments

Parameter	Description
`x`	an object for which a method exists. The default method applies to numeric (or logical) symmetric, positive-definite matrices.
`…`	arguments to be based to or from methods.
`pivot`	Should pivoting be used?
`LINPACK`	logical. Should LINPACK be used (now ignored)?
`tol`	A numeric tolerance for use with pivot = TRUE.

Return Value

The upper triangular factor of the Choleski decomposition, i.e., the matrix \(R\) such that \(R'R = x\) (see example). If pivoting is used, then two additional attributes "pivot" and "rank" are also returned.

Details

chol is generic: the description here applies to the default method. Note that only the upper triangular part of x is used, so that \(R'R = x\) when x is symmetric. If pivot = FALSE and x is not non-negative definite an error occurs. If x is positive semi-definite (i.e., some zero eigenvalues) an error will also occur as a numerical tolerance is used. If pivot = TRUE, then the Choleski decomposition of a positive semi-definite x can be computed. The rank of x is returned as attr(Q, "rank"), subject to numerical errors. The pivot is returned as attr(Q, "pivot"). It is no longer the case that t(Q) %*% Q equals x. However, setting pivot <- attr(Q, "pivot") and oo <- order(pivot), it is true that t(Q[, oo]) %*% Q[, oo] equals x, or, alternatively, t(Q) %*% Q equals x[pivot, pivot]. See the exa

Examples

Example

# NOT RUN {
( m <- matrix(c(5,1,1,3),2,2) )
( cm <- chol(m) )
t(cm) %*% cm  #-- = 'm'
crossprod(cm)  #-- = 'm'

# now for something positive semi-definite
x <- matrix(c(1:5, (1:5)^2), 5, 2)
x <- cbind(x, x[, 1] + 3*x[, 2])
colnames(x) <- letters[20:22]
m <- crossprod(x)
qr(m)$rank # is 2, as it should be

# chol() may fail, depending on numerical rounding:
# chol() unlike qr() does not use a tolerance.
try(chol(m))

(Q <- chol(m, pivot = TRUE))
## we can use this by
pivot <- attr(Q, "pivot")
crossprod(Q[, order(pivot)]) # recover m

## now for a non-positive-definite matrix
( m <- matrix(c(5,-5,-5,3), 2, 2) )
try(chol(m))  # fails
(Q <- chol(m, pivot = TRUE)) # warning
crossprod(Q)  # not equal to m
# }