Warn when neff ratios exceed 1

NEWS.md

@@ -1,5 +1,6 @@
 # bayesplot (development version)
 
+* `mcmc_neff()` and `mcmc_neff_hist()` now warn when any neff ratios are greater than 1, as this is unusual and may indicate a problem with the model or sampler.
 * Use `rlang::warn()` and `rlang::inform()` for selected PPC user messages instead of base `warning()` and `message()`.
 * Standardize input validation errors in `ppc_km_overlay()` and interpolation helpers to use `rlang::abort()` for consistent error handling.
 * Fix assignment-in-call bug in `mcmc_rank_ecdf()` (#).

R/mcmc-diagnostics.R

@@ -658,6 +658,12 @@ validate_neff_ratio <- function(x) {
   if (any(x < 0, na.rm = TRUE)) {
     abort("All neff ratios must be positive.")
   }
+  if (any(x > 1, na.rm = TRUE)) {
+    warn(paste0(
+      "Some neff ratios are greater than 1. ",
+      "This is unusual and may indicate a problem with your model or MCMC sampler."
+    ))
+  }
   x
 }
 

tests/testthat/test-mcmc-diagnostics.R

@@ -19,9 +19,9 @@ test_that("rhat and neff plots return a ggplot object", {
   rhat <- setNames(runif(5, 1, 1.5), paste0("alpha[", 1:5, "]"))
   expect_gg(mcmc_rhat(rhat))
 
-  # doesn't error with ratios > 1 (not common but can happen)
-  expect_gg(mcmc_neff(ratio = c(0.5, 1, 1.25)))
-  expect_gg(mcmc_neff(ratio = c(0.5, 1, 2)))
+  # doesn't error with ratios > 1 (not common but can happen), but does warn
+  expect_warning(mcmc_neff(ratio = c(0.5, 1, 1.25)), "greater than 1")
+  expect_warning(mcmc_neff(ratio = c(0.5, 1, 2)), "greater than 1")
 })
 
 test_that("rhat and neff plot functions throw correct errors & warnings", {
@@ -34,6 +34,7 @@ test_that("rhat and neff plot functions throw correct errors & warnings", {
 
   # need ratios between 0 and 1
   expect_error(mcmc_neff(c(-1, 0.5, 0.7)), "must be positive")
+  expect_warning(mcmc_neff(c(0.5, 1.1, 1.5)), "greater than 1")
 
   # drop NAs and warn
   expect_warning(mcmc_rhat(c(1, 1, NA)), "Dropped 1 NAs")