- 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<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. 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 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`

. (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