ep                package:mvtBinaryEP                R Documentation

_C_o_r_r_e_l_a_t_e_d _B_i_n_a_r_y _D_a_t_a

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

     Generates correlated binary data based on the method of Emrich and
     Piedmonte (1991)

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

     ep(mu, R, rho, n, isd = NULL, nRep = 1, seed = NULL, crit = 1e-06, maxiter = 20)

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

      mu: Vector of means.  If 'rho' is specified then 'mu' must be of
          length 1. 

       R: Correlation matrix. If 'rho' is specified then 'R' is
          ignored. Only the upper part of R is used. 

     rho: If common mean and exchangeable correlation is desired, then
          this correlation parameter must be specified. 

       n: Cluster size.  If 'rho' is specified, then this must be
          specified as well. 

     isd: Internal Simulation Descriptor. This is useful for generating
          more responses  based on the parameters used in the prior
          call to 'ep'.  This increases efficiency since the
          intermediate quantities need not be recomputed.  'isd' is  a
          *list* containing some of the input parameters as well as
          some intermediate quantities.  If this is provided then 'R'
          and 'rho' are ignored. 

    nRep: Number of clusters (replications). 

    seed: Sets the seed 

    crit: Level of precision used in solving for the tetra-choric
          correlations. 

 maxiter: Maximum number of iterations used in solving for the
          tetra-choric correlations. 

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

     The method relies on simulating multivariate normal vectors and
     then dichotomizing each  coordinate.  The cutpoints are determined
     by 'mu'.  The correlation matrix 'S'  (which are the tetra-choric
     correlations) of the multivariate normal vectors is computed in
     such a way that the resulting binary vectors have correlation
     matrix 'R'. One possible complication is that this process is not
     always possible.  Further, when all tetra-choric  correlations are
     computed, the resulting matrix, 'S', may not be positive definite.
      These are two possible failure points in the algorithm; both are
     detected and reported back by the code.

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

     Returns a list with the following two components: 

      y : Multivariate response of dimension 'nRep' by 'length(mu)'

    isd : Internal Simulation Descriptor 

_N_o_t_e:

     The returned object *isd* is also a list with the following
     fields:

   '_m_u'  input parameter 

   '_r_h_o'  input parameter 

   '_n'  input parameter 

   '_R'  input parameter 

   '_r_o_o_t_S'  The Cholesky root of the tetrachoric correlation matrix S
        (if positive definite) 

   '_S'  The tetrachoric correlation matrix S (if NOT positive definite) 

   '_p_d'  Flag, TRUE if S is positive definite, FALSE otherwise 

   '_s_p'  Flag, TRUE if successful in solving for tetrachoric
        correlations 

   '_i'  row where solving for the tetrachoric correlation failed, if it
        did fail 

   '_j'  column where solving for the tetrachoric correlation failed, if
        it did fail 

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

     See Also 'ranMVN', 'ranMVN2', 'ranMvnXch'

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

     # Create mean vector
     mu=c(0.5, 0.3, 0.20, 0.1)

     # Create correlation matrix
     R = c(
         1    , 0.2 , 0.15, -0.05,
         0.2  , 1   , 0.25, 0.2  , 
         0.15 , 0.25, 1   , 0.25 ,
         -0.05, 0.2 , 0.25, 1
     )
     R = matrix(R, ncol=4)

     ep0 = ep(mu=mu, R=R, nRep=1000, seed=NULL)
     apply(ep0$y, 2, mean); cor(ep0$y)

     #Generates more responses based on the parameters provided above.
     ep1 = ep(isd = ep0$isd, nRep=1000, seed=NULL)
     apply(ep1$y, 2, mean); cor(ep1$y)

     # 5-variate based on common mean and exchangeable correlation.
     ep2 = ep(mu=0.3, rho=0.2, n=5, nRep=10000)
     apply(ep2$y, 2, mean); cor(ep2$y)

