##### https://github.com/cran/mvtBinaryEP
Tip revision: bd876c4
ep.Rd
\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 }
}
}

\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 }