ffRanefLMER.fnc {LMERConvenienceFunctions}

Forward-fit the random effect structure of an LMER model.

Description

Forward-fit an LMER model's random effect structure by comparing a model without one of the specified random effects and a model with it by way of log-likelihood ratio testing. If the more complex model is a significantly better fit, the random effect is kept, otherwise it is dropped. This function can now be used with generalized linear mixed-effects models (glmers).

Usage

ffRanefLMER.fnc(model, ran.effects = list(ran.intercepts = 
as.character(), slopes = as.character(), corr = as.character(), 
by.vars = as.character()), alpha = 0.05, if.warn.not.add = TRUE, 
log.file = NULL)

Arguments

model

A mer object (fitted by function lmer). This function can now be used with generalized linear mixed-effects models (glmers).

ran.effects

Can be either a vector or a list. In the former case, the random effects to be evaluated are provided. For example c("(1 + Frequency | Subject)", "(0 + Length | Subject)", "(1 + NSynSet | Subject)"). In the latter case, the list can be composed of (i) a vector of random intercepts to be evaluated (ran.intercepts), (ii) a vector of random slopes to be evaluated (slopes), (iii) a vector specifying, for each element of slopes, whether the correlation between the slope and by-variables specified in by.vars should be added (corr), and (iv) a vector of “by” variables for the random slopes (by.vars). Values that can be supplied to the corr argument are 1 (add correlation), 0 (do not add correlation), and NA (for when the "slope" is a factor variable). Note that if a term in slopes is a factor variable, the corr value tied to it will be automatically set to NA. Also note that if no values are supplied to corr, a vector of 0 as long as the slopes vector will be automatically supplied. For example list(ran.intercepts = "Word", slopes = c("Frequency", "Length", "NSynSet","Class"), corr = c(0, 0, 1, NA), by.vars = "Subject"). Another example is list(slopes = c("Trial", "Class"), by.vars = "Subject"), where the corr argument will be equal to c(0, NA).

alpha

Level of significance for log-likelihood ratio test. Defaults to 0.05.

if.warn.not.add

Logical. If a warning is issued after fitting a model with a new random effect (e.g., false convergence or the like), should the random effect nevertheless be evaluated? Defaults to TRUE, meaning that if such a warning is issued, the random effect will not be added to the random effects structure of the model. If set to FALSE, the random effect will be evaluated for inclusion as any other random effects would be via log likelihood ratio testing even if a warning is issued.

log.file

Should the back-fitting log be saved? Defaults to NULL, which means that a log file is saved in a temporary folder as paste("ffRanefLMER_log_", gsub(":", "-", gsub(" ", "_", date())), ".txt", sep = ""). The path and file name of the log can be changed to whatever the use wishes. Set to FALSE to disable.

Value

A mer object with forward-fitted random effect structure as well as a log of the process is printed on screen and, optionally, printed in a log file.

Note

The removal of a random effect from the random effects structure if the variables that compose it are not also in the fixed effects structure has been turned off in this version.

Author(s)

Antoine Tremblay, Statistics Canada, [e-mail].

References

Pinheiro, J.C. and Bates, D.M. (2000). Mixed Effects Models in S and S-Plus. New York: Springer.

See Also

bfFixefLMER_F.fnc; bfFixefLMER_t.fnc; fitLMER.fnc; mcposthoc.fnc; pamer.fnc; mcp.fnc; romr.fnc; perSubjectTrim.fnc.

Examples

# see example in LMERConvenienceFunctions help page.