From eb04b7b388681931de405ebd315e9f32c01574ac Mon Sep 17 00:00:00 2001 From: Jason Moy Date: Fri, 26 Apr 2024 15:54:20 -0700 Subject: [PATCH] type: message: --- NAMESPACE | 2 - R/lme_model.R | 269 ---------------------------- R/lme_model_summary.R | 230 ------------------------ man/lme_model.Rd | 87 --------- man/lme_multilevel_model_summary.Rd | 108 ----------- tests/testthat/test-lme-model.R | 8 - 6 files changed, 704 deletions(-) delete mode 100644 R/lme_model.R delete mode 100644 R/lme_model_summary.R delete mode 100644 man/lme_model.Rd delete mode 100644 man/lme_multilevel_model_summary.Rd delete mode 100644 tests/testthat/test-lme-model.R diff --git a/NAMESPACE b/NAMESPACE index 31fbc79..3068408 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -20,10 +20,8 @@ export(lm_model) export(lm_model_explore) export(lm_model_summary) export(lm_model_table) -export(lme_model) export(lme_model_explore) export(lme_model_table) -export(lme_multilevel_model_summary) export(measurement_invariance) export(mediation_summary) export(model_summary) diff --git a/R/lme_model.R b/R/lme_model.R deleted file mode 100644 index d6c5911..0000000 --- a/R/lme_model.R +++ /dev/null @@ -1,269 +0,0 @@ -#' Linear Mixed Effect Model -#' -#' `r lifecycle::badge("superseded")` \cr -#' 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. -#' -#' -#' @param data `data.frame` -#' @param model `lme4` model syntax. Support more complicated model. Note that model_summary will only return fixed effect estimates. -#' @param response_variable DV (i.e., outcome variable / response variable). Length of 1. Support `dplyr::select()` syntax. -#' @param 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. -#' @param 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. -#' @param two_way_interaction_factor two-way interaction factors. You need to pass 2+ factor. Support `dplyr::select()` syntax. -#' @param 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. -#' @param id the nesting variable (e.g. group, time). Length of 1. Support `dplyr::select()` syntax. -#' @param estimation_method character. `ML` or `REML` default to `REML`. -#' @param na.action default is `stats::na.omit`. Another common option is `na.exclude` -#' @param opt_control default is `optim` for `lme` and `bobyqa` for `lmerTest` -#' @param 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) -#' @param quite suppress printing output -#' -#' @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. -#' -#' @return an object representing the linear mixed-effects model fit (it maybe an object from `lme` or `lmer` depending of the package you use) -#' -#' @export -#' -#' @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 -#' ) -#' -#' -#' # 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 -#' ) -#' -#' # 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 -#' ) -lme_model <- function(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) { - ########################################### Set up ############################################# - lme_model_check <- function(object, method) { - if (method == "response_variable_check") { - if (length(object) != 1) { - stop("Response variable must be length of 1") - } - } - if (method == "id_check") { - if (length(object) != 1) { - stop("ID must be length of 1") - } - } - if (method == "three_way_interaction_factor_check") { - if (length(object) != 3) { - stop("three_way_interaction_factor must have three factors") - } - } - if (method == "two_interaction_factor_check") { - if (length(object) < 2) { - stop("two_way_interaction_factor must have three factors") - } - } - } - - # run a getfun function that is essentially for do.call() later - getfun <- function(x) { - if (length(grep("::", x)) > 0) { - parts <- strsplit(x, "::")[[1]] - getExportedValue(parts[1], parts[2]) - } else { - x - } - } - - # opt_control check for lme4 and lmerTest to change default optimizer from optim to bobyqa - opt_control_check <- function(opt_control) { - if (opt_control == "bobyqa") { - warning("The default optimizer is changed from bobyqa to optim for nlme package") - opt_control <- "optim" - return(opt_control) - } - return(opt_control) - } - - - - ###################################### Modeling with Explict Model ############################################# - if (!is.null(model)) { - if (use_package == "nlme") { - warning("A model is specified explicitly. Switching to lmerTest for estimation.") - use_package <- "lmerTest" - } - - lmerformula <- stats::as.formula(model) - lmerCtr <- lme4::lmerControl(optimizer = opt_control) - - if (use_package == "lmerTest") { - model <- lmerTest::lmer( - formula = lmerformula, - data = data, - na.action = na.action, - control = lmerCtr - ) - } else if (use_package == "lme4") { - model <- lme4::lmer( - formula = lmerformula, - data = data, - na.action = na.action, - control = lmerCtr - ) - } - return(model) - } - - ###################################### Build model for models without explicit model ############################################# - ## parse tidyselect syntax - response_variable <- data %>% - tidyselect::eval_select(data = ., expr = enquo(response_variable),strict = TRUE) %>% - names() - random_effect_factors <- data %>% - tidyselect::eval_select(data = ., expr = enquo(random_effect_factors),strict = TRUE) %>% - names() - non_random_effect_factors <- data %>% - tidyselect::eval_select(data = ., expr = enquo(non_random_effect_factors),strict = TRUE) %>% - names() - two_way_interaction_factor <- data %>% - tidyselect::eval_select(data = ., expr = enquo(two_way_interaction_factor),strict = TRUE) %>% - names() - three_way_interaction_factor <- data %>% - tidyselect::eval_select(data = ., expr = enquo(three_way_interaction_factor),strict = TRUE) %>% - names() - id <- data %>% - tidyselect::eval_select(data = ., expr = enquo(id),strict = TRUE) %>% - names() - - - ## remove response variable and id from all other variables - random_effect_factors <- random_effect_factors[!random_effect_factors %in% c(response_variable, id)] - non_random_effect_factors <- non_random_effect_factors[!non_random_effect_factors %in% c(response_variable, id)] - two_way_interaction_factor <- two_way_interaction_factor[!two_way_interaction_factor %in% c(response_variable, id)] - three_way_interaction_factor <- three_way_interaction_factor[!three_way_interaction_factor %in% c(response_variable, id)] - - # Check variable length & assign NULL to variables that is NULL - if (length(non_random_effect_factors) == 0) { - non_random_effect_factors <- NULL - } - if (length(two_way_interaction_factor) == 0) { - two_way_interaction_factor <- NULL - } else { - lme_model_check(two_way_interaction_factor, method = "two_interaction_factor_check") - } - if (length(three_way_interaction_factor) == 0) { - three_way_interaction_factor <- NULL - } else { - lme_model_check(three_way_interaction_factor, method = "three_way_interaction_factor_check") - } - lme_model_check(response_variable, method = "response_variable_check") - lme_model_check(id, method = "id_check") - - # Fixed factor include both level factor - fixed_factors <- c(random_effect_factors, non_random_effect_factors) - - # Random factor only include individual_level factor - random_factors <- c(1, random_effect_factors) - - two_way_interaction_terms <- NULL - three_way_interaction_terms <- NULL - # Check if interaction term exist, if so, add interaction terms to fixed factor - if (!is.null(two_way_interaction_factor)) { - two_way_interaction_terms <- two_way_interaction_terms(two_way_interaction_factor) - } - - if (!is.null(three_way_interaction_factor)) { - two_way_interaction_terms <- NULL - three_way_interaction_terms <- paste(three_way_interaction_factor, collapse = "*") - } - fixed_factors <- c(fixed_factors, two_way_interaction_terms, three_way_interaction_terms) - - - ###################################### Use nlme as the Package for Modeling ############################################# - if (use_package == "nlme") { - # change the default optimzer to optim for nlme - opt_control <- opt_control_check(opt_control) - - # Create the formula for fixed factor - fixed_factors_formula <- stats::as.formula(paste(paste(response_variable, "~"), paste(fixed_factors, collapse = " + "))) - # Created the formula for random factors - random_factors_formula <- stats::as.formula(paste("~ 1 +", paste(random_factors, collapse = " + "), paste("|", id))) - - # print formula - if (quite == FALSE) { - fit_fixed_effect_formula <- paste(paste(response_variable, "~"), paste(fixed_factors, collapse = " + ")) - fit_random_effect_formula <- paste("~", paste(random_factors, collapse = " + "), paste("|", id)) - fit_formula <- paste("\n Fixed =", fit_fixed_effect_formula, "\n Random =", fit_random_effect_formula) - cat(paste("Fitting Model with lme:", fit_formula, "\n")) - } - - ctrl <- nlme::lmeControl(opt = opt_control) - # Run lme model - model <- do.call(getfun("nlme::lme"), list( - fixed = fixed_factors_formula, - random = random_factors_formula, - data = quote(data), - na.action = na.action, - control = ctrl, - method = estimation_method - )) - - ###################################### Use lme4 or lmerTest as the Package for Modeling ############################################# - } else if (use_package == "lmerTest" | use_package == "lme4") { - # Create the formula for fixed factor - lmer_fixed_factors_formula <- paste(paste(response_variable, "~"), paste(fixed_factors, collapse = " + ")) - # Created the formula for random factors - lmer_random_factors_formula <- paste(paste(random_factors, collapse = " + "), paste("|", id)) - lmerformula <- stats::as.formula(paste(lmer_fixed_factors_formula, " + (", lmer_random_factors_formula, ")", sep = "")) - lmerCtr <- lme4::lmerControl(optimizer = opt_control) - - # Print fitting formula - if (quite == FALSE) { - fit_formula <- paste(lmer_fixed_factors_formula, " + (", lmer_random_factors_formula, ")", sep = "") - cat(paste("Fitting Model with lmer:\n Formula = ", fit_formula, "\n", sep = "")) - } - if (use_package == "lmerTest") { - # run lmerTest model - model <- lmerTest::lmer( - formula = lmerformula, - data = data, - na.action = na.action, - control = lmerCtr - ) - } else if (use_package == "lme4") { - # run lme4 model - model <- lme4::lmer( - formula = lmerformula, - data = data, - na.action = na.action, - control = lmerCtr - ) - } - } - return(model) -} diff --git a/R/lme_model_summary.R b/R/lme_model_summary.R deleted file mode 100644 index eedb0c7..0000000 --- a/R/lme_model_summary.R +++ /dev/null @@ -1,230 +0,0 @@ -#' Model Summary for Mixed Effect Model -#' -#' `r lifecycle::badge("superseded")` \cr -#' An integrated function for fitting a multilevel linear regression (also known as hierarchical linear regression). -#' This function will no longer be updated. Please use the these functions separately instead: \code{\link{model_summary}}, \code{\link{interaction_plot}},and \code{\link{simple_slope}}. -#' -#' @param data `data.frame` -#' @param model `lme4` model syntax. Support more complicated model structure from `lme4`. It is not well-tested to ensure accuracy `r lifecycle::badge("experimental")` -#' @param response_variable DV (i.e., outcome variable / response variable). Length of 1. Support `dplyr::select()` syntax. -#' @param random_effect_factors random effect factors (level-1 variable for HLM from a HLM perspective) Factors that need to estimate fixed effect and random effect (i.e., random slope / varying slope based on the id). Support `dplyr::select()` syntax. -#' @param non_random_effect_factors non-random effect factors (level-2 variable from a HLM perspective). Factors only need to estimate fixed effect. Support `dplyr::select()` syntax. -#' @param two_way_interaction_factor two-way interaction factors. You need to pass 2+ factor. Support `dplyr::select()` syntax. -#' @param 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. -#' @param id the nesting variable (e.g. group, time). Length of 1. Support `dplyr::select()` syntax. -#' @param estimation_method character. `ML` or `REML` default is `REML`. -#' @param return_result If it is set to `TRUE` (default is `FALSE`), it will return the `model`, `model_summary`, and `plot` (`plot` if the interaction term is included) -#' @param na.action default is `stats::na.omit`. Another common option is `na.exclude` -#' @param opt_control default is `optim` for `lme` and `bobyqa` for `lmerTest`. -#' @param y_lim the plot's upper and lower limit for the y-axis. Length of 2. Example: `c(lower_limit, upper_limit)` -#' @param plot_color If it is set to `TRUE` (default is `FALSE`), the interaction plot will plot with color. -#' @param 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) -#' @param standardize The method used for standardizing the parameters. Can be NULL (default; no standardization), "refit" (for re-fitting the model on standardized data) or one of "basic", "posthoc", "smart", "pseudo". See 'Details' in parameters::standardize_parameters() -#' @param ci_method see options in the `Mixed model` section in ?parameters::model_parameters() -#' @param quite suppress printing output -#' @param digits number of digits to round to -#' @param simple_slope Slope estimate at ± 1 SD and the mean of the moderator. Uses `interactions::sim_slope()` in the background. -#' @param assumption_plot Generate an panel of plots that check major assumptions. It is usually recommended to inspect model assumption violation visually. In the background, it calls `performance::check_model()`. -#' @param streamline print streamlined output. -#' @param family a GLM family. It will passed to the family argument in glmer. See `?glmer` for possible options. `r lifecycle::badge("experimental")` -#' @param model_summary print model summary. Required to be `TRUE` if you want `assumption_plot`. -#' @param interaction_plot generate interaction plot. Default is `TRUE` -#' -#' @return a list of all requested items in the order of model, model_summary, interaction_plot, simple_slope -#' @export -#' -#' @examples -#' fit <- lme_multilevel_model_summary( -#' data = popular, -#' response_variable = popular, -#' random_effect_factors = NULL, # you can add random effect predictors here -#' non_random_effect_factors = c(extrav,texp), -#' two_way_interaction_factor = NULL, # you can add two-way interaction plot here -#' id = class, -#' simple_slope = FALSE, # you can also request simple slope estimate -#' assumption_plot = FALSE, # you can also request assumption plot -#' plot_color = FALSE, # you can also request the plot in color -#' streamline = FALSE # you can change this to get the least amount of info -#' ) -#' -lme_multilevel_model_summary <- function(data, - model = NULL, - response_variable = NULL, - random_effect_factors = NULL, - non_random_effect_factors = NULL, - two_way_interaction_factor = NULL, - three_way_interaction_factor = NULL, - family = NULL, - id = NULL, - estimation_method = "REML", - opt_control = "bobyqa", - na.action = stats::na.omit, - model_summary = TRUE, - interaction_plot = TRUE, - y_lim = NULL, - plot_color = FALSE, - digits = 3, - use_package = "lmerTest", - standardize = NULL, - ci_method = 'satterthwaite', - simple_slope = FALSE, - assumption_plot = FALSE, - quite = FALSE, - streamline = FALSE, - return_result = FALSE) { - ##################################### Set up ######################################### - # Temporary disable plots for glmer object - if (simple_slope == TRUE) { - if (use_package == "nlme") { - warning("Switched use_package to lmerTest since you requested simple_slope") - use_package <- "lmerTest" - } - } - - response_variable <- data %>% - tidyselect::eval_select(data = ., expr = enquo(response_variable),strict = TRUE) %>% - names() - random_effect_factors <- data %>% - tidyselect::eval_select(data = ., expr = enquo(random_effect_factors),strict = TRUE) %>% - names() - non_random_effect_factors <- data %>% - tidyselect::eval_select(data = ., expr = enquo(non_random_effect_factors),strict = TRUE) %>% - names() - two_way_interaction_factor <- data %>% - tidyselect::eval_select(data = ., expr = enquo(two_way_interaction_factor),strict = TRUE) %>% - names() - three_way_interaction_factor <- data %>% - tidyselect::eval_select(data = ., expr = enquo(three_way_interaction_factor),strict = TRUE) %>% - names() - id <- data %>% - tidyselect::eval_select(data = ., expr = enquo(id),strict = TRUE) %>% - names() - - ##################################### Run Model ######################################### - if (is.null(family)) { - model <- lme_model( - model = model, - data = data, - response_variable = dplyr::all_of(response_variable), - random_effect_factors = dplyr::all_of(random_effect_factors), - non_random_effect_factors = dplyr::all_of(non_random_effect_factors), - two_way_interaction_factor = dplyr::all_of(two_way_interaction_factor), - three_way_interaction_factor = dplyr::all_of(three_way_interaction_factor), - id = dplyr::all_of(id), - opt_control = opt_control, - na.action = na.action, - estimation_method = estimation_method, - use_package = use_package, - quite = TRUE - ) - } else { - if (simple_slope == TRUE | interaction_plot == TRUE) { - simple_slope <- FALSE - interaction_plot <- FALSE - warning("interaction_plot & simple_slope is not avaliable for glme model for now") - } - # model <- glme_model( - # model = model, - # data = data, - # response_variable = dplyr::all_of(response_variable), - # random_effect_factors = dplyr::all_of(random_effect_factors), - # non_random_effect_factors = dplyr::all_of(non_random_effect_factors), - # two_way_interaction_factor = dplyr::all_of(two_way_interaction_factor), - # three_way_interaction_factor = dplyr::all_of(three_way_interaction_factor), - # family = family, - # id = dplyr::all_of(id), - # opt_control = opt_control, - # na.action = na.action, - # estimation_method = estimation_method, - # quite = TRUE - # ) - return('glme model will be supported in the future.') - } - - - ############################### Generate Interaction Plots ############################### - two_way_interaction_factor <- data %>% - tidyselect::eval_select(data = ., expr = enquo(two_way_interaction_factor),strict = TRUE) %>% - names() - three_way_interaction_factor <- data %>% - tidyselect::eval_select(data = ., expr = enquo(three_way_interaction_factor),strict = TRUE) %>% - names() - interaction_plot_object <- NULL - if (length(two_way_interaction_factor) != 0 & - (interaction_plot == TRUE | return_result == TRUE)) { - interaction_plot_object <- two_way_interaction_plot( - model = model, - y_lim = y_lim, - plot_color = plot_color - ) - } else if (length(three_way_interaction_factor) != 0 & - (interaction_plot == TRUE | return_result == TRUE)) { - interaction_plot_object <- three_way_interaction_plot( - model = model, - y_lim = y_lim, - plot_color = plot_color - ) - } else { - interaction_plot_object <- NULL - interaction_plot <- FALSE - } - - ############################### Generate Simple Slope Output ############################### - if (simple_slope == TRUE) { - simple_slope_list <- simple_slope( - data = data, - model = model) - } else { - simple_slope_list <- list(simple_slope_df = NULL, - jn_plot = NULL) - } - - ######################################### Output Result ######################################### - if (model_summary == TRUE) { - model_summary_list <- model_summary( - model = model, - standardize = standardize, - ci_method = ci_method, - streamline = streamline, - digits = digits, - return_result = TRUE, - assumption_plot = assumption_plot, - quite = quite - ) - } else { - model_summary_list <- NULL - } - - - if (simple_slope == TRUE & quite == FALSE) { - super_print("underline|Slope Estimates at Each Level of Moderators") - print_table(simple_slope_list$simple_slope_df) - super_print( - "italic|Note: For continuous variable, low and high represent -1 and +1 SD from the mean, respectively." - ) - print(simple_slope_list$jn_plot) - } - - if (interaction_plot == TRUE) { - try(print(interaction_plot_object)) - } - # warning message - plot_logical <- c(interaction_plot, simple_slope, assumption_plot) - number_of_plot_requested <- length(plot_logical[plot_logical]) - if (number_of_plot_requested > 1) { - warning( - "You requested > 2 plots. Since 1 plot can be displayed at a time, considering using Rmd for better viewing experience." - ) - } - - # Return Result - if (return_result == TRUE) { - return_list <- list( - model = model, - summary = model_summary_list, - interaction_plot = interaction_plot_object, - simple_slope = simple_slope_list - ) - return(return_list) - } -} diff --git a/man/lme_model.Rd b/man/lme_model.Rd deleted file mode 100644 index da75cd2..0000000 --- a/man/lme_model.Rd +++ /dev/null @@ -1,87 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/lme_model.R -\name{lme_model} -\alias{lme_model} -\title{Linear Mixed Effect Model} -\usage{ -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{ -\item{data}{\code{data.frame}} - -\item{model}{\code{lme4} model syntax. Support more complicated model. Note that model_summary will only return fixed effect estimates.} - -\item{response_variable}{DV (i.e., outcome variable / response variable). Length of 1. Support \code{dplyr::select()} syntax.} - -\item{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 \code{dplyr::select()} syntax.} - -\item{non_random_effect_factors}{non-random effect factors (level-2 variable for HLM people). Factors only need to estimate fixed effect. Support \code{dplyr::select()} syntax.} - -\item{two_way_interaction_factor}{two-way interaction factors. You need to pass 2+ factor. Support \code{dplyr::select()} syntax.} - -\item{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 \code{dplyr::select()} syntax.} - -\item{id}{the nesting variable (e.g. group, time). Length of 1. Support \code{dplyr::select()} syntax.} - -\item{estimation_method}{character. \code{ML} or \code{REML} default to \code{REML}.} - -\item{opt_control}{default is \code{optim} for \code{lme} and \code{bobyqa} for \code{lmerTest}} - -\item{na.action}{default is \code{stats::na.omit}. Another common option is \code{na.exclude}} - -\item{use_package}{Default is \code{lmerTest}. Only available for linear mixed effect model. Options are \code{nlme}, \code{lmerTest}, or \code{lme4}(\verb{'lme4} return similar result as \code{lmerTest} except the return model)} - -\item{quite}{suppress printing output} -} -\value{ -an object representing the linear mixed-effects model fit (it maybe an object from \code{lme} or \code{lmer} depending of the package you use) -} -\description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}} \cr -Fit a linear mixed effect model (i.e., hierarchical linear model, multilevel linear model) using the \code{nlme::lme()} or the \code{lmerTest::lmer()} function. -Linear mixed effect model is used to explore the effect of continuous / categorical variables in predicting a normally distributed continuous variable. -} -\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 -) - - -# 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 -) - -# 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 -) -} diff --git a/man/lme_multilevel_model_summary.Rd b/man/lme_multilevel_model_summary.Rd deleted file mode 100644 index 75a6caa..0000000 --- a/man/lme_multilevel_model_summary.Rd +++ /dev/null @@ -1,108 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/lme_model_summary.R -\name{lme_multilevel_model_summary} -\alias{lme_multilevel_model_summary} -\title{Model Summary for Mixed Effect Model} -\usage{ -lme_multilevel_model_summary( - data, - model = NULL, - response_variable = NULL, - random_effect_factors = NULL, - non_random_effect_factors = NULL, - two_way_interaction_factor = NULL, - three_way_interaction_factor = NULL, - family = NULL, - id = NULL, - estimation_method = "REML", - opt_control = "bobyqa", - na.action = stats::na.omit, - model_summary = TRUE, - interaction_plot = TRUE, - y_lim = NULL, - plot_color = FALSE, - digits = 3, - use_package = "lmerTest", - standardize = NULL, - ci_method = "satterthwaite", - simple_slope = FALSE, - assumption_plot = FALSE, - quite = FALSE, - streamline = FALSE, - return_result = FALSE -) -} -\arguments{ -\item{data}{\code{data.frame}} - -\item{model}{\code{lme4} model syntax. Support more complicated model structure from \code{lme4}. It is not well-tested to ensure accuracy \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}} - -\item{response_variable}{DV (i.e., outcome variable / response variable). Length of 1. Support \code{dplyr::select()} syntax.} - -\item{random_effect_factors}{random effect factors (level-1 variable for HLM from a HLM perspective) Factors that need to estimate fixed effect and random effect (i.e., random slope / varying slope based on the id). Support \code{dplyr::select()} syntax.} - -\item{non_random_effect_factors}{non-random effect factors (level-2 variable from a HLM perspective). Factors only need to estimate fixed effect. Support \code{dplyr::select()} syntax.} - -\item{two_way_interaction_factor}{two-way interaction factors. You need to pass 2+ factor. Support \code{dplyr::select()} syntax.} - -\item{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 \code{dplyr::select()} syntax.} - -\item{family}{a GLM family. It will passed to the family argument in glmer. See \code{?glmer} for possible options. \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}} - -\item{id}{the nesting variable (e.g. group, time). Length of 1. Support \code{dplyr::select()} syntax.} - -\item{estimation_method}{character. \code{ML} or \code{REML} default is \code{REML}.} - -\item{opt_control}{default is \code{optim} for \code{lme} and \code{bobyqa} for \code{lmerTest}.} - -\item{na.action}{default is \code{stats::na.omit}. Another common option is \code{na.exclude}} - -\item{model_summary}{print model summary. Required to be \code{TRUE} if you want \code{assumption_plot}.} - -\item{interaction_plot}{generate interaction plot. Default is \code{TRUE}} - -\item{y_lim}{the plot's upper and lower limit for the y-axis. Length of 2. Example: \code{c(lower_limit, upper_limit)}} - -\item{plot_color}{If it is set to \code{TRUE} (default is \code{FALSE}), the interaction plot will plot with color.} - -\item{digits}{number of digits to round to} - -\item{use_package}{Default is \code{lmerTest}. Only available for linear mixed effect model. Options are \code{nlme}, \code{lmerTest}, or \code{lme4}(\verb{'lme4} return similar result as \code{lmerTest} except the return model)} - -\item{standardize}{The method used for standardizing the parameters. Can be NULL (default; no standardization), "refit" (for re-fitting the model on standardized data) or one of "basic", "posthoc", "smart", "pseudo". See 'Details' in parameters::standardize_parameters()} - -\item{ci_method}{see options in the \verb{Mixed model} section in ?parameters::model_parameters()} - -\item{simple_slope}{Slope estimate at ± 1 SD and the mean of the moderator. Uses \code{interactions::sim_slope()} in the background.} - -\item{assumption_plot}{Generate an panel of plots that check major assumptions. It is usually recommended to inspect model assumption violation visually. In the background, it calls \code{performance::check_model()}.} - -\item{quite}{suppress printing output} - -\item{streamline}{print streamlined output.} - -\item{return_result}{If it is set to \code{TRUE} (default is \code{FALSE}), it will return the \code{model}, \code{model_summary}, and \code{plot} (\code{plot} if the interaction term is included)} -} -\value{ -a list of all requested items in the order of model, model_summary, interaction_plot, simple_slope -} -\description{ -\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}} \cr -An integrated function for fitting a multilevel linear regression (also known as hierarchical linear regression). -This function will no longer be updated. Please use the these functions separately instead: \code{\link{model_summary}}, \code{\link{interaction_plot}},and \code{\link{simple_slope}}. -} -\examples{ -fit <- lme_multilevel_model_summary( - data = popular, - response_variable = popular, - random_effect_factors = NULL, # you can add random effect predictors here - non_random_effect_factors = c(extrav,texp), - two_way_interaction_factor = NULL, # you can add two-way interaction plot here - id = class, - simple_slope = FALSE, # you can also request simple slope estimate - assumption_plot = FALSE, # you can also request assumption plot - plot_color = FALSE, # you can also request the plot in color - streamline = FALSE # you can change this to get the least amount of info -) - -} diff --git a/tests/testthat/test-lme-model.R b/tests/testthat/test-lme-model.R deleted file mode 100644 index 2a38ef2..0000000 --- a/tests/testthat/test-lme-model.R +++ /dev/null @@ -1,8 +0,0 @@ -testthat::test_that(desc = "lme_model: lmerTest (specify model)", { - fit <- lme_model( - data = popular, - model = "popular ~ extrav + sex + (1 | class)", - use_package = "lmerTest" - ) - expect_equal(class(fit)[1], "lmerModLmerTest") -})