diff --git a/NEWS.md b/NEWS.md index 03326003..989cccc6 100644 --- a/NEWS.md +++ b/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()` (#). diff --git a/R/mcmc-diagnostics.R b/R/mcmc-diagnostics.R index 87e716da..f05cb98c 100644 --- a/R/mcmc-diagnostics.R +++ b/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 } diff --git a/tests/testthat/test-mcmc-diagnostics.R b/tests/testthat/test-mcmc-diagnostics.R index 9c6efb74..d4b45a8a 100644 --- a/tests/testthat/test-mcmc-diagnostics.R +++ b/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")