From 189302e2badbeba68c04608c7b2e904fa770d4d3 Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Mon, 9 Nov 2026 08:54:51 +0200 Subject: [PATCH 1/7] update: set r_eff = NULL for computing tail length --- R/pareto_smooth.R | 38 ++++++++++++++++++++------------------ R/pit.R | 2 +- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/R/pareto_smooth.R b/R/pareto_smooth.R index ed2b0bef..24e90567 100644 --- a/R/pareto_smooth.R +++ b/R/pareto_smooth.R @@ -263,7 +263,7 @@ pareto_smooth.default <- function(x, ...) { if (!is.null(r_eff)) { - r_eff <- as_one_numeric(r_eff) + warn_r_eff_ignored() } if (!is.null(ndraws_tail)) { ndraws_tail <- as_one_integer(ndraws_tail) @@ -293,14 +293,9 @@ pareto_smooth.default <- function(x, tail <- match.arg(tail) ndraws <- length(x) - # automatically calculate relative efficiency - if (is.null(r_eff)) { - r_eff <- ess_tail(x) / ndraws - } - # automatically calculate tail length if (is.null(ndraws_tail)) { - ndraws_tail <- ps_tail_length(ndraws, r_eff) + ndraws_tail <- ps_tail_length(ndraws) } if (is.na(ndraws_tail)) { @@ -773,24 +768,31 @@ ps_convergence_rate <- function(k, ndraws, ...) { rate } +warn_r_eff_ignored <- function() { + warning_no_call( + "`r_eff` is ignored. The Pareto tail length now depends on the number of draws only.", + class = "posterior_warning_pareto_r_eff_ignored" + ) +} + #' Pareto tail length #' -#' Calculate the tail length from number of draws and relative efficiency -#' r_eff. See Appendix H in Vehtari et al. (2024). This function is -#' used internally and is exported to be available for other packages. +#' Calculate the tail length from the number of draws. The tail length is +#' `floor(3 * sqrt(ndraws))` if `ndraws > 225`, and `floor(ndraws / 5)` +#' otherwise. This differs from Appendix H in Vehtari et al. (2024), which +#' also divides by the relative efficiency `r_eff`. This function is used +#' internally and is exported to be available for other packages. #' @family helper-functions #' @param ndraws number of draws -#' @param r_eff relative efficiency +#' @param r_eff Ignored. A value other than `NULL` gives a warning. #' @param ... unused #' @return tail length #' @export -ps_tail_length <- function(ndraws, r_eff, ...) { - floor( - ifelse( - ndraws * r_eff > 225, - 3 * sqrt(ndraws / r_eff), - ndraws / 5) - ) +ps_tail_length <- function(ndraws, r_eff = NULL, ...) { + if (!is.null(r_eff)) { + warn_r_eff_ignored() + } + floor(ifelse(ndraws > 225, 3 * sqrt(ndraws), ndraws / 5)) } #' Pareto-k diagnostic message diff --git a/R/pit.R b/R/pit.R index 4a9f9859..ee39d37d 100644 --- a/R/pit.R +++ b/R/pit.R @@ -248,7 +248,7 @@ pareto_pit.draws_matrix <- function(x, y, weights = NULL, log = FALSE, ndraws <- ndraws(x) if (is.null(ndraws_tail)) { - ndraws_tail <- ps_tail_length(ndraws, 1) + ndraws_tail <- ps_tail_length(ndraws) } else { ndraws_tail <- as_one_integer(ndraws_tail) } From 36cb8f581f06db6c5c4982fdf4e05c7aa9837bd9 Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Mon, 9 Nov 2026 08:55:20 +0200 Subject: [PATCH 2/7] tests: ensure warning appears when r_eff different from NULL --- tests/testthat/test-pareto_pit.R | 4 ++-- tests/testthat/test-pareto_smooth.R | 19 +++++++++++++------ 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/tests/testthat/test-pareto_pit.R b/tests/testthat/test-pareto_pit.R index d552302c..060245ca 100644 --- a/tests/testthat/test-pareto_pit.R +++ b/tests/testthat/test-pareto_pit.R @@ -56,8 +56,8 @@ test_that("pareto_pit treats -Inf log weights as ordinary zero weights", { # unlike pit(), dropping the zero-weight draws is NOT equivalent here, # because the number of tail draws is derived from ndraws - expect_equal(ps_tail_length(n, 1), 60) - expect_equal(ps_tail_length(length(keep), 1), 26) + expect_equal(ps_tail_length(n), 60) + expect_equal(ps_tail_length(length(keep)), 26) }) test_that("pareto_pit keeps the raw PIT when the fitted tail has no mass", { diff --git a/tests/testthat/test-pareto_smooth.R b/tests/testthat/test-pareto_smooth.R index 78cb3500..b33f7732 100644 --- a/tests/testthat/test-pareto_smooth.R +++ b/tests/testthat/test-pareto_smooth.R @@ -80,13 +80,20 @@ test_that("pareto_khat handles ndraws_tail argument", { }) -test_that("pareto_khat handles r_eff argument", { - +test_that("pareto_khat ignores r_eff with a warning", { tau <- extract_variable_matrix(example_draws(), "tau") - pk1 <- pareto_khat(tau, r_eff = 1) - pk0.6 <- pareto_khat(tau, r_eff = 0.6) - expect_true(pk1 < pk0.6) + cls <- "posterior_warning_pareto_r_eff_ignored" + expect_warning(pk <- pareto_khat(tau, r_eff = 0.6), class = cls) + expect_equal(pk, pareto_khat(tau)) + expect_warning(pareto_smooth(tau, r_eff = 1, ndraws_tail = 20), class = cls) +}) +test_that("ps_tail_length depends on ndraws only", { + expect_equal(ps_tail_length(100), 20) + expect_equal(ps_tail_length(1000), floor(3 * sqrt(1000))) + expect_warning(out <- ps_tail_length(1000, 0.5), + class = "posterior_warning_pareto_r_eff_ignored") + expect_equal(out, ps_tail_length(1000)) }) @@ -322,7 +329,7 @@ test_that("ps_tail does not smooth tail values below the cutoff", { test_that("pareto_smooth does not return negative weights for ties at 0", { w <- c(rep(0, 350), exp(-seq(0, 60, length.out = 50))) - ws <- pareto_smooth(w, tail = "right", r_eff = 1, return_k = FALSE, verbose = FALSE) + ws <- pareto_smooth(w, tail = "right", return_k = FALSE, verbose = FALSE) expect_true(all(ws >= 0)) x <- as_draws_df(data.frame(theta = seq_along(ws))) expect_no_error( From 85cefb6bef1bd999f32745611d729e178bff0aa8 Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Mon, 9 Nov 2026 08:55:59 +0200 Subject: [PATCH 3/7] docs: update documentation, add note about r_eff being ignored --- man-roxygen/args-pareto.R | 11 ++++------- man/pareto_diags.Rd | 11 ++++------- man/pareto_khat.Rd | 11 ++++------- man/pareto_smooth.Rd | 11 ++++------- man/ps_tail_length.Rd | 12 +++++++----- 5 files changed, 23 insertions(+), 33 deletions(-) diff --git a/man-roxygen/args-pareto.R b/man-roxygen/args-pareto.R index 488e60bf..e9204e3d 100644 --- a/man-roxygen/args-pareto.R +++ b/man-roxygen/args-pareto.R @@ -9,13 +9,10 @@ #' #' The default is `"both"`. #' @param ndraws_tail (numeric) number of draws for the tail. If -#' `ndraws_tail` is not specified, it will be calculated as -#' ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -#' length(x) / 5 otherwise (see Appendix H in Vehtari et -#' al. (2024)). -#' @param r_eff (numeric) relative effective sample size estimate. If -#' `r_eff` is NULL, it will be calculated assuming the draws are -#' from MCMC. Default is NULL. +#' `ndraws_tail` is not specified, it is calculated with +#' [ps_tail_length()]. +#' @param r_eff Ignored. A value other than `NULL` gives a warning. +#' Default is `NULL`. #' @param verbose (logical) Should diagnostic messages be printed? If #' `TRUE`, messages related to Pareto diagnostics will be #' printed. Default is `FALSE`. diff --git a/man/pareto_diags.Rd b/man/pareto_diags.Rd index 244293a3..fa9f4578 100644 --- a/man/pareto_diags.Rd +++ b/man/pareto_diags.Rd @@ -66,15 +66,12 @@ pareto_convergence_rate(x, ...) The default is \code{"both"}.} -\item{r_eff}{(numeric) relative effective sample size estimate. If -\code{r_eff} is NULL, it will be calculated assuming the draws are -from MCMC. Default is NULL.} +\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +Default is \code{NULL}.} \item{ndraws_tail}{(numeric) number of draws for the tail. If -\code{ndraws_tail} is not specified, it will be calculated as -ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -length(x) / 5 otherwise (see Appendix H in Vehtari et -al. (2024)).} +\code{ndraws_tail} is not specified, it is calculated with +\code{\link[=ps_tail_length]{ps_tail_length()}}.} \item{verbose}{(logical) Should diagnostic messages be printed? If \code{TRUE}, messages related to Pareto diagnostics will be diff --git a/man/pareto_khat.Rd b/man/pareto_khat.Rd index 21fdf3a3..cc0ad284 100644 --- a/man/pareto_khat.Rd +++ b/man/pareto_khat.Rd @@ -39,15 +39,12 @@ pareto_khat(x, ...) The default is \code{"both"}.} -\item{r_eff}{(numeric) relative effective sample size estimate. If -\code{r_eff} is NULL, it will be calculated assuming the draws are -from MCMC. Default is NULL.} +\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +Default is \code{NULL}.} \item{ndraws_tail}{(numeric) number of draws for the tail. If -\code{ndraws_tail} is not specified, it will be calculated as -ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -length(x) / 5 otherwise (see Appendix H in Vehtari et -al. (2024)).} +\code{ndraws_tail} is not specified, it is calculated with +\code{\link[=ps_tail_length]{ps_tail_length()}}.} \item{verbose}{(logical) Should diagnostic messages be printed? If \code{TRUE}, messages related to Pareto diagnostics will be diff --git a/man/pareto_smooth.Rd b/man/pareto_smooth.Rd index 48ae2175..490e11bb 100644 --- a/man/pareto_smooth.Rd +++ b/man/pareto_smooth.Rd @@ -51,15 +51,12 @@ returned. Default is \code{FALSE}.} The default is \code{"both"}.} -\item{r_eff}{(numeric) relative effective sample size estimate. If -\code{r_eff} is NULL, it will be calculated assuming the draws are -from MCMC. Default is NULL.} +\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +Default is \code{NULL}.} \item{ndraws_tail}{(numeric) number of draws for the tail. If -\code{ndraws_tail} is not specified, it will be calculated as -ceiling(3 * sqrt(length(x) / r_eff)) if length(x) > 225 and -length(x) / 5 otherwise (see Appendix H in Vehtari et -al. (2024)).} +\code{ndraws_tail} is not specified, it is calculated with +\code{\link[=ps_tail_length]{ps_tail_length()}}.} \item{verbose}{(logical) Should diagnostic messages be printed? If \code{TRUE}, messages related to Pareto diagnostics will be diff --git a/man/ps_tail_length.Rd b/man/ps_tail_length.Rd index 9da67523..e4cdacc7 100644 --- a/man/ps_tail_length.Rd +++ b/man/ps_tail_length.Rd @@ -4,12 +4,12 @@ \alias{ps_tail_length} \title{Pareto tail length} \usage{ -ps_tail_length(ndraws, r_eff, ...) +ps_tail_length(ndraws, r_eff = NULL, ...) } \arguments{ \item{ndraws}{number of draws} -\item{r_eff}{relative efficiency} +\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning.} \item{...}{unused} } @@ -17,9 +17,11 @@ ps_tail_length(ndraws, r_eff, ...) tail length } \description{ -Calculate the tail length from number of draws and relative efficiency -r_eff. See Appendix H in Vehtari et al. (2024). This function is -used internally and is exported to be available for other packages. +Calculate the tail length from the number of draws. The tail length is +\code{floor(3 * sqrt(ndraws))} if \code{ndraws > 225}, and \code{floor(ndraws / 5)} +otherwise. This differs from Appendix H in Vehtari et al. (2024), which +also divides by the relative efficiency \code{r_eff}. This function is used +internally and is exported to be available for other packages. } \seealso{ Other helper-functions: From 0694f8f5554294fbf2b87ae5b065ea26005fefbe Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Mon, 9 Nov 2026 09:17:35 +0200 Subject: [PATCH 4/7] chore: update NEWS.md --- NEWS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/NEWS.md b/NEWS.md index 6c84f577..3c29ac8e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -10,6 +10,8 @@ result instead of about three. selected. * All warnings now have the class `posterior_warning` and a class for each cause. Calling packages can catch, count, or muffle each type of warning (#470). +* `ps_tail_length()` no longer uses `r_eff`. The Pareto tail length now +depends on the number of draws only. (#478) ### Bug Fixes From 683129496a8360bf2a2d0ba33556918860ff6940 Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Mon, 9 Nov 2026 09:18:08 +0200 Subject: [PATCH 5/7] update: rvar warns only once when r_eff is not NULL --- R/pareto_smooth.R | 18 ++++++++++++++---- R/posterior-package.R | 2 ++ man/pareto_diags.Rd | 2 +- man/pareto_khat.Rd | 2 +- man/pareto_smooth.Rd | 8 ++++---- man/posterior-package.Rd | 2 ++ tests/testthat/test-pareto_smooth.R | 7 +++++++ 7 files changed, 31 insertions(+), 10 deletions(-) diff --git a/R/pareto_smooth.R b/R/pareto_smooth.R index 24e90567..ba053452 100644 --- a/R/pareto_smooth.R +++ b/R/pareto_smooth.R @@ -46,7 +46,10 @@ pareto_khat.default <- function(x, #' @rdname pareto_khat #' @export -pareto_khat.rvar <- function(x, ...) { +pareto_khat.rvar <- function(x, r_eff = NULL, ...) { + if (!is.null(r_eff)) { + warn_r_eff_ignored() + } draws_diags <- summarise_rvar_by_element_with_chains( x, pareto_khat.default, @@ -148,7 +151,10 @@ pareto_diags.default <- function(x, #' @rdname pareto_diags #' @export -pareto_diags.rvar <- function(x, ...) { +pareto_diags.rvar <- function(x, r_eff = NULL, ...) { + if (!is.null(r_eff)) { + warn_r_eff_ignored() + } draws_diags <- summarise_rvar_by_element_with_chains( x, pareto_diags.default, @@ -216,8 +222,12 @@ pareto_smooth <- function(x, ...) UseMethod("pareto_smooth") #' @rdname pareto_smooth #' @export -pareto_smooth.rvar <- function(x, return_k = FALSE, extra_diags = FALSE, ...) { - +pareto_smooth.rvar <- function( + x, return_k = FALSE, extra_diags = FALSE, r_eff = NULL, ... +) { + if (!is.null(r_eff)) { + warn_r_eff_ignored() + } if (extra_diags) { return_k <- TRUE } diff --git a/R/posterior-package.R b/R/posterior-package.R index c33a4fd7..5debf6fe 100644 --- a/R/posterior-package.R +++ b/R/posterior-package.R @@ -99,6 +99,8 @@ #' more than half of the total number of draws. #' * `posterior_warning_pareto_tail_not_fitted`: The generalized Pareto #' distribution was not fitted because there are fewer than 5 tail draws. +#' * `posterior_warning_pareto_r_eff_ignored`: `r_eff` was given, but the +#' Pareto tail length no longer uses it. #' #' The error signaled when all weights are zero has the class #' `posterior_error_degenerate_weights`. diff --git a/man/pareto_diags.Rd b/man/pareto_diags.Rd index fa9f4578..40d7c7cc 100644 --- a/man/pareto_diags.Rd +++ b/man/pareto_diags.Rd @@ -27,7 +27,7 @@ pareto_diags(x, ...) ... ) -\method{pareto_diags}{rvar}(x, ...) +\method{pareto_diags}{rvar}(x, r_eff = NULL, ...) pareto_khat_threshold(x, ...) diff --git a/man/pareto_khat.Rd b/man/pareto_khat.Rd index cc0ad284..68d41aab 100644 --- a/man/pareto_khat.Rd +++ b/man/pareto_khat.Rd @@ -18,7 +18,7 @@ pareto_khat(x, ...) ... ) -\method{pareto_khat}{rvar}(x, ...) +\method{pareto_khat}{rvar}(x, r_eff = NULL, ...) } \arguments{ \item{x}{(multiple options) One of: diff --git a/man/pareto_smooth.Rd b/man/pareto_smooth.Rd index 490e11bb..9e9c5b4f 100644 --- a/man/pareto_smooth.Rd +++ b/man/pareto_smooth.Rd @@ -8,7 +8,7 @@ \usage{ pareto_smooth(x, ...) -\method{pareto_smooth}{rvar}(x, return_k = FALSE, extra_diags = FALSE, ...) +\method{pareto_smooth}{rvar}(x, return_k = FALSE, extra_diags = FALSE, r_eff = NULL, ...) \method{pareto_smooth}{default}( x, @@ -42,6 +42,9 @@ be included in output? If \code{TRUE}, \code{min_ss}, \code{khat_threshold} and \code{convergence_rate} for the estimated k value will be returned. Default is \code{FALSE}.} +\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +Default is \code{NULL}.} + \item{tail}{(string) The tail to diagnose/smooth: \itemize{ \item \code{"right"}: diagnose/smooth only the right (upper) tail @@ -51,9 +54,6 @@ returned. Default is \code{FALSE}.} The default is \code{"both"}.} -\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. -Default is \code{NULL}.} - \item{ndraws_tail}{(numeric) number of draws for the tail. If \code{ndraws_tail} is not specified, it is calculated with \code{\link[=ps_tail_length]{ps_tail_length()}}.} diff --git a/man/posterior-package.Rd b/man/posterior-package.Rd index 4e09bbfb..eae8ed6b 100644 --- a/man/posterior-package.Rd +++ b/man/posterior-package.Rd @@ -109,6 +109,8 @@ is not less than the total number of draws. more than half of the total number of draws. \item \code{posterior_warning_pareto_tail_not_fitted}: The generalized Pareto distribution was not fitted because there are fewer than 5 tail draws. +\item \code{posterior_warning_pareto_r_eff_ignored}: \code{r_eff} was given, but the +Pareto tail length no longer uses it. } The error signaled when all weights are zero has the class diff --git a/tests/testthat/test-pareto_smooth.R b/tests/testthat/test-pareto_smooth.R index b33f7732..6e1d86d1 100644 --- a/tests/testthat/test-pareto_smooth.R +++ b/tests/testthat/test-pareto_smooth.R @@ -231,6 +231,13 @@ test_that("pareto_khat functions work with rvars with and without chains", { }) +test_that("rvar methods give one r_eff warning", { + theta <- as_draws_rvars(example_draws())$theta + expect_length(capture_warnings(pareto_khat(theta, r_eff = 0.5)), 1) + expect_length(capture_warnings(pareto_diags(theta, r_eff = 0.5)), 1) + expect_length(capture_warnings(pareto_smooth(theta, r_eff = 0.5)), 1) +}) + test_that("pareto_smooth returns x with smoothed tail(s)", { mu <- extract_variable_matrix(example_draws(), "mu") From e6eadc3f20708e18c441a809a145913d1346051a Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Fri, 13 Nov 2026 11:40:54 +0200 Subject: [PATCH 6/7] fix: warn not when r_eff is 1, put r_eff after dots in rvar methods --- R/pareto_smooth.R | 40 ++++++++++++----------------- R/posterior-package.R | 4 +-- man-roxygen/args-pareto.R | 2 +- man/pareto_diags.Rd | 4 +-- man/pareto_khat.Rd | 4 +-- man/pareto_smooth.Rd | 4 +-- man/posterior-package.Rd | 4 +-- man/ps_tail_length.Rd | 2 +- tests/testthat/test-pareto_smooth.R | 14 +++++++++- 9 files changed, 41 insertions(+), 37 deletions(-) diff --git a/R/pareto_smooth.R b/R/pareto_smooth.R index ba053452..cd484c65 100644 --- a/R/pareto_smooth.R +++ b/R/pareto_smooth.R @@ -46,10 +46,8 @@ pareto_khat.default <- function(x, #' @rdname pareto_khat #' @export -pareto_khat.rvar <- function(x, r_eff = NULL, ...) { - if (!is.null(r_eff)) { - warn_r_eff_ignored() - } +pareto_khat.rvar <- function(x, ..., r_eff = NULL) { + warn_r_eff_ignored(r_eff) draws_diags <- summarise_rvar_by_element_with_chains( x, pareto_khat.default, @@ -151,10 +149,8 @@ pareto_diags.default <- function(x, #' @rdname pareto_diags #' @export -pareto_diags.rvar <- function(x, r_eff = NULL, ...) { - if (!is.null(r_eff)) { - warn_r_eff_ignored() - } +pareto_diags.rvar <- function(x, ..., r_eff = NULL) { + warn_r_eff_ignored(r_eff) draws_diags <- summarise_rvar_by_element_with_chains( x, pareto_diags.default, @@ -223,11 +219,9 @@ pareto_smooth <- function(x, ...) UseMethod("pareto_smooth") #' @rdname pareto_smooth #' @export pareto_smooth.rvar <- function( - x, return_k = FALSE, extra_diags = FALSE, r_eff = NULL, ... + x, return_k = FALSE, extra_diags = FALSE, ..., r_eff = NULL ) { - if (!is.null(r_eff)) { - warn_r_eff_ignored() - } + warn_r_eff_ignored(r_eff) if (extra_diags) { return_k <- TRUE } @@ -272,9 +266,7 @@ pareto_smooth.default <- function(x, are_log_weights = FALSE, ...) { - if (!is.null(r_eff)) { - warn_r_eff_ignored() - } + warn_r_eff_ignored(r_eff) if (!is.null(ndraws_tail)) { ndraws_tail <- as_one_integer(ndraws_tail) } @@ -778,11 +770,13 @@ ps_convergence_rate <- function(k, ndraws, ...) { rate } -warn_r_eff_ignored <- function() { - warning_no_call( - "`r_eff` is ignored. The Pareto tail length now depends on the number of draws only.", - class = "posterior_warning_pareto_r_eff_ignored" - ) +warn_r_eff_ignored <- function(r_eff) { + if (!is.null(r_eff) && !isTRUE(all(r_eff == 1))) { + warning_no_call( + "`r_eff` is ignored. The Pareto tail length now depends on the number of draws only.", + class = "posterior_warning_pareto_r_eff_ignored" + ) + } } #' Pareto tail length @@ -794,14 +788,12 @@ warn_r_eff_ignored <- function() { #' internally and is exported to be available for other packages. #' @family helper-functions #' @param ndraws number of draws -#' @param r_eff Ignored. A value other than `NULL` gives a warning. +#' @param r_eff Ignored. A value other than `NULL` or 1 gives a warning. #' @param ... unused #' @return tail length #' @export ps_tail_length <- function(ndraws, r_eff = NULL, ...) { - if (!is.null(r_eff)) { - warn_r_eff_ignored() - } + warn_r_eff_ignored(r_eff) floor(ifelse(ndraws > 225, 3 * sqrt(ndraws), ndraws / 5)) } diff --git a/R/posterior-package.R b/R/posterior-package.R index 5debf6fe..c08f10dc 100644 --- a/R/posterior-package.R +++ b/R/posterior-package.R @@ -99,8 +99,8 @@ #' more than half of the total number of draws. #' * `posterior_warning_pareto_tail_not_fitted`: The generalized Pareto #' distribution was not fitted because there are fewer than 5 tail draws. -#' * `posterior_warning_pareto_r_eff_ignored`: `r_eff` was given, but the -#' Pareto tail length no longer uses it. +#' * `posterior_warning_pareto_r_eff_ignored`: `r_eff` was given with a value +#' other than 1, but the Pareto tail length no longer uses it. #' #' The error signaled when all weights are zero has the class #' `posterior_error_degenerate_weights`. diff --git a/man-roxygen/args-pareto.R b/man-roxygen/args-pareto.R index e9204e3d..6153bfc9 100644 --- a/man-roxygen/args-pareto.R +++ b/man-roxygen/args-pareto.R @@ -11,7 +11,7 @@ #' @param ndraws_tail (numeric) number of draws for the tail. If #' `ndraws_tail` is not specified, it is calculated with #' [ps_tail_length()]. -#' @param r_eff Ignored. A value other than `NULL` gives a warning. +#' @param r_eff Ignored. A value other than `NULL` or 1 gives a warning. #' Default is `NULL`. #' @param verbose (logical) Should diagnostic messages be printed? If #' `TRUE`, messages related to Pareto diagnostics will be diff --git a/man/pareto_diags.Rd b/man/pareto_diags.Rd index 40d7c7cc..105f9e1e 100644 --- a/man/pareto_diags.Rd +++ b/man/pareto_diags.Rd @@ -27,7 +27,7 @@ pareto_diags(x, ...) ... ) -\method{pareto_diags}{rvar}(x, r_eff = NULL, ...) +\method{pareto_diags}{rvar}(x, ..., r_eff = NULL) pareto_khat_threshold(x, ...) @@ -66,7 +66,7 @@ pareto_convergence_rate(x, ...) The default is \code{"both"}.} -\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +\item{r_eff}{Ignored. A value other than \code{NULL} or 1 gives a warning. Default is \code{NULL}.} \item{ndraws_tail}{(numeric) number of draws for the tail. If diff --git a/man/pareto_khat.Rd b/man/pareto_khat.Rd index 68d41aab..61edb116 100644 --- a/man/pareto_khat.Rd +++ b/man/pareto_khat.Rd @@ -18,7 +18,7 @@ pareto_khat(x, ...) ... ) -\method{pareto_khat}{rvar}(x, r_eff = NULL, ...) +\method{pareto_khat}{rvar}(x, ..., r_eff = NULL) } \arguments{ \item{x}{(multiple options) One of: @@ -39,7 +39,7 @@ pareto_khat(x, ...) The default is \code{"both"}.} -\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +\item{r_eff}{Ignored. A value other than \code{NULL} or 1 gives a warning. Default is \code{NULL}.} \item{ndraws_tail}{(numeric) number of draws for the tail. If diff --git a/man/pareto_smooth.Rd b/man/pareto_smooth.Rd index 9e9c5b4f..a1fccc5b 100644 --- a/man/pareto_smooth.Rd +++ b/man/pareto_smooth.Rd @@ -8,7 +8,7 @@ \usage{ pareto_smooth(x, ...) -\method{pareto_smooth}{rvar}(x, return_k = FALSE, extra_diags = FALSE, r_eff = NULL, ...) +\method{pareto_smooth}{rvar}(x, return_k = FALSE, extra_diags = FALSE, ..., r_eff = NULL) \method{pareto_smooth}{default}( x, @@ -42,7 +42,7 @@ be included in output? If \code{TRUE}, \code{min_ss}, \code{khat_threshold} and \code{convergence_rate} for the estimated k value will be returned. Default is \code{FALSE}.} -\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning. +\item{r_eff}{Ignored. A value other than \code{NULL} or 1 gives a warning. Default is \code{NULL}.} \item{tail}{(string) The tail to diagnose/smooth: diff --git a/man/posterior-package.Rd b/man/posterior-package.Rd index eae8ed6b..746312b8 100644 --- a/man/posterior-package.Rd +++ b/man/posterior-package.Rd @@ -109,8 +109,8 @@ is not less than the total number of draws. more than half of the total number of draws. \item \code{posterior_warning_pareto_tail_not_fitted}: The generalized Pareto distribution was not fitted because there are fewer than 5 tail draws. -\item \code{posterior_warning_pareto_r_eff_ignored}: \code{r_eff} was given, but the -Pareto tail length no longer uses it. +\item \code{posterior_warning_pareto_r_eff_ignored}: \code{r_eff} was given with a value +other than 1, but the Pareto tail length no longer uses it. } The error signaled when all weights are zero has the class diff --git a/man/ps_tail_length.Rd b/man/ps_tail_length.Rd index e4cdacc7..8bc27dac 100644 --- a/man/ps_tail_length.Rd +++ b/man/ps_tail_length.Rd @@ -9,7 +9,7 @@ ps_tail_length(ndraws, r_eff = NULL, ...) \arguments{ \item{ndraws}{number of draws} -\item{r_eff}{Ignored. A value other than \code{NULL} gives a warning.} +\item{r_eff}{Ignored. A value other than \code{NULL} or 1 gives a warning.} \item{...}{unused} } diff --git a/tests/testthat/test-pareto_smooth.R b/tests/testthat/test-pareto_smooth.R index 6e1d86d1..cab735fa 100644 --- a/tests/testthat/test-pareto_smooth.R +++ b/tests/testthat/test-pareto_smooth.R @@ -85,7 +85,9 @@ test_that("pareto_khat ignores r_eff with a warning", { cls <- "posterior_warning_pareto_r_eff_ignored" expect_warning(pk <- pareto_khat(tau, r_eff = 0.6), class = cls) expect_equal(pk, pareto_khat(tau)) - expect_warning(pareto_smooth(tau, r_eff = 1, ndraws_tail = 20), class = cls) + expect_warning(pareto_smooth(tau, r_eff = 0.6, ndraws_tail = 20), class = cls) + expect_no_warning(pareto_khat(tau, r_eff = 1)) + expect_no_warning(pareto_khat(tau, r_eff = c(1, 1))) }) test_that("ps_tail_length depends on ndraws only", { @@ -238,6 +240,16 @@ test_that("rvar methods give one r_eff warning", { expect_length(capture_warnings(pareto_smooth(theta, r_eff = 0.5)), 1) }) +test_that("rvar methods pass positional tail via dots", { + rv <- rvar(rexp(4000), nchains = 4) + expect_no_warning(k <- pareto_khat(rv, "left")) + expect_equal(k, pareto_khat(rv, tail = "left")) + expect_no_warning(d <- pareto_diags(rv, "left")) + expect_equal(d, pareto_diags(rv, tail = "left")) + expect_no_warning(s <- pareto_smooth(rv, TRUE, FALSE, "left", verbose = FALSE)) + expect_equal(s, pareto_smooth(rv, return_k = TRUE, tail = "left", verbose = FALSE)) +}) + test_that("pareto_smooth returns x with smoothed tail(s)", { mu <- extract_variable_matrix(example_draws(), "mu") From 16943c1ac24038a6286c23ce1d0562db7037a1e5 Mon Sep 17 00:00:00 2001 From: Florence Bockting Date: Mon, 16 Nov 2026 10:19:36 +0200 Subject: [PATCH 7/7] chore: update NEWS.md --- NEWS.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/NEWS.md b/NEWS.md index 3c29ac8e..209ed773 100644 --- a/NEWS.md +++ b/NEWS.md @@ -10,8 +10,12 @@ result instead of about three. selected. * All warnings now have the class `posterior_warning` and a class for each cause. Calling packages can catch, count, or muffle each type of warning (#470). -* `ps_tail_length()` no longer uses `r_eff`. The Pareto tail length now -depends on the number of draws only. (#478) +* The Pareto tail length in `pareto_khat()`, `pareto_diags()`, +`pareto_smooth()`, and `ps_tail_length()` now depends only on the number of +draws (#446, #478). For MCMC draws, results with the default `r_eff = NULL` +change slightly because `r_eff` was previously estimated with `ess_tail()`. +These functions are also faster now. `r_eff` is ignored, with a warning unless +it is `NULL` or `1` (#478). ### Bug Fixes