metrics               package:monomvn               R Documentation

_R_M_S_E, _E_x_p_e_c_t_e_d _L_o_g _L_i_k_e_l_i_h_o_o_d _a_n_d _K_L _D_i_v_e_r_g_e_n_c_e _B_e_t_w_e_e_n
_T_w_o _M_u_l_t_i_v_a_r_i_a_t_e _N_o_r_m_a_l _D_i_s_t_r_i_b_u_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     These functions calculate the root-mean-squared-error, the
     expected log likelihood, and Kullback-Leibler (KL) divergence
     (a.k.a. distance), between two multivariate normal (MVN)
     distributions described by their mean vector and covariance matrix

_U_s_a_g_e:

     rmse.muS(mu1, S1, mu2, S2)
     Ellik.norm(mu1, S1, mu2, S2, quiet=FALSE)
     kl.norm(mu1, S1, mu2, S2, quiet=FALSE, symm=FALSE)

_A_r_g_u_m_e_n_t_s:

     mu1: mean vector of first (estimated) MVN 

      S1: covariance matrix of first (estimated) MVN 

     mu2: mean vector of second (true, baseline, or comparator) MVN 

      S2: covariance matrix of second (true, baseline, or comparator)
          MVN 

   quiet: when 'FALSE' (default), gives a warning if the 'accuracy'
          package cannot be loaded to deal with (possibly) non-positive
          definite 'S1' and 'S2'

    symm: when 'TRUE' a symmetrized version of the KL divergence is
          used; see the note below 

_D_e_t_a_i_l_s:

     The root-mean-squared-error is calculated between the entries of
     the mean vectors, and the upper-triangular part of the covariance
     matrices (including the diagonal).

     The KL divergence is given by the formula:

 0.5 (log(|S1|/|S2|) + tr(inv(S1)S2) + t(mu1-m2)inv(S2)(mu1-mu2) - N)


     where N is 'length(mu1)', and must agree with the dimensions of
     the other parameters.

     The expected log likelihood can be formulated in terms of the KL
     divergence.  That is, the expected log likelihood of data
     simulated from the normal distribution with parameters 'mu2' and
     'S2' under the estimated normal with parameters 'mu1' and 'S1' is
     given by


        -0.5 ln((2 pi e)^N |S2|) - kl.norm(mu1, S1, mu2, S2).


     The 'sechol' function from the 'accuracy' package is used to
     decompose (possibly) non-positive definite 'S1' and/or 'S2' to
     give more stable and robust calculations in the face of numerical
     instabilities that might occur for larger problems

_V_a_l_u_e:

     In the case of the expected log likelihood the result is a real
     number.  The RMSE is a positive real number. The KL divergence
     method returns a positive real number depicting the _distance_
     between the two normal distributions

_N_o_t_e:

     The KL-divergence is not symmetric.  Therefore

     'kl.norm(mu1,S1,mu2,S2) != kl.norm(mu2,S2,mu1,S1).'

     But a symmetric metric can be constructed from

     '0.5 * (kl.norm(mu1,S1,mu2,S2) + kl.norm(mu2,S2,mu1,S1))'

     or by using 'symm = TRUE'

_A_u_t_h_o_r(_s):

     Robert B. Gramacy bobby@statslab.cam.ac.uk

_R_e_f_e_r_e_n_c_e_s:

     <URL: http://www.statslab.cam.ac.uk/~bobby/monomvn.html>

_S_e_e _A_l_s_o:

     'posdef.approx'

_E_x_a_m_p_l_e_s:

     mu1 <- rnorm(5)
     s1 <- matrix(rnorm(100), ncol=5)
     S1 <- t(s1) %*% s1

     mu2 <- rnorm(5)
     s2 <- matrix(rnorm(100), ncol=5)
     S2 <- t(s2) %*% s2

     ## RMSE
     rmse.muS(mu1, S1, mu2, S2)

     ## expected log likelihood
     Ellik.norm(mu1, S1, mu2, S2)

     ## KL is not symmetric
     kl.norm(mu1, S1, mu2, S2)
     kl.norm(mu2, S2, mu1, S1)

     ## symmetric version
     kl.norm(mu2, S2, mu1, S1, symm=TRUE)

