Deprecate rhat() and neff_ratio() in favor of extract_rhat()/extract_neff_ratio()

NAMESPACE

@@ -6,14 +6,18 @@ S3method(apply_transformations,array)
 S3method(apply_transformations,matrix)
 S3method(diagnostic_factor,neff_ratio)
 S3method(diagnostic_factor,rhat)
+S3method(extract_neff_ratio,CmdStanMCMC)
+S3method(extract_neff_ratio,stanfit)
+S3method(extract_neff_ratio,stanreg)
+S3method(extract_rhat,CmdStanMCMC)
+S3method(extract_rhat,stanfit)
+S3method(extract_rhat,stanreg)
 S3method(log_posterior,CmdStanMCMC)
 S3method(log_posterior,stanfit)
 S3method(log_posterior,stanreg)
 S3method(melt_mcmc,matrix)
 S3method(melt_mcmc,mcmc_array)
-S3method(neff_ratio,CmdStanMCMC)
-S3method(neff_ratio,stanfit)
-S3method(neff_ratio,stanreg)
+S3method(neff_ratio,default)
 S3method(num_chains,data.frame)
 S3method(num_chains,mcmc_array)
 S3method(num_iters,data.frame)
@@ -33,9 +37,7 @@ S3method(pp_check,default)
 S3method(print,bayesplot_function_list)
 S3method(print,bayesplot_grid)
 S3method(print,bayesplot_scheme)
-S3method(rhat,CmdStanMCMC)
-S3method(rhat,stanfit)
-S3method(rhat,stanreg)
+S3method(rhat,default)
 export(abline_01)
 export(available_mcmc)
 export(available_ppc)
@@ -53,6 +55,8 @@ export(example_mcmc_draws)
 export(example_x_data)
 export(example_y_data)
 export(example_yrep_draws)
+export(extract_neff_ratio)
+export(extract_rhat)
 export(facet_bg)
 export(facet_text)
 export(grid_lines)

NEWS.md

@@ -1,5 +1,6 @@
 # bayesplot (development version)
 
+* Deprecated `rhat()` and `neff_ratio()` in favor of `extract_rhat()` and `extract_neff_ratio()`.
 * Fixed `validate_chain_list()` colnames check to compare all chains, not just the first two.
 * Added test verifying `legend_move("none")` behaves equivalently to `legend_none()`.
 * Added singleton-dimension edge-case tests for exported `_data()` functions.

R/bayesplot-extractors.R

@@ -24,9 +24,16 @@
 #' The data frame should have columns `"Parameter"` (factor), `"Iteration"`
 #' (integer), `"Chain"` (integer), and `"Value"` (numeric). See **Examples**, below.
 #' }
-#' \item{`rhat()`, `neff_ratio()`}{
+#' \item{`extract_rhat()`, `extract_neff_ratio()`}{
 #' Methods return (named) vectors.
 #' }
+#' \item{`rhat()`, `neff_ratio()`}{
+#' `r lifecycle::badge("deprecated")` Use `extract_rhat()` and
+#' `extract_neff_ratio()` instead. These names clashed with
+#' [posterior::rhat()] and [posterior::ess_basic()] (and other ESS
+#' functions), which caused confusion because the bayesplot versions
+#' *extract* already-computed values rather than compute them.
+#' }
 #' }
 #'
 #' @seealso [MCMC-nuts], [MCMC-diagnostics]
@@ -60,19 +67,70 @@ log_posterior <- function(object, ...) {
 nuts_params <- function(object, ...) {
   UseMethod("nuts_params")
 }
+# extract_rhat -------------------------------------------------------------
+#' @rdname bayesplot-extractors
+#' @export
+extract_rhat <- function(object, ...) {
+  UseMethod("extract_rhat")
+}
+# extract_neff_ratio -------------------------------------------------------
+#' @rdname bayesplot-extractors
+#' @export
+extract_neff_ratio <- function(object, ...) {
+  UseMethod("extract_neff_ratio")
+}
+
 # rhat -------------------------------------------------------------
+# Kept as an S3 generic (not just a wrapper) so third-party methods
+# registered against rhat (e.g. brms::rhat.brmsfit) still dispatch
+# during the deprecation window.
 #' @rdname bayesplot-extractors
 #' @export
 rhat <- function(object, ...) {
+  lifecycle::deprecate_warn(
+    when = "1.16.0",
+    what = "rhat()",
+    with = "extract_rhat()",
+    details = paste(
+      "bayesplot's rhat() was renamed to extract_rhat() to make clear",
+      "it only extracts already-computed R-hat values (and to avoid",
+      "masking posterior::rhat(), which computes R-hat)."
+    )
+  )
   UseMethod("rhat")
 }
+
+#' @rdname bayesplot-extractors
+#' @export
+#' @method rhat default
+rhat.default <- function(object, ...) {
+  extract_rhat(object, ...)
+}
+
 # neff_ratio -------------------------------------------------------------
 #' @rdname bayesplot-extractors
 #' @export
 neff_ratio <- function(object, ...) {
+  lifecycle::deprecate_warn(
+    when = "1.16.0",
+    what = "neff_ratio()",
+    with = "extract_neff_ratio()",
+    details = paste(
+      "bayesplot's neff_ratio() was renamed to extract_neff_ratio() to",
+      "make clear it only extracts already-computed effective sample",
+      "size ratios (and to avoid masking posterior's ESS functions)."
+    )
+  )
   UseMethod("neff_ratio")
 }
 
+#' @rdname bayesplot-extractors
+#' @export
+#' @method neff_ratio default
+neff_ratio.default <- function(object, ...) {
+  extract_neff_ratio(object, ...)
+}
+
 
 
 #' @rdname bayesplot-extractors
@@ -195,9 +253,9 @@ nuts_params.CmdStanMCMC <- function(object, pars = NULL, ...) {
 
 #' @rdname bayesplot-extractors
 #' @export
-#' @method rhat stanfit
+#' @method extract_rhat stanfit
 #'
-rhat.stanfit <- function(object, pars = NULL, ...) {
+extract_rhat.stanfit <- function(object, pars = NULL, ...) {
   suggested_package("rstan")
   s <- if (!is.null(pars)) {
     rstan::summary(object, pars = pars, ...)
@@ -210,10 +268,10 @@ rhat.stanfit <- function(object, pars = NULL, ...) {
 
 #' @rdname bayesplot-extractors
 #' @export
-#' @method rhat stanreg
+#' @method extract_rhat stanreg
 #' @template args-regex_pars
 #'
-rhat.stanreg <- function(object, pars = NULL, regex_pars = NULL, ...) {
+extract_rhat.stanreg <- function(object, pars = NULL, regex_pars = NULL, ...) {
   suggested_package("rstanarm")
   r <- summary(object, pars = pars, regex_pars = regex_pars, ...)[, "Rhat"]
   r <- validate_rhat(r)
@@ -226,8 +284,8 @@ rhat.stanreg <- function(object, pars = NULL, regex_pars = NULL, ...) {
 
 #' @rdname bayesplot-extractors
 #' @export
-#' @method rhat CmdStanMCMC
-rhat.CmdStanMCMC <- function(object, pars = NULL, ...) {
+#' @method extract_rhat CmdStanMCMC
+extract_rhat.CmdStanMCMC <- function(object, pars = NULL, ...) {
   .rhat <- utils::getFromNamespace("rhat", "posterior")
   s <- object$summary(pars, rhat = .rhat)[, c("variable", "rhat")]
   r <- setNames(s$rhat, s$variable)
@@ -238,9 +296,9 @@ rhat.CmdStanMCMC <- function(object, pars = NULL, ...) {
 
 #' @rdname bayesplot-extractors
 #' @export
-#' @method neff_ratio stanfit
+#' @method extract_neff_ratio stanfit
 #'
-neff_ratio.stanfit <- function(object, pars = NULL, ...) {
+extract_neff_ratio.stanfit <- function(object, pars = NULL, ...) {
   suggested_package("rstan")
   s <- if (!is.null(pars)) {
     rstan::summary(object, pars = pars, ...)
@@ -254,9 +312,9 @@ neff_ratio.stanfit <- function(object, pars = NULL, ...) {
 
 #' @rdname bayesplot-extractors
 #' @export
-#' @method neff_ratio stanreg
+#' @method extract_neff_ratio stanreg
 #'
-neff_ratio.stanreg <- function(object, pars = NULL, regex_pars = NULL, ...) {
+extract_neff_ratio.stanreg <- function(object, pars = NULL, regex_pars = NULL, ...) {
   suggested_package("rstanarm")
   s <- summary(object, pars = pars, regex_pars = regex_pars, ...)
   ess <- s[, "n_eff"]
@@ -272,8 +330,8 @@ neff_ratio.stanreg <- function(object, pars = NULL, regex_pars = NULL, ...) {
 
 #' @rdname bayesplot-extractors
 #' @export
-#' @method neff_ratio CmdStanMCMC
-neff_ratio.CmdStanMCMC <- function(object, pars = NULL, ...) {
+#' @method extract_neff_ratio CmdStanMCMC
+extract_neff_ratio.CmdStanMCMC <- function(object, pars = NULL, ...) {
   s <- object$summary(pars, "n_eff" = "ess_basic")[, c("variable", "n_eff")]
   ess <- setNames(s$n_eff, s$variable)
   tss <- prod(dim(object$draws())[1:2])

R/mcmc-diagnostics.R

@@ -105,8 +105,8 @@
 #' # intentionally use small 'iter' so there are some
 #' # problems with rhat and neff for demonstration
 #' fit <- stan_glm(mpg ~ ., data = mtcars, iter = 50, refresh = 0)
-#' rhats <- rhat(fit)
-#' ratios <- neff_ratio(fit)
+#' rhats <- extract_rhat(fit)
+#' ratios <- extract_neff_ratio(fit)
 #' mcmc_rhat(rhats)
 #' mcmc_neff(ratios, size = 3)
 #'
@@ -120,8 +120,8 @@
 #'
 #' # increase number of iterations and plots look much better
 #' fit2 <- update(fit, iter = 500)
-#' mcmc_rhat(rhat(fit2))
-#' mcmc_neff(neff_ratio(fit2))
+#' mcmc_rhat(extract_rhat(fit2))
+#' mcmc_neff(extract_neff_ratio(fit2))
 #' mcmc_acf(as.array(fit2), pars = c("wt", "cyl"), lags = 10)
 #' }
 #'
@@ -220,7 +220,7 @@ mcmc_rhat_data <- function(rhat, ...) {
 #' @rdname MCMC-diagnostics
 #' @export
 #' @param ratio A vector of *ratios* of effective sample size estimates to
-#'   total sample size. See [neff_ratio()].
+#'   total sample size. See [extract_neff_ratio()].
 #'
 mcmc_neff <- function(ratio, ..., size = NULL) {
   check_ignored_arguments(...)

R/mcmc-intervals.R

@@ -31,7 +31,7 @@
 #' @param rhat An optional numeric vector of R-hat estimates, with one element
 #'   per parameter included in `x`. If `rhat` is provided, the intervals/areas
 #'   and point estimates in the resulting plot are colored based on R-hat value.
-#'   See [rhat()] for methods for extracting R-hat estimates.
+#'   See [extract_rhat()] for methods for extracting R-hat estimates.
 #' @template args-density-controls
 #'
 #' @template return-ggplot-or-data
@@ -180,7 +180,7 @@
 #' color_scheme_set("teal")
 #' mcmc_intervals(x, point_est = "mean", prob = 0.8, prob_outer = 0.95)
 #' mcmc_areas(x, regex_pars = "cyl", bw = "SJ",
-#'            rhat = rhat(fit, regex_pars = "cyl"))
+#'            rhat = extract_rhat(fit, regex_pars = "cyl"))
 #' }
 #'
 #' \dontrun{