Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +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).
* 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

Expand Down
52 changes: 28 additions & 24 deletions R/pareto_smooth.R
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ pareto_khat.default <- function(x,

#' @rdname pareto_khat
#' @export
pareto_khat.rvar <- function(x, ...) {
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,
Expand Down Expand Up @@ -148,7 +149,8 @@ pareto_diags.default <- function(x,

#' @rdname pareto_diags
#' @export
pareto_diags.rvar <- function(x, ...) {
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,
Expand Down Expand Up @@ -216,8 +218,10 @@ 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
) {
warn_r_eff_ignored(r_eff)
if (extra_diags) {
return_k <- TRUE
}
Expand Down Expand Up @@ -262,9 +266,7 @@ pareto_smooth.default <- function(x,
are_log_weights = FALSE,
...) {

if (!is.null(r_eff)) {
r_eff <- as_one_numeric(r_eff)
}
warn_r_eff_ignored(r_eff)
if (!is.null(ndraws_tail)) {
ndraws_tail <- as_one_integer(ndraws_tail)
}
Expand Down Expand Up @@ -293,14 +295,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)) {
Expand Down Expand Up @@ -773,24 +770,31 @@ ps_convergence_rate <- function(k, ndraws, ...) {
rate
}

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
#'
#' 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` or 1 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, ...) {
warn_r_eff_ignored(r_eff)
floor(ifelse(ndraws > 225, 3 * sqrt(ndraws), ndraws / 5))
}

#' Pareto-k diagnostic message
Expand Down
2 changes: 1 addition & 1 deletion R/pit.R
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down
2 changes: 2 additions & 0 deletions R/posterior-package.R
Original file line number Diff line number Diff line change
Expand Up @@ -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 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`.
Expand Down
11 changes: 4 additions & 7 deletions man-roxygen/args-pareto.R
Original file line number Diff line number Diff line change
Expand Up @@ -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` 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
#' printed. Default is `FALSE`.
Expand Down
13 changes: 5 additions & 8 deletions man/pareto_diags.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 5 additions & 8 deletions man/pareto_khat.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

15 changes: 6 additions & 9 deletions man/pareto_smooth.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions man/posterior-package.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 7 additions & 5 deletions man/ps_tail_length.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions tests/testthat/test-pareto_pit.R
Original file line number Diff line number Diff line change
Expand Up @@ -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", {
Expand Down
38 changes: 32 additions & 6 deletions tests/testthat/test-pareto_smooth.R
Original file line number Diff line number Diff line change
Expand Up @@ -80,13 +80,22 @@ 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 = 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", {
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))
})


Expand Down Expand Up @@ -224,6 +233,23 @@ 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("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")

Expand Down Expand Up @@ -322,7 +348,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(
Expand Down
Loading