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 = "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,
        nAGQ0initStep=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",
        check.response.not.const = "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 `Nelder_Mead` and `bobyqa` (from the minqa package). 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` (lower 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 also need to load the `optimx` package manually using `library(optimx)` or `require(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.
`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` | do one initial run with `nAGQ = 0`.
`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 random-effects 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.
`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 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
`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`.
`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

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

### See Also

convergence

### Examples

    str(lmerControl())
    str(glmerControl())
    ## Not run:
        ## fit with default "bobyqa" algorithm ...
        fm0 <- lmer(Reaction ~ Days +   ( 1 | Subject), sleepstudy)
        fm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
        ## or with "Nelder_Mead" (the previous default) ...
        fm1_bobyqa <- 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
        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

    ## End(Not run)

[Package lme4 version 1.1-12 Index]