Control parameters for glmmTMB optimization

Usage

glmmTMBControl(
  optCtrl = NULL,
  optArgs = list(),
  optimizer = nlminb,
  profile = FALSE,
  collect = FALSE,
  parallel = list(n = getOption("glmmTMB.cores", 1L), autopar =
    getOption("glmmTMB.autopar", get_autopar())),
  eigval_check = TRUE,
  zerodisp_val = log(.Machine$double.eps)/4,
  start_method = list(method = NULL, jitter.sd = 0),
  rank_check = c("adjust", "warning", "stop", "skip"),
  conv_check = c("warning", "skip"),
  full_cor = TRUE
)

Arguments

optCtrl: Passed as argument control to optimizer. Default value (if default nlminb optimizer is used): list(iter.max=300, eval.max=400)
optArgs: additional arguments to be passed to optimizer function (e.g.: list(method="BFGS") when optimizer=optim)
optimizer: Function to use in model fitting. See Details for required properties of this function.
profile: (logical) Experimental option to improve speed and robustness when a model has many fixed effects
collect: (logical) Experimental option to improve speed by recognizing duplicated observations.
parallel: (named list with an integer value n and a logical value autopar, e.g. list(n=4L, autopar=TRUE)) Set number of OpenMP threads to evaluate the negative log-likelihood in parallel, and determine whether to use auto-parallelization (see openmp). The default is to evaluate models serially (i.e. single-threaded); users can set default values for an R session via options(glmmTMB.cores=<value>, glmmTMB.autopar=<value>). An integer number of cores (only) can be passed instead of a list, in which case the default or previously set value of autopar will be used. At present reduced-rank models (i.e., a covariance structure using rr(...)) cannot be fitted in parallel unless autopar=TRUE; the number of threads will be automatically set to 1, with a warning if this overrides the user-specified value. To trace OpenMP settings, use options(glmmTMB_openmp_debug = TRUE).
eigval_check: Check eigenvalues of variance-covariance matrix? (This test may be very slow for models with large numbers of fixed-effect parameters.)
zerodisp_val: value of the dispersion parameter when dispformula=~0 is specified
start_method: (list) Options to initialize the starting values when fitting models with reduced-rank (rr) covariance structures; jitter.sd adds variation to the starting values of latent variables when method = "res".
rank_check: Check whether all parameters in fixed-effects models are identifiable? This test may be slow for models with large numbers of fixed-effect parameters, therefore default value is 'warning'. Alternatives include 'skip' (no check), 'stop' (throw an error), and 'adjust' (drop redundant columns from the fixed-effect model matrix).
conv_check: Do basic checks of convergence (check for non-positive definite Hessian and non-zero convergence code from optimizer). Default is 'warning'; 'skip' ignores these tests (not recommended for general use!)
full_cor: compute full correlation matrices? can be either a length-1 logical vector (TRUE/FALSE) to include full correlation matrices for all or none of the random-effect terms in the model, or a logical vector with length equal to the number of correlation matrices, to include/exclude correlation matrices individually

Details

By default, glmmTMB uses the nonlinear optimizer nlminb for parameter estimation. Users may sometimes need to adjust optimizer settings in order to get models to converge. For instance, the warning ‘iteration limit reached without convergence’ may be fixed by increasing the number of iterations using (e.g.)

glmmTMBControl(optCtrl=list(iter.max=1e3,eval.max=1e3)).

Setting profile=TRUE allows glmmTMB to use some special properties of the optimization problem in order to speed up estimation in cases with many fixed effects.

Control parameters may depend on the model specification. The value of the controls is evaluated inside an R object that is derived from the output of the mkTMBStruc function. For example, to specify that profile should be enabled if the model has more than 5 fixed-effect parameters, specify

profile=quote(length(parameters$beta)>=5)

The optimizer argument can be any optimization (minimizing) function, provided that:

the first three arguments, in order, are the starting values, objective function, and gradient function;
the function also takes a control argument;
the function returns a list with elements (at least) par, objective, convergence (0 if convergence is successful) and message (glmmTMB automatically handles output from optim(), by renaming the value component to objective)

Examples

## fit with default (nlminb) and alternative (optim/BFGS) optimizer
m1 <- glmmTMB(count~ mined, family=poisson, data=Salamanders)
m1B <- update(m1, control=glmmTMBControl(optimizer=optim,
               optArgs=list(method="BFGS")))
## estimates are *nearly* identical:
all.equal(fixef(m1), fixef(m1B))
#> [1] "Component “cond”: Mean relative difference: 2.66761e-06"