buildmerControl {buildmer}

Set control options for buildmer

Description

buildmerControl provides all the knobs and levers that can be manipulated during the buildmer fitting and summary/anova process. Some of these are part of buildmer's core functionality—for instance, crit allows to specify different elimination criteria, a core buildmer feature—whereas some are only meant for internal usage, e.g. I_KNOW_WHAT_I_AM_DOING is only used to turn off the PQL safeguards in buildbam/buildgam, which you really should only do if you have a very good reason to believe that the PQL check is being triggered erroneously for your problem.

Usage

buildmerControl(
  formula = quote(stop("No formula specified")),
  data = NULL,
  family = gaussian(),
  args = list(),
  direction = c("order", "backward"),
  cl = NULL,
  crit = NULL,
  elim = NULL,
  fit = function(...) stop("No fitting function specified"),
  include = NULL,
  quiet = FALSE,
  calc.anova = FALSE,
  calc.summary = TRUE,
  ddf = "Wald",
  quickstart = 0,
  singular.ok = FALSE,
  grad.tol = formals(buildmer::converged)$grad.tol,
  hess.tol = formals(buildmer::converged)$hess.tol,
  dep = NULL,
  REML = NA,
  can.use.reml = TRUE,
  force.reml = FALSE,
  scale.est = NA,
  I_KNOW_WHAT_I_AM_DOING = FALSE
)

Arguments

formula

The model formula for the maximal model you would like to fit. Alternatively, a buildmer term list as obtained from tabulate.formula. In the latter formulation, you also need to specify a dep='...' argument specifying the dependent variable to go along with the term list. See tabulate.formula for an example of where this is useful.

data

The data to fit the model(s) to.

family

The error distribution to use.

args

Extra arguments passed to the fitting function.

direction

Character string or vector indicating the direction for stepwise elimination; possible options are 'order' (order terms by their contribution to the model), 'backward' (backward elimination), 'forward' (forward elimination, implies order). The default is the combination c('order','backward'), to first make sure that the model converges and to then perform backward elimination; other such combinations are perfectly allowed.

cl

Specifies a cluster to use for parallelizing the evaluation of terms. This can be an object as returned by function makeCluster from package parallel, or a whole number to let buildmer create, manage, and destroy a cluster for you with the specified number of parallel processes.

crit

Character string or vector determining the criterion used to test terms for their contribution to the model fit in the ordering step. Possible options are 'LRT' (likelihood-ratio test based on chi-square mixtures per Stram & Lee 1994 for random effects; this is the default), 'LL' (use the raw -2 log likelihood), 'AIC' (Akaike Information Criterion), 'BIC' (Bayesian Information Criterion), and 'deviance' (explained deviance – note that this is not a formal test). If left at its default value of NULL, the same value is used as in the elim argument; if that is also NULL, both are set to 'LRT'. If crit is a function, it may optionally have an crit.name attribute, which will be used as its name in buildmer. This is used to guide the code checking for mismatches between crit and elim arguments.

elim

Character string or vector determining the criterion used to test terms for elimination in the elimination step. Possible options are 'LRT' (likelihood-ratio test based on chi-square mixtures per Stram & Lee 1994 for random effects; this is the default), 'LL' (use the raw -2 log likelihood), 'AIC' (Akaike Information Criterion), 'BIC' (Bayesian Information Criterion), and 'deviance' (explained deviance — note that this is not a formal test). If left at its default value of NULL, the same value is used as in the crit argument; if that is also NULL, both are set to 'LRT'. If elim is a function, it may optionally have an elim.name attribute, which will be used as its name in buildmer. This is used to guide the code checking for mismatches between crit and elim arguments.

fit

Internal parameter — do not modify.

include

A one-sided formula or character vector of terms that will be included in the model at all times and are not subject to testing for elimination. These do not need to be specified separately in the formula argument. Useful for e.g. passing correlation structures in glmmTMB models.

quiet

A logical indicating whether to suppress progress messages.

calc.anova

Logical indicating whether to also calculate the ANOVA table for the final model after term elimination.

calc.summary

Logical indicating whether to also calculate the summary table for the final model after term elimination.

ddf

The method used for calculating p-values for lme4 models and calc.anova=TRUE or calc.summary=TRUE. Options are 'Wald' (default), 'Satterthwaite' (if package lmerTest is available), 'Kenward-Roger' (if packages lmerTest and pbkrtest are available), and 'lme4' (no p-values).

quickstart

For gam models only: a numeric with values from 0 to 5. If set to 1, will use bam to obtain starting values for gam's outer iteration, potentially resulting in a much faster fit for each model. If set to 2, will disregard ML/REML and always use bam's fREML for the quickstart fit. 3 also sets discrete=TRUE. Values between 3 and 4 fit the quickstart model to a subset of that value (e.g.\ quickstart=3.1 fits the quickstart model to 10% of the data, which is also the default if quickstart=3. Values between 4 and 5 do the same, but also set a very sloppy convergence tolerance of 0.2.

singular.ok

Logical indicating whether singular fits are acceptable. Only for lme4 models.

grad.tol

Tolerance for declaring gradient convergence. For buildbam, the default value is multiplied by 100.

hess.tol

Tolerance for declaring Hessian convergence. For buildbam, the default value is multiplied by 100.

dep

A character string specifying the name of the dependent variable. Only used if formula is a buildmer terms list.

REML

In some situations, the user may want to force REML on or off, rather than using buildmer's autodetection. If REML=TRUE (or more precisely, if isTRUE(REML) evaluates to true), then buildmer will always use REML. This results in invalid results if formal model-comparison criteria are used with models differing in fixed effects (and the user is not guarded against this), but is useful with the 'deviance-explained' criterion, where it is actually the default (you can disable this and use the 'normal' REML/ML-differentiating behavior by passing REML=NA).

can.use.reml

Internal option specifying whether the fitting engine should distinguish between fixed-effects and random-effects model comparisons. Do not set this option yourself unless you are programming a new fitting function for buildcustom.

force.reml

Internal option specifying whether, if not differentiating between fixed-effects and random-effects model comparisons, these comparisons should be based on ML or on REML (if possible). Do not set this option yourself unless you are programming a new fitting function for buildcustom. Enabling this option only makes sense for criteria that do not compare likelihoods, in which case this is an optimization; it is applied automatically for the 'deviance-explained' criterion.

scale.est

Internal option specifying whether the model estimates an unknown scale parameter. Used only in crit.F. Possible values are TRUE (scale is estimated), FALSE (scale is known), and NA (unknown, needs to be inferred from the fitted model; this is the default). There is limited support for modifying this parameter.

I_KNOW_WHAT_I_AM_DOING

An internal option that you should not modify unless you know what you are doing.

Details

With the default options, all buildmer functions will do two things:

1. Determine the order of the effects in your model, based on their importance as measured by the likelihood-ratio test statistic. This identifies the ‘maximal model’, which is the model containing either all effects specified by the user, or subset of those effects that still allow the model to converge, ordered such that the most information-rich effects have made it in.

2. Perform backward stepwise elimination based on the significance of the change in log-likelihood.

The final model is returned in the model slot of the returned buildmer object. All functions in the buildmer package are aware of the distinction between (f)REML and ML, and know to divide chi-square p-values by 2 when comparing models differing only in random effects (see Pinheiro & Bates 2000). The steps executed above can be changed using the direction argument, allowing for arbitrary chains of, for instance, forward-backward-forward stepwise elimination (although using more than one elimination method on the same data is not recommended). The criterion for determining the importance of terms in the ordering stage and the elimination of terms in the elimination stage can also be changed, using the crit argument.