Merge branch 'master' of https://github.com/stan-dev/posterior

Author: paul-buerkner

NEWS.md

@@ -1,5 +1,9 @@
 # posterior 1.7.0
 
+### Enhancements
+
+* Add `truncate` argument to `uniformity_test()` to allow for custom truncation
+
 ### Bug Fixes
 
 * Fix several minor issues occurring in edge cases.
@@ -9,7 +13,7 @@
 * Extend and export several functions related to the generalized
 Pareto distribution for use in other packages. (#408)
 * Support Pareto PIT functionality via `pareto_pit`. (#435)
-* Allow more warnings to be turned off via option 
+* Allow more warnings to be turned off via option
 `posterior.warn_on_merge_chains`.
 * Improve documentation in many places.
 * Improve tests by checking for edge cases.
@@ -41,16 +45,16 @@ Pareto distribution for use in other packages. (#408)
   `pareto_khat_threshold()`, `pareto_min_ss()`, `pareto_convergence_rate()`)
 * `thin_draws()` now automatically thins draws based on ESS by default,
   and non-integer thinning is possible.
-* Matrix multiplication of `rvar`s can now be done with the base matrix 
+* Matrix multiplication of `rvar`s can now be done with the base matrix
   multiplication operator (`%*%`) instead of `%**%` in R >= 4.3.
 * `variables()`, `variables<-()`, `set_variables()`, and `nvariables()` now
   support a `with_indices` argument, which determines whether variable names
   are retrieved/set with (`"x[1]"`, `"x[2]"` ...) or without (`"x"`) indices
   (#208).
 * Add `extract_variable_array()` function to extract variables with indices
   into arrays of iterations x chains x any remaining dimensions (#340).
-* For types that support `factor` variables (`draws_df`, `draws_list`, and 
-  `draws_rvars`), `extract_variable()` and `extract_variable_matrix()` can 
+* For types that support `factor` variables (`draws_df`, `draws_list`, and
+  `draws_rvars`), `extract_variable()` and `extract_variable_matrix()` can
   now return `factor`s.
 
 # posterior 1.5.0
@@ -72,7 +76,7 @@ Pareto distribution for use in other packages. (#408)
 ### Bug Fixes
 
 * Ensure `rfun()` works with primitive functions (#290) and dots arguments (#291).
-* Provide implementations of `vctrs::vec_proxy_equal()`, 
+* Provide implementations of `vctrs::vec_proxy_equal()`,
 `vctrs::vec_proxy_compare()`, and `vctrs::vec_proxy_order()`.
 * Minor future-proofing of `cbind(<rvar>)`, `rbind(<rvar>)`, and `chol(<rvar>)`
   for R 4.4 (#304).
@@ -84,8 +88,8 @@ Pareto distribution for use in other packages. (#408)
 
 ### Bug Fixes
 
-* Delay applying `tibble::num()` formatting to output from `summarise_draws()` 
-  until `print()` is called so that summary output can be easily converted to a 
+* Delay applying `tibble::num()` formatting to output from `summarise_draws()`
+  until `print()` is called so that summary output can be easily converted to a
   vanilla data frame (#275).
 
 
@@ -99,18 +103,18 @@ Pareto distribution for use in other packages. (#408)
 * The `draws_df()`, `draws_list()`, and `draws_rvars()` formats now support
   discrete variables stored as `factors` / `ordered`s (or `rvar_factor`s /
   `rvar_ordered`s). If converted to formats that do not support discrete
-  variables with named levels (`draws_matrix()` and `draws_array()`), 
+  variables with named levels (`draws_matrix()` and `draws_array()`),
   factor-like variables are converted to `numeric`s.
 * Made `match()` and `%in%` generic and added support for `rvar`s to both
   functions.
 * Added `modal_category()`, `entropy()`, and `dissent()` functions for
   summarizing discrete draws.
-* Allow lists of draws objects to be passed as the first argument to 
+* Allow lists of draws objects to be passed as the first argument to
   `bind_draws()` (#253).
 * Improving formatting of `summarise_draws` output via `tibble::num`.
 * `print.rvar()` and `format.rvar()` now default to a smaller number of
   significant digits in more cases, including when printing in data frames.
-  This is controlled by the new `"posterior.digits"` option (see 
+  This is controlled by the new `"posterior.digits"` option (see
   `help("posterior-package")`).
 * Implemented faster `vec_proxy.rvar()` and `vec_restore.rvar()`, improving
   performance of `rvar`s in `tibble`s (and elsewhere `vctrs` is used).
@@ -144,9 +148,9 @@ Pareto distribution for use in other packages. (#408)
 * Support remaining modes of `diag()` for `rvar`s (#246).
 * Better parsing for named indices in `as_draws_rvars()`, including nested use
 of `[`, like `x[y[1],2]` (#243).
-* Allow 0-length `rvar`s with `ndraws() > 1` (#242). 
+* Allow 0-length `rvar`s with `ndraws() > 1` (#242).
 * Ensure 0-length `rvar`s can be cast to `draws` formats (#242).
-* Don't treat length-1 `rvar`s with more than 1 dimension as scalars when 
+* Don't treat length-1 `rvar`s with more than 1 dimension as scalars when
 casting to other formats (#248).
 
 
@@ -173,9 +177,9 @@ casting to other formats (#248).
 
 ### Bug Fixes
 
-* fix hidden variables in `bind_draws.draws_df` when binding 
+* fix hidden variables in `bind_draws.draws_df` when binding
 more than two objects thanks to Jouni Helske (#204)
-* fix output of `pillar::glimpse()` when used on a data frame containing 
+* fix output of `pillar::glimpse()` when used on a data frame containing
 `rvar`s (#210)
 * drop `"draws"` and `"draws_df"` classes from `draws_df` objects if meta data
 columns are removed by a `dplyr` operation (#202)
@@ -187,7 +191,7 @@ columns are removed by a `dplyr` operation (#202)
 
 ### Enhancements
 
-* use `matrixStats` to speed up convergence functions (#190) and 
+* use `matrixStats` to speed up convergence functions (#190) and
 `rvar` summaries (#200)
 
 ### Bug Fixes
@@ -200,7 +204,7 @@ Karl Dunkle Werner and Alexey Stukalov (#188)
 ### Other Changes
 
 * No longer check for constant-per-chain input in effective
-sample size diagnostics as this is overly conservative 
+sample size diagnostics as this is overly conservative
 especially for `ess_tail`. (#198)
 
 

R/uniformity_test.R

@@ -29,6 +29,10 @@
 #' @param pit Numeric vector of PIT values in `[0, 1]`.
 #' @param test Character string. One of `"POT"`, `"PIET"`, or `"PRIT"`.
 #'   See details above.
+#' @param truncate Boolean. Determines whether the truncated (TRUE) or
+#'   untruncated (FALSE) Cauchy combination test (CCT) is used. By default it
+#'   is NULL in which case the truncated CCT is computed for `POT` and `PRIT`
+#'   and the untruncated CCT is computed for `PIET`.
 #'
 #' @return A list with components:
 #'   * `pvalue`: Global p-value from the Cauchy combination test.
@@ -49,13 +53,10 @@
 #'   correlations. arXiv preprint arXiv:2506.12489.
 #'
 #' @export
-uniformity_test <- function(pit, test) {
+uniformity_test <- function(pit, test, truncate = NULL) {
 
-  choices <- c("POT", "PRIT", "PIET")
-  if (!test %in% choices) {
-    stop("'test' should be one of ", paste(dQuote(choices), collapse = ", "), call. = FALSE)
-  }
-  test <- match.arg(test, choices = choices)
+  test <- rlang::arg_match(test, values = c("POT", "PRIT", "PIET"))
+  if (is.null(truncate)) truncate <- (test != "PIET")
 
   test_fn <- switch(test,
       POT  = .pot_test,
@@ -67,7 +68,7 @@ uniformity_test <- function(pit, test) {
     std_cauchy_values    <- .compute_cauchy(test_fn(pit_sorted))
     p_value_CCT          <- .cauchy_combination_test(
       test_fn(pit),
-      truncate = test != "PIET"
+      truncate = truncate
     )
     pointwise_contributions  <- .compute_shapley_values(std_cauchy_values)
 
@@ -83,9 +84,9 @@ uniformity_test <- function(pit, test) {
 
 #' Compute Shapley values
 #'
-#' Calculates the average marginal contribution of players across 
+#' Calculates the average marginal contribution of players across
 #' all random arrival orders in a cooperative game.
-#' Used to provide a principled approach for quantifying 
+#' Used to provide a principled approach for quantifying
 #' point-specific influences in a way that reflects local miscalibration.
 #'
 #' @param x Numeric vector of Cauchy-transformed PIT values.
@@ -99,11 +100,11 @@ uniformity_test <- function(pit, test) {
   if (n == 1) {
     return(0)
   }
-  
+
   # Harmonic number
   # H_n = sum(1/i) for i = 1 to n
   harmonic_number <- sum(1 / seq_len(n))
-  
+
   shapley_values <- numeric(n)
   for (i in seq_len(n)) {
     mean_others <- sum(x[-i]) / (n - 1)
@@ -120,7 +121,7 @@ uniformity_test <- function(pit, test) {
 #' H0: The value obtained via the inverse CDF transformation F^(-1)(x_i)
 #' follows the distribution of X under uniformity.
 #' HA: The p-value p_(i) provides evidence against uniformity.
-#' 
+#'
 #' @param x Numeric vector of PIT values in `[0, 1]`.
 #' @return Numeric vector of p-values.
 #' @noRd
@@ -138,7 +139,7 @@ uniformity_test <- function(pit, test) {
 #' under uniformity.
 #' HA: The p-value p_(i) provides evidence against uniformity
 #' at the i-th order statistic u_(i).
-#' 
+#'
 #' @param x Numeric vector of PIT values in `[0, 1]`.
 #' @return Numeric vector of p-values.
 #' @noRd
@@ -153,12 +154,12 @@ uniformity_test <- function(pit, test) {
 }
 
 #' Pointwise Rank-based Individual Tests Combination (PRIT)
-#' 
+#'
 #' Uniformity test based on a binomial distribution.
 #' H0: The number of observations falling at or below x_i
 #' follows a binomial distribution under uniformity.
 #' HA: The p-value p_i provides evidence against uniformity.
-#' 
+#'
 #' @param x Numeric vector of PIT values in `[0, 1]`.
 #' @return Numeric vector of p-values.
 #' @noRd
@@ -168,7 +169,7 @@ uniformity_test <- function(pit, test) {
   probs1 <- pbinom(scaled_ecdf - 1, n, x)
   probs2 <- pbinom(scaled_ecdf, n, x)
   p_values <- 2 * pmin(1 - probs1, probs2)
-  
+
   return(p_values)
 }