Learn R Programming

lme4 (version 1.1-7)

lmerControl: 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 importantlyoptimizer, furtherrestart_edge, etc;
  • model- or data-checking specifications, in shortchecking options, such ascheck.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 theoptCtrllist argument.

Usage

lmerControl(optimizer = "bobyqa",    restart_edge = TRUE,
    boundary.tol = 1e-5,
    calc.derivs=TRUE,
    use.last.params=FALSE,
    sparseX = 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 = "ignore",  tol = 1e-4),
    check.conv.hess     = .makeCC(action = "warning", tol = 1e-6),
    ## optimizer args
    optCtrl = list())

glmerControl(optimizer = c("bobyqa", "Nelder_Mead"), restart_edge = FALSE, boundary.tol = 1e-5, calc.derivs=TRUE, use.last.params=FALSE, sparseX = FALSE, tolPwrss=1e-7, compDev=TRUE, ## 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 = "warning", check.formula.LHS = "stop", ## convergence checking options check.conv.grad = .makeCC("warning", tol = 1e-3, relTol = NULL), check.conv.singular = .makeCC(action = "ignore", tol = 1e-4), check.conv.hess = .makeCC(action = "warning", tol = 1e-6), ## optimizer args optCtrl = list())

nlmerControl(optimizer = "Nelder_Mead", tolPwrss = 1e-10, 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). The built-in optimizers are
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
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?
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, wi
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<
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 random-effects levels for each term, usually necessary for identifiable variances. As for check.nobs.vs.nle
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.
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. So
check.scaleX
character - check for problematic scaling of columns of fixed-effect model matrix, e.g. parameters measured on very different scales.
check.formula.LHS
check whether specified formula has a left-hand side. Primarily for internal use within simulate.merMod; use at your own risk as it may allow the generation of unstable merMod objects
optCtrl
a list of additional arguments to be passed to the nonlinear optimizer (see Nelder_Mead, bobyqa
action
character - generic choices for the severity level of any test. "ignore": skip the test. "warning": warn if test fails. "stop": throw an error if test fails.
tol
numeric - tolerance for check
relTol
numeric - tolerance for checking relative variation
...
other elements to include in check specification

Value

  • The *Control functions return a list (inheriting from class "merControl") containing
    1. general control parameters, such asoptimizer,restart_edge;
    2. (currently not fornlmerControl:)"checkControl", alistof data-checking specifications, e.g.,check.nobs.vs.rankZ;
    3. parameters to be passed to the optimizer, i.e., theoptCtrllist, which may containmaxiter.

    .makeCC returns a list containing the check specification (action, tolerance, and optionally relative tolerance).

Troubleshooting

Some additional information about specific warnings and what to do about them:
  • Model failed to converge with max|grad| ...The scaled gradient at the fitted (RE)ML estimates is worryingly large. Try switching optimizers to see if you get consistent results, or compute values of the deviance in the neighbourhood of the estimated parameters to double-check thatlme4has really found a local optimum.
  • Model is nearly unidentifiable ... Rescale variables?The Hessian (curvature matrix) at the maximum likelihood or REML estimates has a large eigenvalue, indicating that the surface is nearly flat in some direction. Consider centering and/or scaling continuous predictor variables.

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.

Examples

Run this code
str(lmerControl())
str(glmerControl())
## fit with default Nelder-Mead algorithm ...
    fm0 <- lmer(Reaction ~ Days + (1 | Subject), sleepstudy)
    fm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
    ## or with minqa::bobyqa ...
    fm1_bobyqa <- update(fm1,control=lmerControl(optimizer="bobyqa"))
    ## or with the nlminb function used in older (<1.0) versions of lme4;
    ## this will usually replicate older results
    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 from the nloptr package.
    if (require(nloptr)) {
        defaultControl <- list(algorithm="NLOPT_LN_BOBYQA",
                               xtol_abs=1e-6,ftol_abs=1e-6,maxeval=1e5)
        nloptwrap <- function(fn,par,lower,upper,control=list(),...) {
            for (n in names(defaultControl))
                if (is.null(control[[n]])) control[[n]] <- defaultControl[[n]]
            res <- nloptr(x0=par,eval_f=fn,lb=lower,ub=upper,opts=control,...)
            with(res,list(par=solution,
                          fval=objective,
                          feval=iterations,
                          conv=if (status>0) 0 else status,
                          message=message))
        }
        fm1_nloptr <- update(fm1,control=lmerControl(optimizer="nloptwrap"))
        fm1_nloptr_NM <- update(fm1,control=lmerControl(optimizer="nloptwrap",
                                    optCtrl=list(algorithm="NLOPT_LN_NELDERMEAD")))
    }
    ## other algorithm options include NLOPT_LN_COBYLA, NLOPT_LN_SBPLX

Run the code above in your browser using DataLab