Control of Mixed Model Fitting
Description
Construct control structures for mixed model fitting. All arguments
have defaults, and can be grouped into

general control parameters, most importantly optimizer
,
further restart_edge
, etc;

model or datachecking specifications, in short
“checking options”, such as check.nobs.vs.rankZ
, or
check.rankX
(currently not for nlmerControl
);

all the parameters to be passed to the optimizer, e.g.,
maximal number of iterations, passed via the optCtrl
list
argument.
Usage
lmerControl(optimizer = "nloptwrap",
restart_edge = TRUE,
boundary.tol = 1e5,
calc.derivs = TRUE,
use.last.params = FALSE,
sparseX = FALSE,
standardize.X = FALSE,
check.nobs.vs.rankZ = "ignore",
check.nobs.vs.nlev = "stop",
check.nlev.gtreq.5 = "ignore",
check.nlev.gtr.1 = "stop",
check.nobs.vs.nRE= "stop",
check.rankX = c("message+drop.cols", "silent.drop.cols", "warn+drop.cols",
"stop.deficient", "ignore"),
check.scaleX = c("warning","stop","silent.rescale",
"message+rescale","warn+rescale","ignore"),
check.formula.LHS = "stop",
check.conv.grad = .makeCC("warning", tol = 2e3, relTol = NULL),
check.conv.singular = .makeCC(action = "message", tol = formals(isSingular)$tol),
check.conv.hess = .makeCC(action = "warning", tol = 1e6),
optCtrl = list(),
mod.type = "lmer"
)
glmerControl(optimizer = c("bobyqa", "Nelder_Mead"),
restart_edge = FALSE,
boundary.tol = 1e5,
calc.derivs = TRUE,
use.last.params = FALSE,
sparseX = FALSE,
standardize.X = FALSE,
check.nobs.vs.rankZ = "ignore",
check.nobs.vs.nlev = "stop",
check.nlev.gtreq.5 = "ignore",
check.nlev.gtr.1 = "stop",
check.nobs.vs.nRE= "stop",
check.rankX = c("message+drop.cols", "silent.drop.cols", "warn+drop.cols",
"stop.deficient", "ignore"),
check.scaleX = c("warning","stop","silent.rescale",
"message+rescale","warn+rescale","ignore"),
check.formula.LHS = "stop",
check.conv.grad = .makeCC("warning", tol = 2e3, relTol = NULL),
check.conv.singular = .makeCC(action = "message", tol = formals(isSingular)$tol),
check.conv.hess = .makeCC(action = "warning", tol = 1e6),
optCtrl = list(),
mod.type = "glmer",
tolPwrss = 1e7,
compDev = TRUE,
nAGQ0initStep = TRUE,
check.response.not.const = "stop"
)
nlmerControl(optimizer = "Nelder_Mead", tolPwrss = 1e10,
optCtrl = list())
.makeCC(action, tol, relTol, ...)
Arguments
optimizer 
character  name of optimizing function(s). A
character vector or list of functions: length 1 for
lmer or glmer , possibly length 2 for glmer ).
Builtin optimizers are "Nelder_Mead" ,
"bobyqa" (from the minqa package),
"nlminbwrap" (using base R's nlminb ) and the
default for lmerControl() , "nloptwrap" . Any
minimizing function that allows box constraints can be used provided
that it
 (1)

takes input parameters fn (function to be
optimized), par (starting parameter values), lower
and upper (parameter bounds)
and control (control parameters, passed
through from the control argument) and
 (2)

returns a list with (at least) elements par
(bestfit parameters), fval (bestfit function value),
conv (convergence code, equal to zero for
successful convergence) and (optionally) message
(informational message, or explanation of convergence failure).
Special provisions are made for bobyqa ,
Nelder_Mead , and optimizers wrapped in the
optimx package; to use the optimx optimizers (including
LBFGSB from base optim and
nlminb ), pass the method argument to
optim in the optCtrl argument (you may
need to load the optimx package manually using
library(optimx) ).
For glmer , if length(optimizer)==2 , the first element
will be used for the preliminary (random effects parameters only)
optimization, while the second will be used for the final (random
effects plus fixed effect parameters) phase. See
modular for more information on these two phases.
If optimizer is NULL (at present for lmer only),
all of the model structures will be set up, but no optimization will
be done (e.g. parameters will all be returned as NA ).

calc.derivs 
logical  compute gradient and Hessian of nonlinear
optimization solution?

use.last.params 
logical  should the last value of the
parameters evaluated (TRUE ), rather than the value of the
parameters corresponding to the minimum deviance, be returned?
This is a "backward bugcompatibility" option; use TRUE
only when trying to match previous results.

sparseX 
logical  should a sparse model matrix be
used for the fixedeffects terms?
Currently inactive.

restart_edge 
logical  should the optimizer
attempt a restart when it finds a solution at the
boundary (i.e. zero randomeffect variances or perfect
+/1 correlations)? (Currently only implemented for
lmerControl .)

boundary.tol 
numeric  within what distance of
a boundary should the boundary be checked for a better fit?
(Set to zero to disable boundary checking.)


numeric scalar  the tolerance for declaring
convergence in the penalized iteratively weighted residual
sumofsquares step.

compDev 
logical scalar  should compiled code be
used for the deviance evaluation during the optimization
of the parameter estimates?

nAGQ0initStep 
Run an initial optimization phase with
nAGQ = 0 . While the initial optimization usually
provides a good starting point for subsequent fitting
(thus increasing overall computational speed),
setting this option to FALSE can be useful in cases
where the initial phase results in bad fixedeffect estimates
(seen most often in binomial models with link="cloglog"
and offsets).

check.nlev.gtreq.5 
character  rules for
checking whether all random effects have >= 5 levels.
See action .

check.nlev.gtr.1 
character  rules for checking
whether all random effects have > 1 level. See action .

check.nobs.vs.rankZ 
character  rules for
checking whether the number of observations is greater
than (or greater than or equal to) the rank of the random
effects design matrix (Z), usually necessary for
identifiable variances. As for action , with
the addition of "warningSmall" and "stopSmall" , which run
the test only if the dimensions of Z are < 1e6.
nobs > rank(Z) will be tested for LMMs and GLMMs with
estimated scale parameters; nobs >= rank(Z) will be tested
for GLMMs with fixed scale parameter.
The rank test is done using the
method="qr" option of the rankMatrix
function.

check.nobs.vs.nlev 
character  rules for checking whether the
number of observations is less than (or less than or equal to) the
number of levels of every grouping factor, usually necessary for
identifiable variances. As for action .
nobs<nlevels will be tested for LMMs and GLMMs with estimated
scale parameters; nobs<=nlevels will be tested for GLMMs with
fixed scale parameter.

check.nobs.vs.nRE 
character  rules for
checking whether the number of observations is greater
than (or greater than or equal to) the number of randomeffects
levels for each term, usually necessary for identifiable variances.
As for check.nobs.vs.nlev .

check.conv.grad 
rules for checking the gradient of the deviance
function for convergence. A list as returned
by .makeCC , or a character string with only the action.

check.conv.singular 
rules for checking for a singular fit,
i.e. one where some parameters are on the boundary of the feasible
space (for example, random effects variances equal to 0 or
correlations between random effects equal to +/ 1.0);
as for check.conv.grad above. The default is to use
isSingular(.., tol = *) 's default.

check.conv.hess 
rules for checking the Hessian of the deviance
function for convergence.; as for check.conv.grad
above.

check.rankX 
character  specifying if rankMatrix(X)
should be compared with ncol(X) and if columns from the design
matrix should possibly be dropped to ensure that it has full rank.
Sometimes needed to make the model identifiable. The options can be
abbreviated; the three "*.drop.cols" options all do drop
columns, "stop.deficient" gives an error when the rank is
smaller than the number of columns where "ignore" does no
rank computation, and will typically lead to less easily
understandable errors, later.

check.scaleX 
character  check for problematic scaling of
columns of fixedeffect model matrix, e.g. parameters measured on
very different scales.

check.formula.LHS 
check whether specified formula has
a lefthand side. Primarily for internal use within
simulate.merMod ;
use at your own risk as it may allow the generation
of unstable merMod objects

check.response.not.const 
character  check that the
response is not constant.

optCtrl 
a list of additional arguments to be
passed to the nonlinear optimizer (see Nelder_Mead ,
bobyqa ). In particular, both
Nelder_Mead and bobyqa use maxfun to
specify the maximum number of function evaluations they
will try before giving up  in contrast to
optim and optimx wrapped optimizers,
which use maxit . (Also see convergence
for details of stopping tolerances for different optimizers.)
Note: All of lmer() , glmer() and
nlmer() have an optional integer argument verbose
which you should raise (to a positive value) in order to get diagnostic
console output about the optimization progress.

action 
character  generic choices for the severity level
of any test, with possible values
 "ignore":

skip the test.
 "warning":

warn if test fails.
 "message":

print a message if test fails.
 "stop":

throw an error if test fails.

tol 
(numeric) tolerance for checking the gradient, scaled
relative to the curvature (i.e., testing the gradient on a scale
defined by its Wald standard deviation)

relTol 
(numeric) tolerance for the gradient, scaled
relative to the magnitude of the estimated coefficient

mod.type 
model type (for internal use)

standardize.X 
scale columns of X matrix? (not yet implemented)

... 
other elements to include in check specification

Details
Note that (only!) the prefitting “checking options”
(i.e., all those starting with "check."
but not
including the convergence checks ("check.conv.*"
) or
rankchecking ("check.rank*"
) options)
may also be set globally via options
.
In that case, (g)lmerControl
will use them rather than the
default values, but will not override values that are passed as
explicit arguments.
For example, options(lmerControl=list(check.nobs.vs.rankZ = "ignore"))
will suppress warnings that the number of observations is less than
the rank of the random effects model matrix Z
.
Value
The *Control
functions return a list (inheriting from class
"merControl"
) containing

general control parameters, such as optimizer
, restart_edge
;

(currently not for nlmerControl
:)
"checkControl"
, a list
of datachecking
specifications, e.g., check.nobs.vs.rankZ
;

parameters to be passed to the optimizer, i.e., the optCtrl
list, which may contain maxiter
.
.makeCC
returns a list containing the check specification
(action, tolerance, and optionally relative tolerance).
See Also
convergence and allFit()
which fits
for a couple of optimizers;
nloptwrap
for the lmerControl()
default optimizer.
Examples
str(lmerControl())
str(glmerControl())
fm0 < lmer(Reaction ~ Days + ( 1  Subject), sleepstudy)
fm1 < lmer(Reaction ~ Days + (Days  Subject), sleepstudy)
fm1_bobyqa < update(fm1, control = lmerControl(optimizer="bobyqa"))
fm1_NMead < update(fm1, control = lmerControl(optimizer="Nelder_Mead"))
if (require(optimx)) {
fm1_nlminb < update(fm1,
control = lmerControl(optimizer= "optimx",
optCtrl = list(method="nlminb")))
}
optimwrap < function(fn,par,lower,upper,control=list(),
...) {
if (is.null(control$method)) stop("must specify method in optCtrl")
method < control$method
control$method < NULL
if (method=="Brent") upper < pmin(1e4,upper)
res < optim(par=par, fn=fn, lower=lower,upper=upper,
control=control,method=method,...)
with(res, list(par = par,
fval = value,
feval= counts[1],
conv = convergence,
message = message))
}
fm0_brent < update(fm0,
control = lmerControl(optimizer = "optimwrap",
optCtrl = list(method="Brent")))
if (require(nloptr)) {
fm1_nloptr_NM < update(fm1, control=lmerControl(optimizer="nloptwrap",
optCtrl=list(algorithm="NLOPT_LN_NELDERMEAD")))
fm1_nloptr_COBYLA < update(fm1, control=lmerControl(optimizer="nloptwrap",
optCtrl=list(algorithm="NLOPT_LN_COBYLA",
xtol_rel=1e6,
xtol_abs=1e10,
ftol_abs=1e10)))
}