dwmw {trouBBlme4SolveR}

Solver for (generalized) linear MM warnings

Description

Updates a (possibly generalized) linear mixed model computed with the library lme4 functions lmer or glmer, in order to elude some singularity or convergence problems informed by distinct warnings or messages.

Usage

dwmw(lmmodel,
     boundary_check = TRUE, scale = FALSE, scale_info = TRUE,
     tol = 1e-4, max_message_iter = 7, max_nAGQ = 6,
     next_optimizer = "bobyqa", next_optCtrl = list(maxfun = 2e5),
     when_next = max_message_iter - 1, verbose = FALSE)

Arguments

lmmodel

The model of interest, output of either lmer or glmer, that is, an object of class merMod and subclass either lmerMod or glmerMod.

boundary_check

A length 1 boolean object (TRUE [default] or FALSE), determining if the function removes those random effects which make the model singular (in the simplest situation, those with standard deviation almost 0.

scale

A length 1 boolean object (TRUE or FALSE [default]), determining if the function must rescale the numeric predictors when this action is asked in a warning or message.

scale_info

A length 1 boolean object (TRUE [default] or FALSE), determining if the function should cat a message when some predictor variables are on very different scales, but are not rescaled.

tol

A numeric value (default is 1e-4), tolerance under which to consider if a model is singular (see boundary_check argument).

max_message_iter

A numeric value (default is 7), generally the maximum number of iterations allowed to update the model. For the exception, see the Details section.

max_nAGQ

A numeric value (default is 6), maximum to which increase the nAGQ argument fitting glmer models.

next_optimizer

An optimizer (default is "bobyqa"), next to be used when model convergence is failing.

next_optCtrl

A list (default is list(maxfun=2e5)) 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.

when_next

A numeric value not greater than max_message_iter - 1 (which is the default), specifying from which iteration a model convergence failing is approached with a new optimizer (next_optimizer) and with a new set of arguments to it (next_optCtrl).

verbose

A length 1 boolean object (TRUE or FALSE [default])

specifying if function iterations and model updating should be verbose.

Details

If the model does not generate any warning or message, dwmw returns itself. The function rescales numeric predictors if some warning or message suggests it and the scale argument is TRUE. If the model fails to converge, it only updates the starting values for the parameters in the model through the first when_next - 1 iterations, while it also updates the optimizer and their arguments through the next iterations.

If the model is singular (there is a "boundary (singular)"-alike message) and boundary_check is TRUE, the formula is updated removing the random effects which cause the model to be singular. If all the random effects are removed, a linear or generalized linear model is computed according to the lmmodel object.

If the model has subclass glmerMod, a single scalar random effect and converges but it is nearly unidentifiable with a very large eigenvalue, then nAGQ is increased one unity while nAGQ <= max_nAGQ (and only in this case, allowing the iterations to exceed max_message_iter until nAGQ == max_nAGQ).

Value

Generally, an object of class merMod, being either an object of subclass glmerMod or an object of subclass lmerMod, corresponding to the input lmmodel argument. When all random effects are removed, an object of class glm or lm depending also on the input lmmodel.

Author(s)

Iago Giné-Vázquez, [e-mail]

See Also

lmer, glmer, merMod lmerControl, convergence, troubleshooting, isSingular, lm and glm.

Examples

if(requireNamespace("nlme")){
	library(lme4)
	data(Orthodont, package = "nlme")
	Orthodont$nsex <- as.numeric(Orthodont$Sex == "Male")
	Orthodont$nsexage <- with(Orthodont, nsex*age)
	## Without using dwmw, the next model is singular
	fmo <- lmer(distance ~ age + (age|Subject) + (0+nsex|Subject) +
		    (0 + nsexage|Subject), data = Orthodont)
	summary(fmo)

	## Using dwmw, we remove the singularity of the model
	fmo1 <- dwmw(lmer(distance ~ age + (age|Subject) + (0+nsex|Subject) +
			  (0 + nsexage|Subject), data = Orthodont))
	summary(fmo1)

	## It also can be used on the output object

	fmo2 <- dwmw(fmo)
	summary(fmo2)
}