Deprecate user-facing size and fatten arguments for ggplot2 4.0 compatibility

DESCRIPTION

@@ -34,6 +34,7 @@ Imports:
     ggplot2 (>= 3.4.0),
     ggridges (>= 0.5.5),
     glue,
+    lifecycle,
     posterior,
     reshape2,
     rlang (>= 0.3.0),

NAMESPACE

@@ -226,3 +226,6 @@ importFrom(dplyr,top_n)
 importFrom(dplyr,ungroup)
 importFrom(dplyr,vars)
 importFrom(ggplot2,"%+replace%")
+importFrom(lifecycle,deprecate_warn)
+importFrom(lifecycle,deprecated)
+importFrom(lifecycle,is_present)

NEWS.md

@@ -1,5 +1,14 @@
 # bayesplot (development version)
 
+* Deprecate user-facing `size` arguments that controlled line width in favor of
+  `linewidth` across all plotting functions. The `size` argument still works but
+  emits a deprecation warning. (#408)
+* Deprecate the `fatten` argument in `ppc_intervals()`, `ppd_intervals()`,
+  `ppc_loo_intervals()`, `ppc_bars()`, and their grouped variants. Point size in
+  `geom_pointrange()` is now controlled directly by `size`, matching ggplot2 4.0
+  semantics. The default `size` has been changed from 1 to 2.5 to preserve the
+  previous visual appearance (old `size * fatten`). (#408)
+* Added `lifecycle` as an imported dependency for deprecation infrastructure.
 * Documentation added for all exported `*_data()` functions (#209)
 * Improved documentation for `binwidth`, `bins`, and `breaks` arguments to clarify they are passed to `ggplot2::geom_area()` and `ggdist::stat_dots()` in addition to `ggplot2::geom_histogram()`
 * Improved documentation for `freq` argument to clarify it applies to frequency polygons in addition to histograms

R/bayesplot-package.R

@@ -4,6 +4,7 @@
 #' @aliases bayesplot
 #'
 #' @import ggplot2 stats rlang
+#' @importFrom lifecycle deprecated deprecate_warn is_present
 #' @importFrom dplyr %>% summarise group_by select
 #'
 #' @description

R/helpers-shared.R

@@ -45,6 +45,52 @@ check_ignored_arguments <- function(..., ok_args = character()) {
   }
 }
 
+#' Handle size -> linewidth deprecation
+#'
+#' @param size User's `size` argument (deprecated for lines).
+#' @param linewidth User's `linewidth` argument (replacement).
+#' @param default_linewidth Default linewidth value if neither is specified.
+#' @param calling_fn Name of the calling function for the deprecation message.
+#' @return The resolved linewidth value.
+#' @noRd
+resolve_linewidth <- function(size, linewidth, default_linewidth, calling_fn = NULL) {
+  if (!is.null(size)) {
+    lifecycle::deprecate_warn(
+      when = "1.16.0",
+      what = paste0(calling_fn %||% "fn", "(size)"),
+      with = paste0(calling_fn %||% "fn", "(linewidth)")
+    )
+    return(size)
+  }
+  linewidth %||% default_linewidth
+}
+
+
+#' Handle fatten deprecation
+#'
+#' @param fatten User's `fatten` argument (deprecated).
+#' @param size User's `size` argument.
+#' @param default_size Default size when neither `fatten` nor `size` is given.
+#' @param calling_fn Name of the calling function for the deprecation message.
+#' @return The resolved point `size` value.
+#' @noRd
+resolve_fatten <- function(fatten, size, default_size, calling_fn = NULL) {
+  if (!lifecycle::is_present(fatten)) {
+    return(size %||% default_size)
+  }
+
+  lifecycle::deprecate_warn(
+    when = "1.16.0",
+    what = paste0(calling_fn %||% "fn", "(fatten)"),
+    details = paste0(
+      "The point size is now controlled directly by `size`. ",
+      "The `fatten` argument will be removed in a future release."
+    )
+  )
+  size %||% default_size
+}
+
+
 #' Validate bounds passed to stat_density/geom_density wrappers
 #' @noRd
 validate_density_bounds <- function(bounds) {

R/mcmc-diagnostics.R

@@ -10,8 +10,9 @@
 #'
 #' @template args-hist
 #' @param size Optional values to override [ggplot2::geom_point()]'s
-#'   default size (for `mcmc_rhat()`, `mcmc_neff()`) or
-#'   [ggplot2::geom_line()]'s default line width (for `mcmc_acf()`).
+#'   default size (for `mcmc_rhat()`, `mcmc_neff()`).
+#' @param linewidth Optional value to override [ggplot2::geom_line()]'s
+#'   default line width (for `mcmc_acf()`).
 #' @param ... Currently ignored.
 #'
 #' @template return-ggplot-or-data
@@ -322,15 +323,17 @@ mcmc_acf <-
            ...,
            facet_args = list(),
            lags = 20,
-           size = NULL) {
+           size = NULL,
+           linewidth = NULL) {
     check_ignored_arguments(...)
+    linewidth <- resolve_linewidth(size, linewidth, default_linewidth = NULL, calling_fn = "mcmc_acf")
     .mcmc_acf(
       x,
       pars = pars,
       regex_pars = regex_pars,
       facet_args = facet_args,
       lags = lags,
-      size = size,
+      linewidth = linewidth,
       style = "line"
     )
   }
@@ -514,15 +517,15 @@ drop_NAs_and_warn <- function(x) {
 }
 
 # Autocorrelation plot (either bar or line)
-# @param size passed to geom_line() if style="line"
+# @param linewidth passed to geom_line() if style="line"
 .mcmc_acf <-
   function(x,
            pars = character(),
            regex_pars = character(),
            facet_args = list(),
            lags = 25,
            style = c("bar", "line"),
-           size = NULL) {
+           linewidth = NULL) {
 
     style <- match.arg(style)
     x <- prepare_mcmc_array(x, pars, regex_pars)
@@ -561,7 +564,7 @@ drop_NAs_and_warn <- function(x) {
         ) +
         do.call(
           "geom_line",
-          args = c(list(color = get_color("d")), linewidth = size)
+          args = c(list(color = get_color("d")), linewidth = linewidth)
         )
     }
 

R/mcmc-parcoord.R

@@ -13,7 +13,7 @@
 #' @template args-regex_pars
 #' @template args-transformations
 #' @param ... Currently ignored.
-#' @param size,alpha Arguments passed on to [ggplot2::geom_line()].
+#' @param size,alpha,linewidth Arguments passed on to [ggplot2::geom_line()].
 #' @param np For models fit using [NUTS] (more generally,
 #'   any [symplectic integrator](https://en.wikipedia.org/wiki/Symplectic_integrator)),
 #'   an optional data frame providing NUTS diagnostic information. The data
@@ -114,11 +114,13 @@ mcmc_parcoord <-
            regex_pars = character(),
            transformations = list(),
            ...,
-           size = 0.2,
+           size = NULL,
+           linewidth = 0.2,
            alpha = 0.3,
            np = NULL,
            np_style = parcoord_style_np()) {
     check_ignored_arguments(...)
+    linewidth <- resolve_linewidth(size, linewidth, default_linewidth = 0.2, calling_fn = "mcmc_parcoord")
     stopifnot(inherits(np_style, "nuts_style"))
 
     data <-
@@ -142,7 +144,7 @@ mcmc_parcoord <-
       group = factor(.data$Draw)
     )) +
       geom_line(
-        linewidth = size,
+        linewidth = linewidth,
         alpha = alpha,
         color = get_color("dh")
       ) +

R/ppc-censoring.R

@@ -15,8 +15,8 @@
 #' @family PPCs
 #'
 #' @template args-y-yrep
-#' @param size,alpha Passed to the appropriate geom to control the appearance of
-#'   the `yrep` distributions.
+#' @param size,alpha,linewidth Passed to the appropriate geom to control the
+#'   appearance of the `yrep` distributions.
 #' @param ... Currently only used internally.
 #'
 #' @template return-ggplot
@@ -103,10 +103,12 @@ ppc_km_overlay <- function(
   status_y,
   left_truncation_y = NULL,
   extrapolation_factor = 1.2,
-  size = 0.25,
+  size = NULL,
+  linewidth = 0.25,
   alpha = 0.7
 ) {
   check_ignored_arguments(..., ok_args = "add_group")
+  linewidth <- resolve_linewidth(size, linewidth, default_linewidth = 0.25, calling_fn = "ppc_km_overlay")
   add_group <- list(...)$add_group
 
   suggested_package("survival")
@@ -172,7 +174,7 @@ ppc_km_overlay <- function(
   }
 
   fsf$is_y_color <- as.factor(sub("\\[rep\\] \\(.*$", "rep", sub("^italic\\(y\\)", "y", fsf$strata)))
-  fsf$is_y_linewidth <- ifelse(fsf$is_y_color == "yrep", size, 1)
+  fsf$is_y_linewidth <- ifelse(fsf$is_y_color == "yrep", linewidth, 1)
   fsf$is_y_alpha <- ifelse(fsf$is_y_color == "yrep", alpha, 1)
 
   max_time_y <- max(y, na.rm = TRUE)
@@ -225,7 +227,8 @@ ppc_km_overlay_grouped <- function(
   status_y,
   left_truncation_y = NULL,
   extrapolation_factor = 1.2,
-  size = 0.25,
+  size = NULL,
+  linewidth = 0.25,
   alpha = 0.7
 ) {
   check_ignored_arguments(...)
@@ -238,6 +241,7 @@ ppc_km_overlay_grouped <- function(
     status_y = status_y,
     left_truncation_y = left_truncation_y,
     size = size,
+    linewidth = linewidth,
     alpha = alpha,
     extrapolation_factor = extrapolation_factor
   )

R/ppc-discrete.R

@@ -18,10 +18,12 @@
 #'   of the expected counts.)
 #' @param width For bar plots only, passed to [ggplot2::geom_bar()] to control
 #'   the bar width.
-#' @param size,fatten,linewidth For bar plots, `size`, `fatten`, and `linewidth`
-#'   are passed to [ggplot2::geom_pointrange()] to control the appearance of the
-#'   `yrep` points and intervals. For rootograms `size` is passed to
-#'   [ggplot2::geom_line()] and [ggplot2::geom_pointrange()].
+#' @param size,linewidth For bar plots, `size` and `linewidth` are passed to
+#'   [ggplot2::geom_pointrange()] to control the appearance of the `yrep` points
+#'   and intervals, where `size` controls the point size and `linewidth` controls
+#'   the line width. For rootograms `size` is passed to [ggplot2::geom_point()]
+#'   and [ggplot2::geom_pointrange()].
+#' @param fatten Deprecated. Point size is now controlled directly by `size`.
 #' @param freq For bar plots only, if `TRUE` (the default) the y-axis will
 #'   display counts. Setting `freq=FALSE` will put proportions on the y-axis.
 #' @param bound_distinct For `ppc_rootogram(style = "discrete)`,
@@ -147,7 +149,6 @@
 #'   group = esoph$agegp,
 #'   freq=FALSE,
 #'   prob = 0.5,
-#'   fatten = 1,
 #'   size = 1.5
 #' )
 #' }
@@ -162,8 +163,8 @@ ppc_bars <-
            ...,
            prob = 0.9,
            width = 0.9,
-           size = 1,
-           fatten = 2.5,
+           size = 2.5,
+           fatten = deprecated(),
            linewidth = 1,
            freq = TRUE) {
 
@@ -172,6 +173,8 @@ ppc_bars <-
       check_ignored_arguments(...)
       dots$group <- NULL
     }
+    size <- resolve_fatten(fatten, size, default_size = 2.5,
+                           calling_fn = "ppc_bars")
 
     data <- ppc_bars_data(
       y = y,
@@ -197,7 +200,6 @@ ppc_bars <-
       geom_pointrange(
         mapping = intervals_inner_aes(needs_y = TRUE, color = "yrep"),
         size = size,
-        fatten = fatten,
         linewidth = linewidth,
         na.rm = TRUE
       ) +
@@ -229,8 +231,8 @@ ppc_bars_grouped <-
            facet_args = list(),
            prob = 0.9,
            width = 0.9,
-           size = 1,
-           fatten = 2.5,
+           size = 2.5,
+           fatten = deprecated(),
            linewidth = 1,
            freq = TRUE) {
     check_ignored_arguments(...)
@@ -277,6 +279,7 @@ ppc_rootogram <- function(y,
                           ...,
                           prob = 0.9,
                           size = 1,
+                          linewidth = 1,
                           bound_distinct = TRUE) {
   check_ignored_arguments(...)
   style <- match.arg(style)
@@ -289,7 +292,6 @@ ppc_rootogram <- function(y,
     bound_distinct = bound_distinct
   )
 
-  # Building geoms for y and y_rep
   geom_y <- if (style == "discrete") {
     geom_point(
       aes(y = .data$obs, shape = .data$obs_shape),
@@ -313,16 +315,15 @@ ppc_rootogram <- function(y,
     geom_pointrange(
       aes(y = .data$pred_median, ymin = .data$lower, ymax = .data$upper, color = "y_rep"),
       fill = get_color("lh"),
-      linewidth = size,
+      linewidth = linewidth,
       size = size,
-      fatten = 2,
       alpha = 1
     )
   } else {
     geom_smooth(
       aes(x = .data$xpos, y = .data$tyexp, color = "Expected"),
       fill = get_color("d"),
-      linewidth = size,
+      linewidth = linewidth,
       stat = "identity"
     )
   }