# chol

0th

Percentile

##### The Choleski Decomposition

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

Keywords
algebra, array
##### Usage
chol(x, ...)
"chol"(x, pivot = FALSE,  LINPACK = FALSE, tol = -1, ...)
##### Arguments
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 (which is deprecated)?
tol
A numeric tolerance for use with pivot = TRUE, LINPACK = FALSE).
##### 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 examples. Use of chol(pivot = FALSE, LINPACK = TRUE) was deprecated in R 1.7.0. Pivoting with LAPACK requires LAPACK >= 3.2 and was added in R 2.15.2. The value of tol is passed to LAPACK, with negative values selecting the default tolerance of (usually) nrow(x) * .Machine$double.neg.eps * max(diag(x). The algorithm terminates once the pivot is less than tol. The LINPACK interface is restricted to matrices x with less than$2^31$elements. ##### 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. ##### Note LINPACK = TRUE, pivot = FALSE (for compatibility with R < 1.7.0) was formally deprecated in R 2.15.2. ##### Warning The code does not check for symmetry. If pivot = TRUE and x is not non-negative definite then there will be a warning message but a meaningless result will occur. So only use pivot = TRUE when x is non-negative definite by construction. ##### Source This is an interface to the LAPACK routines DPOTRF and DPSTRF and the LINPACK routines DPOFA and DCHDC. LAPACK and LINPACK are from http://www.netlib.org/lapack and http://www.netlib.org/linpack and their guides are listed in the references. ##### References Anderson. E. and ten others (1999) LAPACK Users' Guide. Third Edition. SIAM. Available on-line at http://www.netlib.org/lapack/lug/lapack_lug.html. Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W. (1978) LINPACK Users Guide. Philadelphia: SIAM Publications. ##### See Also chol2inv for its inverse (without pivoting), backsolve for solving linear systems with upper triangular left sides. qr, svd for related matrix factorizations. ##### Aliases • chol • chol.default ##### Examples library(base) ( 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 
Documentation reproduced from package base, version 3.0.3, License: Part of R 3.0.3

### Community examples

Looks like there are no examples yet.