Merge pull request #285 from larmarange/marginal_means

Hard deprecation of `tidy_marginal_means()`

DESCRIPTION

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

NEWS.md

@@ -1,5 +1,9 @@
 # broom.helpers (development version)
 
+**Deprecated function**
+
+- `tidy_marginal_means()` is now hard deprecated (#284)
+
 # broom.helpers 1.18.0
 
 **New supported models**
@@ -67,7 +71,7 @@
 
 - `tidy_marginal_means()` is now deprecated, following deprecation of
   `marginaleffects::marginal_means()`. Use instead `tidy_marginal_predictions()`
-  with the option `newdata = "marginalmeans"`.
+  with the option `newdata = "balanced"`.
 - `tidy_margins()` is now indicated as superseded and may be deprecated if
   `margins` is removed from CRAN. `tidy_avg_slopes()` could be used as an
   alternative. (#252)

R/custom_tidiers.R

@@ -255,7 +255,6 @@ tidy_broom <- function(x, ...) {
 
 #' Tidy a `multgee` model
 #'
-#' `r lifecycle::badge("experimental")`
 #' A tidier for models generated with `multgee::nomLORgee()` or `multgee::ordLORgee()`.
 #' Term names will be updated to be consistent with generic models. The original
 #' term names are preserved in an `"original_term"` column.
@@ -337,7 +336,6 @@ tidy_multgee <- function(x, conf.int = TRUE, conf.level = .95, ...) {
 
 #' Tidy a `zeroinfl` or a `hurdle` model
 #'
-#' `r lifecycle::badge("experimental")`
 #' A tidier for models generated with `pscl::zeroinfl()` or `pscl::hurdle()`.
 #' Term names will be updated to be consistent with generic models. The original
 #' term names are preserved in an `"original_term"` column.

R/marginal_tidiers.R

@@ -62,7 +62,6 @@ tidy_margins <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
 
 #' Marginal Predictions at the mean with `effects::allEffects()`
 #'
-#' `r lifecycle::badge("experimental")`
 #' Use `effects::allEffects()` to estimate marginal predictions and
 #' return a tibble tidied in a way that it could be used by `broom.helpers`
 #' functions.
@@ -178,7 +177,6 @@ effpoly_to_df <- function(x) {
 
 #' Marginal Predictions with `ggeffects::ggpredict()`
 #'
-#' `r lifecycle::badge("experimental")`
 #' Use `ggeffects::ggpredict()` to estimate marginal predictions
 #' and return a tibble tidied in a way that it could be used by `broom.helpers`
 #' functions.
@@ -250,7 +248,6 @@ tidy_ggpredict <- function(x, conf.int = TRUE, conf.level = .95, ...) {
 
 #' Marginal Slopes / Effects with `marginaleffects::avg_slopes()`
 #'
-#' `r lifecycle::badge("experimental")`
 #' Use `marginaleffects::avg_slopes()` to estimate marginal slopes / effects and
 #' return a tibble tidied in a way that it could be used by `broom.helpers`
 #' functions. See `marginaleffects::avg_slopes()` for a list of supported
@@ -327,7 +324,7 @@ tidy_avg_slopes <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
   attr(res, "coefficients_type") <- dplyr::case_when(
     is.null(dots$newdata) ~ "marginal_effects_average",
     isTRUE(dots$newdata == "mean") ~ "marginal_effects_at_mean",
-    isTRUE(dots$newdata == "marginalmeans") ~ "marginal_effects_at_marginalmeans",
+    isTRUE(dots$newdata == "balanced") ~ "marginal_effects_at_marginalmeans",
     TRUE ~ "marginal_effects"
   )
   attr(res, "skip_add_reference_rows") <- TRUE
@@ -336,7 +333,6 @@ tidy_avg_slopes <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
 
 #' Marginal Contrasts with `marginaleffects::avg_comparisons()`
 #'
-#' `r lifecycle::badge("experimental")`
 #' Use `marginaleffects::avg_comparisons()` to estimate marginal contrasts and
 #' return a tibble tidied in a way that it could be used by `broom.helpers`
 #' functions. See `marginaleffects::avg_comparisons()` for a list of supported
@@ -421,98 +417,38 @@ tidy_avg_comparisons <- function(x, conf.int = TRUE, conf.level = 0.95, ...) {
   attr(res, "coefficients_type") <- dplyr::case_when(
     is.null(dots$newdata) ~ "marginal_contrasts_average",
     isTRUE(dots$newdata == "mean") ~ "marginal_contrasts_at_mean",
-    isTRUE(dots$newdata == "marginalmeans") ~ "marginal_contrasts_at_marginalmeans",
+    isTRUE(dots$newdata == "balanced") ~ "marginal_contrasts_at_marginalmeans",
     TRUE ~ "marginal_contrasts"
   )
   attr(res, "skip_add_reference_rows") <- TRUE
   res |> dplyr::as_tibble()
 }
 
-#' Marginal Means with `marginaleffects::marginal_means()`
+#' Marginal Means with deprecated `marginaleffects::marginal_means()`
 #'
 #' `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
-#' models.
-#' @details
-#' `marginaleffects::marginal_means()` estimate marginal means:
-#' adjusted predictions, averaged across a grid of categorical predictors,
-#' holding other numeric predictors at their means. Please refer to the
-#' documentation page of `marginaleffects::marginal_means()`. Marginal means
-#' are defined only for categorical variables.
-#'
-#' For more information, see `vignette("marginal_tidiers", "broom.helpers")`.
+#' This function is deprecated. `marginal_means()` is not anymore exported
+#' by `marginaleffects`. Use instead `tidy_marginal_predictions()` with
+#' the option `newdata = "balanced"`.
 #' @param x (a model object, e.g. `glm`)\cr
 #' A model to be tidied.
 #' @param conf.int (`logical`)\cr
 #' Whether or not to include a confidence interval in the tidied output.
 #' @param conf.level (`numeric`)\cr
 #' The confidence level to use for the confidence interval (between `0` ans `1`).
-#' @param ... Additional parameters passed to
-#' `marginaleffects::marginal_means()`.
-#' @family marginal_tieders
-#' @seealso `marginaleffects::marginal_means()`
+#' @param ... Additional parameters.
 #' @export
-#' @examplesIf interactive()
-#' # Average Marginal Means
-#'
-#' df <- Titanic |>
-#'   dplyr::as_tibble() |>
-#'   tidyr::uncount(n) |>
-#'   dplyr::mutate(Survived = factor(Survived, c("No", "Yes")))
-#' mod <- glm(
-#'   Survived ~ Class + Age + Sex,
-#'   data = df, family = binomial
-#' )
-#' tidy_marginal_means(mod)
-#' tidy_plus_plus(mod, tidy_fun = tidy_marginal_means)
-#'
-#' 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",
+  lifecycle::deprecate_stop(
+    when = "1.19.0",
     what = "tidy_marginal_means()",
     with = "tidy_marginal_predictions()",
-    details = "Specify `newdata = \"marginalmeans\"`."
+    details = "Specify `newdata = \"balanced\"`."
   )
-
-  .assert_package("marginaleffects")
-
-  dots <- rlang::dots_list(...)
-  if (isTRUE(dots$exponentiate)) {
-    cli::cli_abort("{.arg exponentiate = TRUE} is not relevant for {.fun broom.helpers::tidy_marginal_means}.") # nolint
-  }
-  dots$exponentiate <- NULL
-  dots$conf_level <- conf.level
-  dots$model <- x
-
-  res <- do.call(marginaleffects::marginal_means, dots) |>
-    dplyr::rename(
-      variable = "term",
-      term = "value"
-    ) |>
-    dplyr::mutate(term = as.character(.data$term))
-
-  # multinomial models
-  if ("group" %in% names(res)) {
-    res <- res |>
-      dplyr::rename(y.level = "group") |>
-      dplyr::relocate("y.level")
-  }
-
-  attr(res, "coefficients_type") <- "marginal_means"
-  attr(res, "skip_add_reference_rows") <- TRUE
-  res |> dplyr::as_tibble()
 }
 
 #' Marginal Predictions with `marginaleffects::avg_predictions()`
 #'
-#' `r lifecycle::badge("experimental")`
 #' Use `marginaleffects::avg_predictions()` to estimate marginal predictions for
 #' each variable of a model and return a tibble tidied in a way that it could
 #' be used by `broom.helpers` functions.
@@ -673,7 +609,7 @@ tidy_marginal_predictions <- function(x, variables_list = "auto",
   attr(res, "coefficients_type") <- dplyr::case_when(
     is.null(dots$newdata) ~ "marginal_predictions_average",
     isTRUE(dots$newdata == "mean") ~ "marginal_predictions_at_mean",
-    isTRUE(dots$newdata == "marginalmeans") ~ "marginal_predictions_at_marginalmeans",
+    isTRUE(dots$newdata == "balanced") ~ "marginal_predictions_at_marginalmeans",
     TRUE ~ "marginal_predictions"
   )
   attr(res, "skip_add_reference_rows") <- TRUE
@@ -877,7 +813,6 @@ plot_marginal_predictions <- function(x, variables_list = "auto",
 
 #' Marginal Contrasts with `marginaleffects::avg_comparisons()`
 #'
-#' `r lifecycle::badge("experimental")`
 #' Use `marginaleffects::avg_comparisons()` to estimate marginal contrasts for
 #' each variable of a model and return a tibble tidied in a way that it could
 #' be used by `broom.helpers` functions.
@@ -1046,7 +981,7 @@ tidy_marginal_contrasts <- function(x, variables_list = "auto",
   attr(res, "coefficients_type") <- dplyr::case_when(
     is.null(dots$newdata) ~ "marginal_contrasts_average",
     isTRUE(dots$newdata == "mean") ~ "marginal_contrasts_at_mean",
-    isTRUE(dots$newdata == "marginalmeans") ~ "marginal_contrasts_at_marginalmeans",
+    isTRUE(dots$newdata == "balanced") ~ "marginal_contrasts_at_marginalmeans",
     TRUE ~ "marginal_contrasts"
   )
   attr(res, "skip_add_reference_rows") <- TRUE

R/model_get_pairwise_contrasts.R

@@ -17,11 +17,10 @@
 #' List of additional parameter to pass to
 #' [emmeans::emmeans()] when computing pairwise contrasts.
 #' @details
-#' `r lifecycle::badge("experimental")`
 #' For `pscl::zeroinfl()` and `pscl::hurdle()` models, pairwise contrasts are
 #' computed separately for each component, using `mode = "count"` and
 #' `mode = "zero"` (see documentation of `emmeans`) and a component column
-#' is added to the results. This support is still experimental.
+#' is added to the results.
 #' @family model_helpers
 #' @export
 #' @examplesIf interactive()

R/tidy_add_pairwise_contrasts.R

@@ -1,6 +1,5 @@
 #' Add pairwise contrasts for categorical variables
 #'
-#' `r lifecycle::badge("experimental")`
 #' Computes pairwise contrasts with [emmeans::emmeans()] and add them to the
 #' results tibble. Works only with models supported by `emmeans`, see
 #' `vignette("models", package = "emmeans")`.
@@ -9,7 +8,6 @@
 #' If the `contrasts` column is not yet available in `x`,
 #' [tidy_add_contrasts()] will be automatically applied.
 #'
-#' `r lifecycle::badge("experimental")`
 #' For multi-components models, such as zero-inflated Poisson or beta
 #' regression, support of pairwise contrasts is still experimental.
 #'

_pkgdown.yml

@@ -66,7 +66,6 @@ reference:
       - tidy_marginal_contrasts
       - tidy_avg_slopes
       - tidy_margins
-      - tidy_marginal_means
 
   - title: Get information from model objects
   - contents:
@@ -82,3 +81,6 @@ reference:
       - starts_with("\\.")
       - seq_range
 
+  - title: Deprecated
+  - contents:
+      - tidy_marginal_means

data-raw/DATASET.R

@@ -47,8 +47,8 @@ supported_models <-
     "`fixest::feols()`", "May fail with R <= 4.0.",
     "`fixest::feNmlm()`", "May fail with R <= 4.0.",
     "`logitr::logitr()`", "Requires logitr >= 0.8.0",
-    "`multgee::nomLORgee()`", "Experimental support. Use `tidy_multgee()` as `tidy_fun`.",
-    "`multgee::ordLORgee()`", "Experimental support. Use `tidy_multgee()` as `tidy_fun`.",
+    "`multgee::nomLORgee()`", "Use `tidy_multgee()` as `tidy_fun`.",
+    "`multgee::ordLORgee()`", "Use `tidy_multgee()` as `tidy_fun`.",
     "`mmrm::mmrm()`", "",
     "`pscl::zeroinfl()`", "Use `tidy_zeroinfl()` as `tidy_fun`.",
     "`pscl::hurdle()`", "Use `tidy_zeroinfl()` as `tidy_fun`.",