\name{ep}
\alias{ep}
\title{ Correlated Binary Data }
\description{
  Generates correlated binary data based on the method of Emrich and Piedmonte (1991)
}
\usage{
ep(mu, R, rho, n, isd = NULL, nRep = 1, seed = NULL, crit = 1e-06,
maxiter = 20)
}

\arguments{
  \item{mu}{ Vector of means.  If \code{rho} is specified then \code{mu} must be of length 1. }
  \item{R}{ Correlation matrix. If \code{rho} is specified then \code{R} is ignored. Only the
            upper part of R is used. }
  \item{rho}{ If common mean and exchangeable correlation is desired, then this correlation parameter must
              be specified. }
  \item{n}{ Cluster size.  If \code{rho} is specified, then this must be specified as well. }
  \item{isd}{ Internal Simulation Descriptor. This is useful for generating more responses 
              based on the parameters used in the prior call to \code{ep}.  This increases
              efficiency since the intermediate quantities need not be recomputed.  \code{isd} is 
              a \bold{list} containing some of the input parameters as well as some intermediate
              quantities.  If this is provided then \code{R} and \code{rho} are ignored. }
  \item{nRep}{ Number of clusters (replications). }
  \item{seed}{ Sets the seed }
  \item{crit}{ Level of precision used in solving for the tetra-choric correlations. }
  \item{maxiter}{ Maximum number of iterations used in solving for the tetra-choric correlations. }
}

\details{ The method relies on simulating multivariate normal vectors and then dichotomizing each 
          coordinate.  The cutpoints are determined by \code{mu}.  The correlation matrix \code{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 \code{R}. One possible
          complication is that this process is not always possible.  Further, when all tetra-choric 
          correlations are computed, the resulting matrix, \code{S}, may not be positive definite.  These
          are two possible failure points in the algorithm; both are detected and reported back by the code.  
}

\value{
  Returns a list with the following two components:
  \item{y }{ Multivariate response of dimension \code{nRep} by \code{length(mu)}}
  \item{isd }{ Internal Simulation Descriptor }
}

\note{ The returned object \bold{isd} is also a list with the following fields:
    \itemize{
    \item{\code{mu} }{ input parameter }
    \item{\code{rho} }{ input parameter }
    \item{\code{n} }{ input parameter }
    \item{\code{R} }{ input parameter }
    \item{\code{rootS} }{ The Cholesky root of the tetrachoric correlation matrix S (if positive definite) }
    \item{\code{S} }{ The tetrachoric correlation matrix S (if NOT positive definite) }
    \item{\code{pd} }{ Flag, TRUE if S is positive definite, FALSE otherwise }
    \item{\code{sp} }{ Flag, TRUE if successful in solving for tetrachoric correlations }
    \item{\code{i} }{ row where solving for the tetrachoric correlation failed, if it did fail }
    \item{\code{j} }{ column where solving for the tetrachoric correlation failed, if it did fail }
    }
}

\seealso{ See Also \code{\link{ranMVN}}, \code{\link{ranMVN2}}, \code{\link{ranMvnXch}} }

\examples{

# 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)

}

% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ datagen }
\keyword{ distribution }
\keyword{ multivariate }