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, further restart_edge, etc;

• model- or data-checking 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 = 1e-5,
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 = 2e-3, relTol = NULL),
check.conv.singular = .makeCC(action = "message", tol = formals(isSingular)$tol), check.conv.hess = .makeCC(action = "warning", tol = 1e-6), ## optimizer args optCtrl = list(), mod.type = "lmer" ) glmerControl(optimizer = c("bobyqa", "Nelder_Mead"), restart_edge = FALSE, boundary.tol = 1e-5, 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 = 2e-3, relTol = NULL), check.conv.singular = .makeCC(action = "message", tol = formals(isSingular)$tol),
check.conv.hess     = .makeCC(action = "warning", tol = 1e-6),
## optimizer args
optCtrl = list(),
mod.type = "glmer",
compDev = TRUE,
nAGQ0initStep = TRUE,
check.response.not.const = "stop"
)

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). Built-in 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 (best-fit parameters), fval (best-fit 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 L-BFGS-B 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 bug-compatibility" option; use TRUE only when trying to match previous results. sparseX logical - should a sparse model matrix be used for the fixed-effects terms? Currently inactive. restart_edge logical - should the optimizer attempt a restart when it finds a solution at the boundary (i.e. zero random-effect 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.) tolPwrss numeric scalar - the tolerance for declaring convergence in the penalized iteratively weighted residual sum-of-squares 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 fixed-effect 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

### Details

Note that (only!) the pre-fitting “checking options” (i.e., all those starting with "check." but not including the convergence checks ("check.conv.*") or rank-checking ("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

1. general control parameters, such as optimizer, restart_edge;

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

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

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 - 2019-02) ...
fm1_bobyqa <- update(fm1, control = lmerControl(optimizer="bobyqa"))
## or with "Nelder_Mead" (the default till 2013) ...
## 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="L-BFGS-B".
}

## 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")
`