\HeaderA{simulate.lme}{simulate lme models}{simulate.lme}
\aliasA{plot.simulate.lme}{simulate.lme}{plot.simulate.lme}
\aliasA{print.simulate.lme}{simulate.lme}{print.simulate.lme}
\keyword{models}{simulate.lme}
\begin{Description}\relax
The model \code{m1} is fit to the data.  Using
the fitted values of the parameters, \code{nsim} new data vectors from
this model are simulated.  Both \code{m1} and \code{m2} are fit by
maximum likelihood (ML) and/or by restricted maximum likelihood (REML)
to each of the simulated data vectors.
\end{Description}
\begin{Usage}
\begin{verbatim}
simulate.lme(m1, m2, Random.seed, method, nsim, niterEM, useGen)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{m1}] an object inheriting from class \code{lme}, representing a fitted
linear mixed-effects model, or a list containing an lme model
specification.  If given as a list, it should contain
components \code{fixed}, \code{data}, and \code{random}
with values suitable for a call to \code{\LinkA{lme}{lme}}. This argument
defines the null model.

\item[\code{m2}] an \code{lme} object, or a list, like \code{m1} containing a second
lme model specification. This argument defines the alternative model.
If given as a list, only those parts of the specification that
change between model \code{m1} and \code{m2} need to be specified.

\item[\code{Random.seed}] an optional vector to seed the random number generator so as to
reproduce a simulation.  This vector should be the same form as the
\code{.Random.seed} object.

\item[\code{method}] an optional character array.  If it includes \code{"REML"} the models
are fit by maximizing the restricted log-likelihood. If it includes
\code{"ML"} the log-likelihood is maximized.  Defaults to
\code{c("REML", "ML")}, in which case both methods are used.

\item[\code{nsim}] an optional positive integer specifying the number of simulations to
perform.  Defaults to 1000.

\item[\code{niterEM}] an optional integer vector of length 2 giving the number of
iterations of the EM algorithm to apply when fitting the \code{m1}
and \code{m2} to each simulated set of data. Defaults to
\code{c(40,200)}. 

\item[\code{useGen}] an optional logical value. If \code{TRUE}, numerical derivatives are
used to obtain the gradient and the Hessian of the log-likelihood in
the optimization algorithm in the \code{ms} function. If
\code{FALSE}, the default algorithm in \code{ms} for functions that
do not incorporate gradient and Hessian attributes is used. Default
depends on the \code{pdMat} classes used in \code{m1} and \code{m2}:
if both are standard classes (see \code{\LinkA{pdClasses}{pdClasses}}) then
defaults to \code{TRUE}, otherwise defaults to \code{FALSE}.

\end{ldescription}
\end{Arguments}
\begin{Value}
an object of class \code{simulate.lme} with components \code{null} and
\code{alt}.  Each of these has components \code{ML} and/or \code{REML}
which are matrices.  An attribute called \code{Random.seed} contains
the seed that was used for the random number generator.
\end{Value}
\begin{Author}\relax
Jose Pinheiro \email{Jose.Pinheiro@pharma.novartis.com} and Douglas Bates \email{bates@stat.wisc.edu}
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{lme}{lme}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
orthSim <-
 simulate.lme(m1 = list(fixed = distance ~ age, data = Orthodont,
                        random = ~ 1 | Subject),
              m2 = list(random = ~ age | Subject))
## End(Not run)
\end{ExampleCode}
\end{Examples}

