nearPD                package:Matrix                R Documentation

_N_e_a_r_e_s_t _M_a_t_r_i_x _t_o _a _P_o_s_i_t_i_v_e _D_e_f_i_n_i_t_e _M_a_t_r_i_x

_D_e_s_c_r_i_p_t_i_o_n:

     Computes the nearest positive definite matrix to an approximate
     one, typically a correlation or variance-covariance matrix.

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

     nearPD(x, corr = FALSE,
            eig.tol = 1e-06, conv.tol = 1e-07, posd.tol = 1e-08,
            do2eigen = TRUE, maxit = 100, verbose = FALSE)

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

       x: numeric n * n approximately positive definite matrix,
          typically an approximation to a correlation or covariance
          matrix.

    corr: logical indicating if the matrix should be a _correlation_
          matrix.

 eig.tol: defines relative positiveness of eigenvalues compared to
          largest one.

conv.tol: convergence tolerance for algorithm.

posd.tol: tolerance for enforcing positive definiteness.

do2eigen: logical indicating if a 'posdefify()' eigen step should be
          applied to the result of the Hingham algorithm.

   maxit: maximum number of iterations allowed.

 verbose: logical; if 'TRUE' the iterations are monitored by print out.

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

     Note that setting 'corr = TRUE' just sets 'diag(.) <- 1' within
     the algorithm.

_V_a_l_u_e:

     an S3 object of 'class' '"nearPD"', basically a list with
     components 

     mat: a matrix of class 'dpoMatrix', the computed positive-definite
          matrix.

    corr: logical, just the argument 'corr'.

   normF: the Frobenius norm ('norm(x-X, "F")') of the difference
          between the original and the resulting matrix.

iterations: number of iterations needed.

converged: logical indicating if iterations converged.

_A_u_t_h_o_r(_s):

     Jens Oehlschlaegel donated a first version.  Subsequent changes by
     the Matrix package authors.

_R_e_f_e_r_e_n_c_e_s:

     Cheng, Sheung Hun and Higham, Nick (1998) A Modified Cholesky
     Algorithm Based on a Symmetric Indefinite Factorization; _SIAM J.
     Matrix Anal. Appl._, *19*, 1097-1110.

     Highham (2002) Computing the nearest correlation matrix - a
     problem from finance; _IMA Journal of Numerical Analysis_ *22*,
     329-343.

_S_e_e _A_l_s_o:

     More simple versions with a similar purpose by 'posdefify()'.

_E_x_a_m_p_l_e_s:

      set.seed(27)
      m <- matrix(round(rnorm(25),2), 5, 5)
      m <- m + t(m)
      diag(m) <- pmax(0, diag(m)) + 1
      (m <- round(cov2cor(m), 2))

      str(near.m <- nearPD(m))
      round(near.m$mat, 2)
      norm(m - near.m$mat) # 1.102

      if(require("sfsmisc")) {
         m2 <- posdefify(m) # a simpler approach
         norm(m - m2)  # 1.185, i.e., slightly "less near"
      }

