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 real symmetric
     positive-definite square matrix.

_U_s_a_g_e:

     chol(x, pivot = FALSE,  LINPACK = pivot)
     La.chol(x)

_A_r_g_u_m_e_n_t_s:

       x: a real symmetric, positive-definite matrix

   pivot: Should pivoting be used?

 LINPACK: logical. Should LINPACK be used (for compatibility with R <
          1.7.0)?

_D_e_t_a_i_l_s:

     'chol(pivot = TRUE)' provides an interface to the LINPACK routine
     DCHDC. 'La.chol' provides an interface to the LAPACK routine
     DPOTRF.

     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.

_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.

     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:

     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.

     Anderson. E. and ten others (1999) _LAPACK Users' Guide_. Third
     Edition. SIAM.
      Available on-line at <URL:
     http://www.netlib.org/lapack/lug/lapack_lug.html>.

_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'
     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])
     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)) # NB wrong rank here ... see Warning section.
     ## we can use this by
     pivot <- attr(Q, "pivot")
     oo <- order(pivot)
     t(Q[, oo]) %*% Q[, oo] # recover m

