Linear Mixed Effect Model — lme

Fit a linear mixed effect model (i.e., hierarchical linear model, multilevel linear model) using the nlme::lme() or the lmerTest::lmer() function. Linear mixed effect model is used to explore the effect of continuous / categorical variables in predicting a normally distributed continuous variable.

lme_model(
  data,
  model = NULL,
  response_variable,
  random_effect_factors = NULL,
  non_random_effect_factors = NULL,
  two_way_interaction_factor = NULL,
  three_way_interaction_factor = NULL,
  id,
  estimation_method = "REML",
  opt_control = "bobyqa",
  na.action = stats::na.omit,
  use_package = "lmerTest",
  quite = FALSE
)

Arguments

data: data.frame
model: lme4 model syntax. Support more complicated model. Note that model_summary will only return fixed effect estimates.
response_variable: DV (i.e., outcome variable / response variable). Length of 1. Support dplyr::select() syntax.
random_effect_factors: random effect factors (level-1 variable for HLM people) Factors that need to estimate fixed effect and random effect (i.e., random slope / varying slope based on the id). Support dplyr::select() syntax.
non_random_effect_factors: non-random effect factors (level-2 variable for HLM people). Factors only need to estimate fixed effect. Support dplyr::select() syntax.
two_way_interaction_factor: two-way interaction factors. You need to pass 2+ factor. Support dplyr::select() syntax.
three_way_interaction_factor: three-way interaction factor. You need to pass exactly 3 factors. Specifying three-way interaction factors automatically included all two-way interactions, so please do not specify the two_way_interaction_factor argument. Support dplyr::select() syntax.
id: the nesting variable (e.g. group, time). Length of 1. Support dplyr::select() syntax.
estimation_method: character. ML or REML default to REML.
opt_control: default is optim for lme and bobyqa for lmerTest
na.action: default is stats::na.omit. Another common option is na.exclude
use_package: Default is lmerTest. Only available for linear mixed effect model. Options are nlme, lmerTest, or lme4('lme4 return similar result as lmerTest except the return model)
quite: suppress printing output

Value

an object representing the linear mixed-effects model fit (it maybe an object from lme or lmer depending of the package you use)

Details

Here is a little tip. If you are using generic selecting syntax (e.g., contains() or start_with()), you don't need to remove the response variable and the id from the factors. It will be automatically remove. For example, if you have x1:x9 as your factors. You want to regress x2:x8 on x1. Your probably pass something like response_variable = x1, random_effect_factors = c(contains('x'),-x1) to the function. However, you don't need to do that, you can just pass random_effect_factors = c(contains('x')) to the function since it will automatically remove the response variable from selection.

Examples

# two-level model with level-1 and level-2 variable with random intercept and random slope
fit1 <- lme_model(
  data = popular,
  response_variable = popular,
  random_effect_factors = c(extrav, sex),
  non_random_effect_factors = texp,
  id = class
)
#> Fitting Model with lmer:
#>  Formula = popular ~ extrav + sex + texp + (1 + extrav + sex | class)
#> boundary (singular) fit: see help('isSingular')


# added two-way interaction factor
fit2 <- lme_model(
  data = popular,
  response_variable = popular,
  random_effect_factors = c(extrav, sex),
  non_random_effect_factors = texp,
  two_way_interaction_factor = c(extrav, texp),
  id = class
)
#> Fitting Model with lmer:
#>  Formula = popular ~ extrav + sex + texp + extrav*texp + (1 + extrav + sex | class)
#> boundary (singular) fit: see help('isSingular')

# pass a explicit lme model (I don't why you want to do that, but you can)
lme_fit <- lme_model(
  model = "popular ~ extrav*texp + (1 + extrav | class)",
  data = popular
)
#> boundary (singular) fit: see help('isSingular')