chol                  package:base                  R Documentation

_T_h_e _C_h_o_l_e_s_k_i _D_e_c_o_m_p_o_s_i_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Compute the Choleski factorization of a symmetric (Hermitian),
     positive definite square matrix.

_U_s_a_g_e:

     chol(x, pivot = FALSE)

_A_r_g_u_m_e_n_t_s:

       x: a symmetric, positive definite matrix

   pivot: Should pivoting be used?

_D_e_t_a_i_l_s:

     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 may or may not occur, depending on finite
     precision numerical errors.

     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.

_V_a_l_u_e:

     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.

_W_a_r_n_i_n_g:

     The code does not check for symmetry or for non-negative
     definiteness.  If `pivot = TRUE' and `x' is not non-negative
     definite then there will be no error message but a meaningless
     result will occur.  So only use `pivot = TRUE' when `x' is
     non-negative definite by construction.

_R_e_f_e_r_e_n_c_e_s:

     Dongarra, J. J., Bunch, J. R., Moler, C. B. and Stewart, G. W.
     (1978) LINPACK Users Guide.  Philadelphia: SIAM Publications.

_S_e_e _A_l_s_o:

     `chol2inv' for its inverse (without pivoting), `backsolve' for
     solving linear systems with upper triangular left sides.

     `qr', `svd' for related matrix factorizations.

_E_x_a_m_p_l_e_s:

     ( m <- matrix(c(5,1,1,3),2,2) )
     ( cm <- chol(m) )
     t(cm) %*% cm  #-- = 'm'
     all(abs(m  -  t(cm) %*% cm) < 100* .Machine$double.eps) # TRUE


     x <- matrix(c(1:5, (1:5)^2), 5, 2)
     m <- crossprod(x)
     Q <- chol(m)
     all.equal(t(Q) %*% Q, m) # TRUE

     Q <- chol(m, pivot = TRUE)
     pivot <- attr(Q, "pivot")
     oo <- order(pivot)
     all.equal(t(Q[, oo]) %*% Q[, oo], m) # TRUE
     all.equal(t(Q) %*% Q, m[pivot, pivot]) # TRUE

     # now for something positive semi-definite
     x <- cbind(x, x[, 1]+3*x[, 2])
     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.
     test <- try(Q <- chol(m))     

     (Q <- chol(m, pivot = TRUE)) # NB wrong rank here ... you have been warned!
     pivot <- attr(Q, "pivot")
     oo <- order(pivot)
     all.equal(t(Q[, oo]) %*% Q[, oo], m) # TRUE
     all.equal(t(Q) %*% Q, m[pivot, pivot]) # TRUE

