soft-deprecate margins tidiers (closes #1200)

DESCRIPTION

@@ -596,7 +596,6 @@ Suggests:
     lmodel2,
     lmtest (>= 0.9.38),
     maps,
-    margins,
     MASS,
     mclust,
     mediation,

NEWS.md

@@ -1,8 +1,10 @@
 # broom (development version)
 
-* While this broom release contains no changes to the `tidy.survfit()` method for objects from the survival package, the package has bumped the minimum required version for survival. Before survival 3.6-4, `tidy.survfit()` propagated "inconsistent" `n.censor` values from survival for multi-state models (#1195). 
+* Soft-deprecated tidiers for margins, lsmeans, and emmeans. Each package has been removed from Suggests and is no longer tested---their tidiers will raise a deprecation warning but return the same results as before.
+     - margins was archived from CRAN. In the case that the package is back on CRAN before the next package release, broom will once again Suggest and test support for the package (#1200).
+     - lsmeans and emmeans have a dependency requiring R 4.3.0 or higher. To maintain compatibility with at least 4 previous minor versions of R, broom won't test support for these packages until the release of R 4.7.x (or until lsmeans and emmeans are compatible with the R version 4 minor releases previous, #1193).
 
-* Removed lsmeans and emmeans as Suggested packages as the packages have a dependency requiring R 4.3.0 or higher. To maintain compatibility with at least 4 previous minor versions of R, broom won't test support for these packages until the release of R 4.7.x (or until lsmeans and emmeans are compatible with the R version 4 minor releases previous, #1193).
+* While this broom release contains no changes to the `tidy.survfit()` method for objects from the survival package, the package has bumped the minimum required version for survival. Before survival 3.6-4, `tidy.survfit()` propagated "inconsistent" `n.censor` values from survival for multi-state models (#1195). 
 
 * Moved forward with deprecation of tidiers for objects from the sp package. See resources linked in [tidymodels/broom#1142](https://github.com/tidymodels/broom/issues/1142) for more information on migration from retiring spatial packages.
 

R/margins-tidiers.R

@@ -1,7 +1,7 @@
 #' @templateVar class margins
 #' @template title_desc_tidy
 #'
-#' @param x A `margins` object returned from [margins::margins()].
+#' @param x A `margins` object returned from `margins::margins()`.
 #' @template param_confint
 #' @template param_unused_dots
 #'
@@ -14,64 +14,70 @@
 #'   Similarly, an `augment.margins()` method is not currently supported, but
 #'   users can simply run the underlying model to obtain the same information.
 #'
-#' @examplesIf rlang::is_installed("margins")
-#'
-#' # load libraries for models and data
-#' library(margins)
-#'
-#' # example 1: logit model
-#' mod_log <- glm(am ~ cyl + hp + wt, data = mtcars, family = binomial)
-#'
-#' # get tidied "naive" model coefficients
-#' tidy(mod_log)
-#'
-#' # convert to marginal effects with margins()
-#' marg_log <- margins(mod_log)
-#'
-#' # get tidied marginal effects
-#' tidy(marg_log)
-#' tidy(marg_log, conf.int = TRUE)
-#'
-#' # requires running the underlying model again. quick for this example
-#' glance(marg_log)
-#'
-#' # augmenting `margins` outputs isn't supported, but
-#' # you can get the same info by running on the underlying model
-#' augment(mod_log)
-#'
-#' # example 2: threeway interaction terms
-#' mod_ie <- lm(mpg ~ wt * cyl * disp, data = mtcars)
-#'
-#' # get tidied "naive" model coefficients
-#' tidy(mod_ie)
-#'
-#' # convert to marginal effects with margins()
-#' marg_ie0 <- margins(mod_ie)
-
-#' # get tidied marginal effects
-#' tidy(marg_ie0)
-#' glance(marg_ie0)
-#'
-#' # marginal effects evaluated at specific values of a variable (here: cyl)
-#' marg_ie1 <- margins(mod_ie, at = list(cyl = c(4,6,8)))
-#'
-#' # summarize model fit with tidiers
-#' tidy(marg_ie1)
-#'
-#' # marginal effects of one interaction variable (here: wt), modulated at
-#' # specific values of the two other interaction variables (here: cyl and drat)
-#' marg_ie2 <- margins(mod_ie,
-#'                     variables = "wt",
-#'                     at = list(cyl = c(4,6,8), drat = c(3, 3.5, 4)))
-#'
-#' # summarize model fit with tidiers
-#' tidy(marg_ie2)
-#'
+# examples no longer supplied, see #1200
+# @examplesIf rlang::is_installed("margins")
+#
+# # load libraries for models and data
+# library(margins)
+#
+# # example 1: logit model
+# mod_log <- glm(am ~ cyl + hp + wt, data = mtcars, family = binomial)
+#
+# # get tidied "naive" model coefficients
+# tidy(mod_log)
+#
+# # convert to marginal effects with margins()
+# marg_log <- margins(mod_log)
+#
+# # get tidied marginal effects
+# tidy(marg_log)
+# tidy(marg_log, conf.int = TRUE)
+#
+# # requires running the underlying model again. quick for this example
+# glance(marg_log)
+#
+# # augmenting `margins` outputs isn't supported, but
+# # you can get the same info by running on the underlying model
+# augment(mod_log)
+#
+# # example 2: threeway interaction terms
+# mod_ie <- lm(mpg ~ wt * cyl * disp, data = mtcars)
+#
+# # get tidied "naive" model coefficients
+# tidy(mod_ie)
+#
+# # convert to marginal effects with margins()
+# marg_ie0 <- margins(mod_ie)
+# # get tidied marginal effects
+# tidy(marg_ie0)
+# glance(marg_ie0)
+#
+# # marginal effects evaluated at specific values of a variable (here: cyl)
+# marg_ie1 <- margins(mod_ie, at = list(cyl = c(4,6,8)))
+#
+# # summarize model fit with tidiers
+# tidy(marg_ie1)
+#
+# # marginal effects of one interaction variable (here: wt), modulated at
+# # specific values of the two other interaction variables (here: cyl and drat)
+# marg_ie2 <- margins(mod_ie,
+#                     variables = "wt",
+#                     at = list(cyl = c(4,6,8), drat = c(3, 3.5, 4)))
+#
+# # summarize model fit with tidiers
+# tidy(marg_ie2)
+#
 #' @export
 #' @aliases margins_tidiers
 #' @family margins tidiers
-#' @seealso [tidy()], [margins::margins()]
+#' @seealso [tidy()], `margins::margins()`
 tidy.margins <- function(x, conf.int = FALSE, conf.level = 0.95, ...) {
+  lifecycle::deprecate_soft(
+    "1.0.6", 
+    I("tidying a `margins` object"), 
+    details = "margins was removed from CRAN in April 2024 and its tidiers are thus untested."
+  )
+
   check_ellipses("exponentiate", "tidy", "margins", ...)
 
   ret <- as_tibble(summary(x, level = conf.level))
@@ -138,6 +144,12 @@ tidy.margins <- function(x, conf.int = FALSE, conf.level = 0.95, ...) {
 #'
 #' @export
 glance.margins <- function(x, ...) {
+  lifecycle::deprecate_soft(
+    "1.0.6", 
+    I("tidying a `margins` object"), 
+    details = "margins was removed from CRAN in April 2024 and its tidiers are thus untested."
+  )
+
   orig_mod_call <- attributes(x)$call
   ret <- broom::glance(eval(orig_mod_call), ...)
   return(ret)

tests/testthat/test-margins.R

@@ -5,16 +5,18 @@ skip_on_cran()
 skip_if_not_installed("modeltests")
 library(modeltests)
 
-skip_if_not_installed("margins")
+skip("margins not available (#1200)")
+# skip_if_not_installed("margins")
+# library(margins)
 
 fit1 <- glm(am ~ cyl + hp + wt, data = mtcars, family = binomial)
-marg1 <- margins::margins(fit1)
+marg1 <- margins(fit1)
 
 fit2 <- lm(mpg ~ wt * cyl * disp, data = mtcars)
-marg2a <- margins::margins(fit2)
-marg2b <- margins::margins(fit2, variable = "wt")
-marg2c <- margins::margins(fit2, at = list(cyl = c(4, 6, 8)))
-marg2d <- margins::margins(fit2, variables = "wt", at = list(cyl = c(4, 6, 8), drat = c(3, 3.5, 4)))
+marg2a <- margins(fit2)
+marg2b <- margins(fit2, variable = "wt")
+marg2c <- margins(fit2, at = list(cyl = c(4, 6, 8)))
+marg2d <- margins(fit2, variables = "wt", at = list(cyl = c(4, 6, 8), drat = c(3, 3.5, 4)))
 
 test_that("margins tidier arguments", {
   check_arguments(tidy.margins)