lmerControl {lme4}  R Documentation 
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
, furtherrestart_edge
, etc;model or datachecking specifications, in short “checking options”, such as
check.nobs.vs.rankZ
, orcheck.rankX
(currently not fornlmerControl
);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,
## input checking options
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",
## convergence checking options
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),
## optimizer args
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,
## input checking options
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",
## convergence checking options
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),
## optimizer args
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
Special provisions are made for For If 
calc.derivs 
logical  compute gradient and Hessian of nonlinear optimization solution? 
use.last.params 
logical  should the last value of the
parameters evaluated ( 
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

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.) 
tolPwrss 
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

check.nlev.gtreq.5 
character  rules for
checking whether all random effects have >= 5 levels.
See 
check.nlev.gtr.1 
character  rules for checking
whether all random effects have > 1 level. See 
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 
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 
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.conv.grad 
rules for checking the gradient of the deviance
function for convergence. A list as returned
by 
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.hess 
rules for checking the Hessian of the deviance
function for convergence.; as for 
check.rankX 
character  specifying if 
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

check.response.not.const 
character  check that the response is not constant. 
optCtrl 
a Note: All of 
action 
character  generic choices for the severity level of any test, with possible values

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"
, alist
of datachecking specifications, e.g.,check.nobs.vs.rankZ
;parameters to be passed to the optimizer, i.e., the
optCtrl
list, which may containmaxiter
.
.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())
## fit with default algorithm [nloptr version of BOBYQA] ...
fm0 < lmer(Reaction ~ Days + ( 1  Subject), sleepstudy)
fm1 < lmer(Reaction ~ Days + (Days  Subject), sleepstudy)
## or with "bobyqa" (default 2013  201902) ...
fm1_bobyqa < update(fm1, control = lmerControl(optimizer="bobyqa"))
## or with "Nelder_Mead" (the default till 2013) ...
fm1_NMead < update(fm1, control = lmerControl(optimizer="Nelder_Mead"))
## or with the nlminb function used in older (<1.0) versions of lme4;
## this will usually replicate older results
if (require(optimx)) {
fm1_nlminb < update(fm1,
control = lmerControl(optimizer= "optimx",
optCtrl = list(method="nlminb")))
## The other option here is method="LBFGSB".
}
## Or we can wrap base::optim():
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
## "Brent" requires finite upper values (lower bound will always
## be zero in this case)
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")))
## You can also use functions (in addition to the lmerControl() default "NLOPT_BOBYQA")
## from the 'nloptr' package, see also '?nloptwrap' :
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)))
}
## other algorithm options include NLOPT_LN_SBPLX