Merge pull request #10 from JeffreyRStevens/devel

Add format_stats.lmerModLmerTest method, tests, and documentation

DESCRIPTION

@@ -19,6 +19,7 @@ Suggests:
     correlation,
     knitr,
     lme4,
+    lmerTest,
     rmarkdown,
     testthat (>= 3.0.0)
 Config/testthat/edition: 3

NAMESPACE

@@ -6,6 +6,7 @@ S3method(format_stats,default)
 S3method(format_stats,easycorrelation)
 S3method(format_stats,htest)
 S3method(format_stats,lm)
+S3method(format_stats,lmerModLmerTest)
 S3method(format_stats,merMod)
 export(format_bf)
 export(format_chr)

R/format_stats.R

@@ -18,7 +18,8 @@
 #' arguments, see [format_stats.htest()] for htest correlations, t-tests,
 #' and Wilcoxon tests, [format_stats.easycorrelation()] for easycorrelation
 #' correlations, [format_stats.lm()] for linear models,
-#' [format_stats.merMod()] for linear mixedmodels, and
+#' [format_stats.merMod()] and [format_stats.lmerModLmerTest()] for
+#' linear mixed models, and
 #' [format_stats.BFBayesFactor()] for Bayes factors from the
 #' \{[BayesFactor](https://cran.r-project.org/package=BayesFactor)\} package.
 #'
@@ -49,6 +50,9 @@
 #' format_stats(lme4::lmer(mpg ~ hp + (1 | cyl), data = mtcars), term = "hp")
 #' format_stats(lme4::glmer(am ~ hp + (1 | cyl), data = mtcars, family = binomial), term = "hp")
 #'
+#' # Format lmerTest::lmer() object
+#' format_stats(lmerTest::lmer(mpg ~ hp + (1 | cyl), data = mtcars), term = "hp")
+#'
 #' # Format BFBayesFactor object from {BayesFactor} package
 #' format_stats(BayesFactor::ttestBF(mtcars$vs, mtcars$am))
 format_stats <- function(x, ...) {

R/format_stats_lmerTest.R

@@ -0,0 +1,106 @@
+
+#' Format linear mixed model statistics
+#'
+#' @description
+#' This method formats linear mixed model statistics from the
+#' class `lmerModLmerTest` from the
+#' \{[lmerTest](https://cran.r-project.org/package=lmerTest)\} package.
+#' Only fixed effects can be extracted.
+#' The default output is APA formatted, but this function allows
+#' control over numbers of digits, leading zeros, italics,
+#' and output format of Markdown or LaTeX.
+#'
+#' @param x An `lmerModLmerTest` object from [lmerTest::lmer()].
+#' @param term Character string for row name of term to extract statistics for.
+#' This must be the exact string returned in the `summary()` output from the
+#' `lmerModLmerTest` object and can only be fixed effects.
+#' @param digits Number of digits after the decimal for test statistics.
+#' @param pdigits Number of digits after the decimal for p-values, ranging
+#' between 1-5 (also controls cutoff for small p-values).
+#' @param pzero Logical value (default = FALSE) for whether to include
+#' leading zero for p-values.
+#' @param full Logical value (default = TRUE) for whether to include extra
+#' info (e.g., standard errors and t-values or z-values for terms)
+#' or just test statistic and p-value.
+#' @param italics Logical value (default = TRUE) for whether statistics labels
+#' should be italicized.
+#' @param type Type of formatting ("md" = markdown, "latex" = LaTeX).
+#' @param ... Additional arguments passed to methods.
+#'
+#' @return
+#' A character string of statistical information formatted in Markdown or LaTeX.
+#'
+#' @method format_stats lmerModLmerTest
+#' @family functions for printing statistical objects
+#' @export
+#'
+#' @examples
+#' test_lmer <- lmerTest::lmer(mpg ~ hp + (1 | cyl), data = mtcars)
+#'
+#' # Format linear mixed model term statistics
+#' format_stats(test_lmer, term = "hp")
+#'
+#' # Remove italics
+#' format_stats(test_lmer, term = "hp", italics = FALSE)
+#'
+#' # Change digits and add leading zero to p-value
+#' format_stats(test_lmer, term = "hp", digits = 3, pdigits = 4, pzero = TRUE)
+#'
+#' # Format for LaTeX
+#' format_stats(test_lmer, term = "hp", type = "latex")
+format_stats.lmerModLmerTest <- function(x,
+                                         term = NULL,
+                                         digits = 3,
+                                         pdigits = 3,
+                                         pzero = FALSE,
+                                         full = TRUE,
+                                         italics = TRUE,
+                                         type = "md",
+                                         ...) {
+  # Validate arguments
+  check_character(term)
+  check_number_whole(digits, min = 0, allow_null = TRUE)
+  check_number_whole(pdigits, min = 1, max = 5)
+  check_bool(pzero)
+  check_bool(full)
+  check_bool(italics)
+  check_string(type)
+  check_match(type, c("md", "latex"))
+
+  summ <- summary(x)
+
+  terms <- rownames(summ$coefficients)
+  stopifnot("Argument `term` not found in model terms." = term %in% terms)
+  term_num <- which(terms == term)
+
+  coeffs <- as.data.frame(summ$coefficients)
+  estimate <- coeffs[term_num, "Estimate"]
+  se <- coeffs[term_num, "Std. Error"]
+  z <- coeffs[term_num, "t value"]
+  p_value <- coeffs[term_num, "Pr(>|t|)"]
+  pvalue <- format_p(p_value,
+                     digits = pdigits, pzero = pzero,
+                     italics = italics, type = type)
+  z_lab <- "t"
+
+
+  # Format values
+  stat_value <- format_num(estimate, digits = digits, pzero = TRUE)
+  se_value <- format_num(se, digits = digits, pzero = TRUE)
+  z_value <- format_num(z, digits = digits, pzero = TRUE)
+
+  # Build label
+  stat_label <- dplyr::case_when(
+    !italics & identical(type, "md") ~ "\u03B2",
+    !italics & identical(type, "latex") ~ "\\textbeta",
+    italics & identical(type, "md") ~ format_chr("\u03B2", italics = TRUE, type = "md"),
+    italics & identical(type, "latex") ~ format_chr("\\beta", italics = TRUE, type = "latex")
+  )
+
+  # Create statistics string
+  if(full) {
+    paste0(stat_label, " = ", stat_value, ", SE = ", se_value, ", ", format_chr(z_lab, italics = italics, type = type), " = ", z_value, ", ", pvalue)
+  } else {
+    paste0(stat_label, " = ", stat_value, ", ", pvalue)
+  }
+}

R/format_stats_merMod.R

@@ -36,9 +36,8 @@
 #' @export
 #'
 #' @examples
-#' library(lme4)
-#' test_lmer <- lmer(mpg ~ hp + (1 | cyl), data = mtcars)
-#' test_glmer <- glmer(am ~ hp + (1 | cyl), data = mtcars, family = binomial)
+#' test_lmer <- lme4::lmer(mpg ~ hp + (1 | cyl), data = mtcars)
+#' test_glmer <- lme4::glmer(am ~ hp + (1 | cyl), data = mtcars, family = binomial)
 #'
 #' # Format linear mixed model term statistics
 #' format_stats(test_lmer, term = "hp")

README.Rmd

@@ -102,7 +102,7 @@ from `t.test()` and `wilcox.test()`, including one-sample, two-sample
 independent, and paired tests)
   - ANOVAs from `aov()`
   - Linear models from `lm()`, generalized linear models from `glm()`, linear 
-mixed models from `lme4::lmer()`, and generalized linear mixed models from
+mixed models from `lme4::lmer()` and `lmerTest::lmer()`, and generalized linear mixed models from
 `lme4::glmer()`
   - Bayes factors (output from [`{BayesFactor}`](https://cran.r-project.org/package=BayesFactor) package)
 * `format_summary()`: Means and error (calculates from vector or uses vector 

README.md

@@ -108,8 +108,8 @@ Fuel efficiency and engine displacement were highly correlated (r =
     two-sample independent, and paired tests)
   - ANOVAs from `aov()`
   - Linear models from `lm()`, generalized linear models from `glm()`,
-    linear mixed models from `lme4::lmer()`, and generalized linear
-    mixed models from `lme4::glmer()`
+    linear mixed models from `lme4::lmer()` and `lmerTest::lmer()`, and
+    generalized linear mixed models from `lme4::glmer()`
   - Bayes factors (output from
     [`{BayesFactor}`](https://cran.r-project.org/package=BayesFactor)
     package)

_pkgdown.yml

@@ -16,6 +16,7 @@ reference:
   - format_stats.easycorrelation
   - format_stats.htest
   - format_stats.lm
+  - format_stats.lmerModLmerTest
   - format_stats.merMod
 - title: Format statistical values
   contents:

tests/testthat/helper.R

@@ -21,6 +21,7 @@ test_lm <- lm(c ~ a, data = df)
 test_glm <- glm(d ~ a, data = df, family = binomial)
 test_lmer <- suppressMessages(lme4::lmer(c ~ a + (1 | e), data = df))
 test_glmer <- suppressMessages(lme4::glmer(d ~ a + (1 | e), data = df, family = binomial))
+test_lmer2 <- suppressMessages(lmerTest::lmer(c ~ a + (1 | e), data = df))
 test_bf <- BayesFactor::ttestBF(df$a, mu = 5)
 
 suppressPackageStartupMessages({