icc                   package:aod                   R Documentation

_I_n_t_r_a-_C_l_u_s_t_e_r _C_o_r_r_e_l_a_t_i_o_n

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

     This function computes the intra-cluster correlation rho from
     clustered binomial data (n, y), using the ML/REML and ANOVA
     methods.

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

     icc(n, y, data, method = c("REML", "ML"), R = NULL)

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

       n: The denominator of the proportion.

       y: The numerator of the proportion.

    data: A data frame containing the data.

  method: A character string "ML" (maximum likelihood) or "REML"
          (restricted ML) used in the first estimation method for rho.
          Default to "REML".

       R: A scalar indicating the number of Monte Carlo (MC) replicates
          used to estimate the confidence interval of rho (ML/REML
          estimate). When R is NULL (the default value), the MC
          confidence interval is not computed.

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

     The function ungroups the clustered data into binary (0/1)
     observations y_{ij} (obs. j in cluster i).
      For the ML/REML method, a linear mixed-effect model is fitted:

                      y_{ij} = mu + u_i + e_{ij}

     where mu is the general mean, a_i is the random cluster effect and
     e_{ij} is the residual error. Model assumptions are: u ~ N(0,
     sigma_u^2) and  e_{ij} ~ N(0, sigma_e^2). The intra-cluster
     correlation is computed as

              rho = sigma_u^2 / (sigma_u^2 + sigma_e^2)

     Variance components sigma_u^2 and sigma_e^2 (actually, vector nu =
     log(sigma_u, sigma_e)) are  estimated with 'lme' (package 'nlme'):
     see Pinheiro and Bates, 2000. The variance of rho is estimated 
     with the _Delta_ method. An F test is provided to assess whether
     rho = 0 (actually, whether sigma_u^2 = 0: see Searle et al, 1992,
     p. 76). If the argument 'R' is not null, a MC confidence interval
     of rho is computed assuming that nu ~ N(nu, Var[nu]), where
     Var[nu] is the matrix 'apVar' provided in the 'lme' output.
      For the ANOVA method, see Donner (1989), Searle et al. (1992) or
     Zou and Donner (2004).
      The function assumes an homogeneous proportion p across the
     clusters.

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

     An object of formal class "icc", with 7 slots: 

    CALL: The call of the function.

     rho: A numeric vector with 2 components: REML (or ML) and ANOVA,
          containing the estimated values of rho according to these 2
          methods.

  varrho: A numeric scalar giving the approximate variance of rho
          (ML/REML estimate) estimated with the _Delta_ method.

       f: A numeric vector with the results of the F test.

  rho.MC: A numeric vector with the MC replicates of rho.

  method: A character string taking values "ML" or "REML".

features: A numeric vector with 3 components summarizing the main
          features of the data: 'N' = number  of clusters, 'n' = number
          of subjects, 'y' = number of cases.

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

     Matthieu Lesnoff matthieu.lesnoff@cirad.fr, Renaud Lancelot
     renaud.lancelot@cirad.fr

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

     Donner, A., 1989. _Statistical methods in ophthalmology: an
     adjusted chi-squared approach_. Biometrics 45, 605-611.
      Pinheiro, J.C., Bates, D.M., 2000. _Mixed-effects models in S and
     S-PLUS_. Springer-Verlag, New York.
      Searle, S.R., Casella, G., McCulloch, C.E., 1992. _Variance
     components_. Wiley, New York.
      Zou, G., Donner, A., 2004. _Confidence interval estimation of the
     intraclass correlation coefficient for  binary outcome data_.
     Biometrics 60, 807-811.

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

     'icc-class', 'lme'
      'icc' in the contributed packages 'irr' and 'psy'.

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

       data(rats)
       icc(n, y, rats[rats$group == "CTRL", ])
       res <- icc(n, y, rats[rats$group == "TREAT", ], R = 5000)
       res
       hist(res@rho.MC)
       by(rats,
          list(group = rats$group),
          function(x) icc(n, y, data = x))
       

