[Stable]
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')