Merge pull request #257 from larmarange/datagrid

replace datagridcf() and deprecate tidy_marginal_means()

.github/workflows/R-CMD-historic-R-check.yaml

@@ -38,7 +38,7 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::rcmdcheck, emmeans=?ignore-before-r=4.3.0, gam=?ignore-before-r=4.0.0, rstan=?ignore-before-r=4.0.0, multgee=?ignore-before-r=4.0.0, VGAM=?ignore-before-r=4.0.0, glmmTMB=?ignore, effects=?ignore-before-r=4.3.0, survey=?ignore-before-r=4.1.0
+          extra-packages: any::rcmdcheck, emmeans=?ignore-before-r=4.3.0, gam=?ignore-before-r=4.0.0, rstan=?ignore-before-r=4.0.0, multgee=?ignore-before-r=4.0.0, VGAM=?ignore-before-r=4.0.0, glmmTMB=?ignore, effects=?ignore-before-r=4.3.0, survey=?ignore-before-r=4.1.0, lme4=?ignore-before-r=4.4.0, rstanarm=?ignore-before-r=4.4.0, Matrix=?ignore-before-r=4.4.0
           needs: check
 
       - uses: r-lib/actions/check-r-package@v2

DESCRIPTION

@@ -55,7 +55,7 @@ Suggests:
     lfe,
     lme4 (>= 1.1.28),
     logitr (>= 0.8.0),
-    marginaleffects (>= 0.10.0),
+    marginaleffects (>= 0.18.0),
     margins,
     MASS,
     mgcv,

NEWS.md

@@ -10,6 +10,17 @@
 
 - `biglmm::bigglm()` not supported anymore as `bigglmm` has been removed from
   CRAN
+
+**Deprecated functions**
+
+- `tidy_marginal_means()` is now deprecated, following deprecation of
+  `marginaleffects::marginal_means()`. Use instead `tidy_marginal_predictions()`
+  with the option `newdata = "marginalmeans"`.
+
+**Fixes**
+
+- `tidy_marginal_predictions()` has been updated to avoid the use of the
+  deprecated function `marginaleffects::datagridcf()` (#256)
 
 # broom.helpers 1.15.0
 

R/marginal_tidiers.R

@@ -412,7 +412,10 @@ tidy_avg_comparisons <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
 
 #' Marginal Means with `marginaleffects::marginal_means()`
 #'
-#' `r lifecycle::badge("experimental")`
+#' `r lifecycle::badge("deprecated")`
+#' This function is deprecated. Use instead `tidy_marginal_predictions()` with
+#' the option `newdata = "marginalmeans"`.
+#'
 #' Use `marginaleffects::marginal_means()` to estimate marginal means and
 #' return a tibble tidied in a way that it could be used by `broom.helpers`
 #' functions. See `marginaleffects::marginal_means()()` for a list of supported
@@ -451,6 +454,13 @@ tidy_avg_comparisons <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
 #' mod2 <- lm(Petal.Length ~ poly(Petal.Width, 2) + Species, data = iris)
 #' tidy_marginal_means(mod2)
 tidy_marginal_means <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
+  lifecycle::deprecate_warn(
+    when = "1.16.0",
+    what = "tidy_marginal_means()",
+    with = "tidy_marginal_predictions()",
+    details = "Specify `newdata = \"marginalmeans\"`."
+  )
+
   .assert_package("marginaleffects")
 
   dots <- rlang::dots_list(...)
@@ -1029,7 +1039,8 @@ tidy_marginal_contrasts <- function(x, variables_list = "auto",
   if (!is.null(variables$by) && is.null(dots$newdata)) {
     args <- variables$by
     args$model <- dots$model
-    dots$newdata <- do.call(marginaleffects::datagridcf, args)
+    args$grid_type <- "counterfactual"
+    dots$newdata <- do.call(marginaleffects::datagrid, args)
   }
 
   if (!is.null(variables$by) && identical(dots$newdata, "mean")) {

tests/testthat/test-attach_and_detach.R

@@ -33,4 +33,3 @@ test_that("tidy_and_attach() handles models without exponentiate arguments", {
   expect_error(mod %>% tidy_and_attach(exponentiate = TRUE))
   expect_error(mod %>% tidy_and_attach(), NA)
 })
-

tests/testthat/test-marginal_tidiers.R

@@ -347,31 +347,8 @@ test_that("tidy_marginal_means()", {
   skip_if_not_installed("marginaleffects")
 
   mod <- lm(Petal.Length ~ Petal.Width * Species + Sepal.Length, data = iris)
-  expect_error(
-    t <- tidy_marginal_means(mod),
-    NA
-  )
-  expect_error(
-    tidy_marginal_means(mod, exponentiate = TRUE)
-  )
-  expect_error(
-    res <- tidy_plus_plus(mod, tidy_fun = tidy_marginal_means),
-    NA
-  )
-  expect_equal(
-    nrow(res),
-    nrow(t)
-  )
-  expect_equal(
-    attr(res, "coefficients_label"),
-    "Marginal Means"
-  )
-  expect_error(
-    tidy_plus_plus(
-      mod,
-      tidy_fun = tidy_marginal_means,
-      add_pairwise_contrasts = TRUE
-    )
+  lifecycle::expect_deprecated(
+    tidy_marginal_means(mod)
   )
 })
 
@@ -481,12 +458,6 @@ test_that("Marginal tidiers works with nnet::multinom() models", {
   )
   expect_true("y.level" %in% names(res))
 
-  expect_error(
-    res <- tidy_marginal_means(mod),
-    NA
-  )
-  expect_true("y.level" %in% names(res))
-
   expect_error(
     res <- tidy_marginal_predictions(mod),
     NA
@@ -547,12 +518,6 @@ test_that("Marginal tidiers works with MASS::polr() models", {
   )
   expect_true("y.level" %in% names(res))
 
-  expect_error(
-    suppressMessages(res <- tidy_marginal_means(mod)),
-    NA
-  )
-  expect_true("y.level" %in% names(res))
-
   expect_error(
     suppressMessages(res <- tidy_marginal_predictions(mod)),
     NA
@@ -611,12 +576,6 @@ test_that("Marginal tidiers works with ordinal::clm() models", {
   )
   expect_true("y.level" %in% names(res))
 
-  expect_error(
-    res <- tidy_marginal_means(mod),
-    NA
-  )
-  expect_true("y.level" %in% names(res))
-
   expect_error(
     res <- tidy_marginal_predictions(mod),
     NA

vignettes/articles/marginal_tidiers.Rmd

@@ -277,6 +277,7 @@ predict(mod, newdata = dB, type = "link") %>%
   mean() %>%
   b$linkinv()
 ```
+
 We can use `tidy_marginal_predictions()` to get average marginal predictions for all variables and `plot_marginal_predictions()` for a visual representation.
 
 ```{r}
@@ -327,7 +328,7 @@ pred <- predictions(mod, newdata = "marginalmeans")
 pred
 ```
 
-As we can see, `pred` contains 8 rows, one for each combination of `trt` (2 modalities) and `stage` (4 modalities). `age` is fixed at his mean (`mean(d$age)`) as well as `marker`.
+As we can see, `pred` contains 8 rows, one for each combination of `trt` (2 modalities) and `stage` (4 modalities). `age` is fixed at its mean (`mean(d$age)`) as well as `marker`.
 
 Let's compute the average predictions for each value of `stage`.
 
@@ -343,22 +344,19 @@ We can check that we obtain the same estimates as with `emmeans::emmeans()`.
 emmeans::emmeans(mod, "stage", type = "response")
 ```
 
-The function `marginaleffects::marginal_means()` allows to compute directly marginal means of all categorical variables.
-
-```{r}
-marginal_means(mod)
-```
+These estimates could be computed, for each categorical variable, with `marginaleffects::prediction()` using `datagrid(grid_type = "balanced")`[^1].
 
-`{broom.helpers}` provides a `tidy_marginal_means()` tidier.
+[^1]: The function `marginaleffects::marginalmeans()` is now deprecated.
 
 ```{r}
-mod %>%
-  tbl_regression(
-    tidy_fun = tidy_marginal_means,
-    estimate_fun = scales::label_percent(accuracy = .1)
-  ) %>%
-  modify_column_hide("p.value") %>%
-  bold_labels()
+predictions(mod,
+  by = "trt",
+  newdata = datagrid(grid_type = "balanced")
+)
+predictions(mod,
+  by = "stage",
+  newdata = datagrid(grid_type = "balanced")
+)
 ```
 
 Marginal means are defined only for categorical variables. However, we can define **marginal predictions at marginal means** for both continuous and categorical variables, calling `tidy_marginal_predictions()` with the option `newdata = "marginalmeans"`. For categorical variables, marginal predictions at marginal means will be equal to marginal means.
@@ -578,8 +576,11 @@ In our model, we defined an interaction between `trt` and `marker`. Therefore, w
 avg_comparisons(
   mod,
   variables = list(marker = 1),
-  newdata = datagridcf(trt = unique),
-  by = "trt",
+  newdata = datagrid(
+    trt = unique,
+    grid_type = "counterfactual"
+  ),
+  by = "trt"
 )
 ```
 
@@ -709,9 +710,9 @@ mod_alt %>%
 
 ### Marginal Effects at the Mean (MEM)
 
-For marginal effects at the mean[^1], simple use `newdata = "mean"`.
+For marginal effects at the mean[^2], simple use `newdata = "mean"`.
 
-[^1]: More precisely, `marginaleffects::marginaleffects()` use the mean of continuous variables and the mode of categorical variables.
+[^2]: More precisely, `marginaleffects::marginaleffects()` use the mean of continuous variables and the mode of categorical variables.
 
 ```{r}
 mod %>%