diff --git a/NEWS.md b/NEWS.md index 6c84f577..a9eb107b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -10,6 +10,10 @@ 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()` warns if all tail values are the same, with the class +`posterior_warning_pareto_constant_tail`. +* Add the argument `max_threshold` to `ps_khat_threshold()`. +* Improve efficiency of `is_constant()` and `ps_tail_length()`. ### Bug Fixes diff --git a/R/misc.R b/R/misc.R index b19d60f4..d17ed040 100644 --- a/R/misc.R +++ b/R/misc.R @@ -196,10 +196,11 @@ isNA <- function(x) { #' @keywords internal #' @export is_constant <- function(x, tol = .Machine$double.eps) { - r <- range(x) - spread <- r[2] - r[1] + lo <- min(x) + hi <- max(x) + spread <- hi - lo # the equality check covers all-zero and all-infinite x - r[1] == r[2] || (is.finite(spread) && spread <= tol * max(abs(r))) + lo == hi || (is.finite(spread) && spread <= tol * max(abs(lo), abs(hi))) } # collapse variables via commas for pretty printing diff --git a/R/pareto_smooth.R b/R/pareto_smooth.R index ed2b0bef..0595db4f 100644 --- a/R/pareto_smooth.R +++ b/R/pareto_smooth.R @@ -342,16 +342,19 @@ pareto_smooth.default <- function(x, ndraws_tail = ndraws_tail, tail = "left", are_log_weights = are_log_weights, + warn_constant_tail = FALSE, ... ) left_k <- smoothed$k # right tail - smoothed <-ps_tail( + smoothed <- ps_tail( x = smoothed$x, ndraws_tail = ndraws_tail, tail = "right", are_log_weights = are_log_weights, + # warn only if k is NA for both tails + warn_constant_tail = is.na(left_k), ... ) right_k <- smoothed$k @@ -483,6 +486,8 @@ pareto_convergence_rate.rvar <- function(x, ...) { #' @param are_log_weights (logical) Are the draws log weights? Default is #' `FALSE`. If `TRUE` computation will take into account that the #' draws are log weights, and only right tail will be smoothed. +#' @param warn_constant_tail (logical) Warn if all tail values are the +#' same? Default is `TRUE`. #' @template args-methods-dots #' @template ref-vehtari-paretosmooth-2022 #' @seealso [`pareto_smooth`] for the user-facing function. @@ -493,6 +498,7 @@ ps_tail <- function(x, smooth_draws = TRUE, tail = c("right", "left"), are_log_weights = FALSE, + warn_constant_tail = TRUE, ... ) { @@ -510,7 +516,7 @@ ps_tail <- function(x, x <- x - max(x) } - tail <- match.arg(tail) + tail <- match.arg(tail, c("right", "left")) if (tail == "left") { x <- -x } @@ -519,7 +525,14 @@ ps_tail <- function(x, ix_tail <- selection$ix draws_tail <- x[ix_tail] - if (is_constant(draws_tail)) { + if (is_constant(draws_tail[c(1L, ndraws_tail)])) { + if (warn_constant_tail) { + warning_no_call( + "Can't fit generalized Pareto distribution ", + "because all tail values are the same.", + class = "posterior_warning_pareto_constant_tail" + ) + } if (tail == "left") { x <- -x } @@ -531,7 +544,7 @@ ps_tail <- function(x, cutoff <- selection$cutoff if (are_log_weights) { - smoothed <- ps_tail_sorted_log_ratios( + smoothed <- .ps_tail_sorted_log_ratios( x = draws_tail, cutoff = cutoff, smooth_draws = smooth_draws, @@ -615,7 +628,12 @@ ps_tail_sorted_log_ratios <- function(x, cutoff, smooth_draws = TRUE, ...) { if (is_constant(x)) { return(list(tail = x, k = NA)) } + .ps_tail_sorted_log_ratios(x, cutoff, smooth_draws = smooth_draws, ...) +} +# Internal version without input checks. The caller must give a sorted, +# non-constant x. +.ps_tail_sorted_log_ratios <- function(x, cutoff, smooth_draws = TRUE, ...) { smoothed <- .ps_tail_sorted( x = exp(x), excess = exp_x_minus_exp_y(x, cutoff), @@ -724,11 +742,17 @@ ps_min_ss <- function(k, ...) { #' [`pareto_diags`]. #' @family helper-functions #' @param ndraws number of draws +#' @param max_threshold (numeric) upper bound for the threshold. Default is +#' `Inf`, which means no bound. Algorithm 1 in Vehtari et al. (2024) uses 0.7. #' @param ... unused #' @return threshold #' @export -ps_khat_threshold <- function(ndraws, ...) { - 1 - 1 / log10(ndraws) +ps_khat_threshold <- function(ndraws, max_threshold = Inf, ...) { + out <- 1 - 1 / log10(ndraws) + if (max_threshold < Inf) { + out[out > max_threshold] <- max_threshold + } + out } #' Pareto convergence rate @@ -785,12 +809,7 @@ ps_convergence_rate <- function(k, ndraws, ...) { #' @return tail length #' @export ps_tail_length <- function(ndraws, r_eff, ...) { - floor( - ifelse( - ndraws * r_eff > 225, - 3 * sqrt(ndraws / r_eff), - ndraws / 5) - ) + floor(pmin(ndraws / 5, 3 * sqrt(ndraws / r_eff))) } #' Pareto-k diagnostic message diff --git a/R/posterior-package.R b/R/posterior-package.R index c33a4fd7..8dc65b40 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_constant_tail`: The generalized Pareto +#' distribution was not fitted because all tail values are the same. #' #' The error signaled when all weights are zero has the class #' `posterior_error_degenerate_weights`. diff --git a/man/posterior-package.Rd b/man/posterior-package.Rd index 79313766..72d33617 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_constant_tail}: The generalized Pareto +distribution was not fitted because all tail values are the same. } The error signaled when all weights are zero has the class diff --git a/man/ps_khat_threshold.Rd b/man/ps_khat_threshold.Rd index 75b6c1e2..60b2a746 100644 --- a/man/ps_khat_threshold.Rd +++ b/man/ps_khat_threshold.Rd @@ -4,11 +4,14 @@ \alias{ps_khat_threshold} \title{Pareto k-hat threshold} \usage{ -ps_khat_threshold(ndraws, ...) +ps_khat_threshold(ndraws, max_threshold = Inf, ...) } \arguments{ \item{ndraws}{number of draws} +\item{max_threshold}{(numeric) upper bound for the threshold. Default is +\code{Inf}, which means no bound. Algorithm 1 in Vehtari et al. (2024) uses 0.7.} + \item{...}{unused} } \value{ diff --git a/man/ps_tail.Rd b/man/ps_tail.Rd index 376e9b3c..599cd182 100644 --- a/man/ps_tail.Rd +++ b/man/ps_tail.Rd @@ -12,6 +12,7 @@ ps_tail( smooth_draws = TRUE, tail = c("right", "left"), are_log_weights = FALSE, + warn_constant_tail = TRUE, ... ) } @@ -39,6 +40,9 @@ ps_tail( \code{FALSE}. If \code{TRUE} computation will take into account that the draws are log weights, and only right tail will be smoothed.} +\item{warn_constant_tail}{(logical) Warn if all tail values are the +same? Default is \code{TRUE}.} + \item{...}{Arguments passed to individual methods (if applicable).} } \description{ diff --git a/tests/testthat/test-pareto_smooth.R b/tests/testthat/test-pareto_smooth.R index 78cb3500..77ade12b 100644 --- a/tests/testthat/test-pareto_smooth.R +++ b/tests/testthat/test-pareto_smooth.R @@ -4,11 +4,16 @@ test_that("pareto_khat handles constant tail correctly", { # should be the same as the right tail x <- c(rep(-100, 10), sort(rnorm(100))) - expect_true(is.na(pareto_khat(x, tail = "left", ndraws_tail = 10))) - expect_equal( - pareto_khat(x, tail = "right", ndraws_tail = 10), - pareto_khat(x, tail = "both", ndraws_tail = 10) + expect_warning( + k_left <- pareto_khat(x, tail = "left", ndraws_tail = 10), + class = "posterior_warning_pareto_constant_tail" ) + expect_true(is.na(k_left)) + # the constant left tail gives no warning, because k is not NA + expect_no_warning( + k_both <- pareto_khat(x, tail = "both", ndraws_tail = 10) + ) + expect_equal(pareto_khat(x, tail = "right", ndraws_tail = 10), k_both) }) @@ -18,9 +23,37 @@ test_that("pareto_khat handles both tails being constant correctly", { # left and right tails are constant, so khat should be NA in all cases x <- c(rep(-100, 10), sort(rnorm(100)), rep(100, 10)) - expect_true(is.na(pareto_khat(x, tail = "left", ndraws_tail = 10))) - expect_true(is.na(pareto_khat(x, tail = "right", ndraws_tail = 10))) - expect_true(is.na(pareto_khat(x, tail = "both", ndraws_tail = 10))) + for (tail in c("left", "right", "both")) { + expect_warning( + k <- pareto_khat(x, tail = tail, ndraws_tail = 10), + class = "posterior_warning_pareto_constant_tail" + ) + expect_true(is.na(k)) + } + +}) + + +test_that("pareto_khat with tail = 'both' warns only if k is NA", { + + set.seed(1) + mid <- sort(rnorm(100)) + const <- rep(100, 10) + # the 3 smallest tail values are equal, so gpdfit gives k = NA + ties <- c(5, 5, 5, 6:12) + + # only the left tail is constant: k comes from the right tail + expect_no_warning( + k <- pareto_khat(c(-const, mid), tail = "both", ndraws_tail = 10) + ) + expect_false(is.na(k)) + + # left tail with ties, right tail constant: k is NA + expect_warning( + k <- pareto_khat(c(-ties, mid, const), tail = "both", ndraws_tail = 10), + class = "posterior_warning_pareto_constant_tail" + ) + expect_true(is.na(k)) }) @@ -30,8 +63,9 @@ test_that("pareto_smooth handles non-constant x with constant tail", { # x is non-constant but the right tail is constant x <- c(seq(-3, 3, length.out = 90), rep(5, 10)) - expect_no_error( - ps <- pareto_smooth(x, tail = "right", ndraws_tail = 10, return_k = TRUE, verbose = FALSE) + expect_warning( + ps <- pareto_smooth(x, tail = "right", ndraws_tail = 10, return_k = TRUE, verbose = FALSE), + class = "posterior_warning_pareto_constant_tail" ) expect_true(is.na(ps$diagnostics$khat)) expect_equal(ps$x, x) @@ -386,11 +420,44 @@ test_that("ps_tail_sorted_log_ratios requires a sorted tail", { test_that("check ps_tail behavior for constant draws_tail", { x <- log(replicate(10, 0.3)) - tail <- ps_tail(x, ndraws_tail = 10, tail = "left") + expect_warning( + tail <- ps_tail(x, ndraws_tail = 10, tail = "left"), + class = "posterior_warning_pareto_constant_tail" + ) # output has expected return values expect_equal(x, tail$x) expect_true(is.na(tail$k)) + + # warn_constant_tail = FALSE gives no warning and the same output + expect_no_warning( + tail2 <- ps_tail(x, ndraws_tail = 10, tail = "left", warn_constant_tail = FALSE) + ) + expect_equal(tail2, tail) +}) + + +test_that("ps_tail_length gives the same values as the old ifelse version", { + old_tail_length <- function(ndraws, r_eff) { + floor(ifelse(ndraws * r_eff > 225, 3 * sqrt(ndraws / r_eff), ndraws / 5)) + } + # the first 4 cases have ndraws * r_eff == 225, where the 2 branches meet + ndraws <- c(225, 1125, 450, 100, 4000, 1e5, 10) + r_eff <- c(1, 0.2, 0.5, 2.25, 1, 0.01, 1) + expect_equal(ps_tail_length(ndraws, r_eff), old_tail_length(ndraws, r_eff)) + expect_equal(ps_tail_length(225, 1), 45) + expect_true(is.na(ps_tail_length(1000, NA))) +}) + + +test_that("ps_khat_threshold caps the threshold at max_threshold", { + ndraws <- c(10, 4000, 1e6) + expect_equal(ps_khat_threshold(ndraws), 1 - 1 / log10(ndraws)) + expect_equal( + ps_khat_threshold(ndraws, max_threshold = 0.7), + pmin(1 - 1 / log10(ndraws), 0.7) + ) + expect_true(is.na(ps_khat_threshold(NA, max_threshold = 0.7))) })