\Header{lmeControl}{Control Values for lme Fit}
\keyword{models}{lmeControl}
\begin{Description}\relax
The values supplied in the function call replace the defaults and a
list with all possible arguments is returned. The returned list is
used as the \code{control} argument to the \code{lme} function.
\end{Description}
\begin{Usage}
\begin{verbatim}
lmeControl(maxIter, msMaxIter, tolerance, niterEM, msTol,
           msScale, msVerbose, returnObject, gradHess, apVar,
           .relStep, minAbsParApVar, nlmStepMax, natural)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{maxIter}] maximum number of iterations for the \code{lme}
optimization algorithm. Default is 50.
\item[\code{msMaxIter}] maximum number of iterations
for the \code{nlm} optimization step inside the \code{lme}
optimization. Default is 50.
\item[\code{tolerance}] tolerance for the convergence criterion in the
\code{lme} algorithm. Default is 1e-6.
\item[\code{niterEM}] number of iterations for the EM algorithm used to refine
the initial estimates of the random effects variance-covariance
coefficients. Default is 25.
\item[\code{msTol}] tolerance for the convergence criterion in \code{nlm},
passed as the \code{rel.tolerance} argument to the function (see
documentation on \code{nlm}). Default is 1e-7. 
\item[\code{msScale}] scale function passed as the \code{scale} argument to
the \code{nlm} function (see documentation on that function). Default
is \code{lmeScale}.
\item[\code{msVerbose}] a logical value passed as the \code{trace} argument to
\code{nlm} (see documentation on that function). Default is
\code{FALSE}.
\item[\code{returnObject}] a logical value indicating whether the fitted
object should be returned when the maximum number of iterations is
reached without convergence of the algorithm. Default is
\code{FALSE}.
\item[\code{gradHess}] a logical value indicating whether numerical gradient
vectors and Hessian matrices of the log-likelihood function should
be used in the \code{nlm} optimization. This option is only available
when the correlation structure (\code{corStruct}) and the variance
function structure (\code{varFunc}) have no "varying" parameters and
the \code{pdMat} classes used in the random effects structure are
\code{pdSymm} (general positive-definite), \code{pdDiag} (diagonal),
\code{pdIdent} (multiple of the identity),  or
\code{pdCompSymm} (compound symmetry). Default is \code{TRUE}.
\item[\code{apVar}] a logical value indicating whether the approximate
covariance matrix of the variance-covariance parameters should be
calculated. Default is \code{TRUE}.
\item[\code{.relStep}] relative step for numerical derivatives
calculations. Default is \code{.Machine\$double.eps\textasciicircum{}(1/3)}.
\item[\code{minAbsParApVar}] numeric value - minimum absolute parameter value
in the approximate variance calculation.  The default is \code{0.05}.
\item[\code{nlmStepMax}] stepmax value to be passed to nlm. See
\code{\Link{nlm}} for details. Default is 100.0
\item[\code{natural}] a logical value indicating whether the \code{pdNatural}
parametrization should be used for general positive-definite matrices
(\code{pdSymm}) in \code{reStruct}, when the approximate covariance
matrix of the estimators is calculated. Default is \code{TRUE}.
\end{ldescription}
\end{Arguments}
\begin{Value}
a list with components for each of the possible arguments.
\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{\Link{lme}}, \code{\Link{nlm}}, \code{\Link{optim}},
\code{\Link{lmeScale}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# decrease the maximum number iterations in the ms call and
# request that information on the evolution of the ms iterations be printed
lmeControl(msMaxIter = 20, msVerbose = TRUE)
\end{ExampleCode}
\end{Examples}

