From d6389f6a5e5e6d270a8084711e36fde50991e1ca Mon Sep 17 00:00:00 2001 From: n-kall Date: Mon, 5 Aug 2024 16:06:52 +0300 Subject: [PATCH 1/3] update reference for nested r-hat to published version --- R/nested_rhat.R | 22 +++++++++---------- ...023.R => ref-margossian-nestedrhat-2024.R} | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) rename man-roxygen/{ref-margossian-nestedrhat-2023.R => ref-margossian-nestedrhat-2024.R} (55%) diff --git a/R/nested_rhat.R b/R/nested_rhat.R index f1b81901..c65f0c95 100644 --- a/R/nested_rhat.R +++ b/R/nested_rhat.R @@ -1,7 +1,7 @@ #' Nested Rhat convergence diagnostic #' #' Compute the nested Rhat convergence diagnostic for a single -#' variable as proposed in Margossian et al. (2023). +#' variable as proposed in Margossian et al. (2024). #' #' @family diagnostics #' @template args-conv @@ -20,11 +20,11 @@ #' Note that there is a slight difference in the calculation of Rhat #' and nested Rhat, as nested Rhat is lower bounded by 1. This means #' that nested Rhat with one chain per superchain will not be -#' exactly equal to basic Rhat (see Footnote 1 in Margossian et -#' al. (2023)). +#' exactly equal to basic Rhat (see Footnote 3 in Margossian et +#' al. (2024)). #' #' @template return-conv -#' @template ref-margossian-nestedrhat-2023 +#' @template ref-margossian-nestedrhat-2024 #' #' @examples #' mu <- extract_variable_matrix(example_draws(), "mu") @@ -78,17 +78,17 @@ rhat_nested.rvar <- function(x, superchain_ids, ...) { superchains <- unique(superchain_ids) - # mean and variance of chains calculated as in rhat + # mean and variance of chains calculated as in Rhat chain_mean <- matrixStats::colMeans2(x) chain_var <- matrixStats::colVars(x, center = chain_mean) # mean of superchains calculated by only including specified chains - # (equation 15 in Margossian et al. 2023) + # (equation 4 in Margossian et al. 2024) superchain_mean <- sapply( superchains, function(k) mean(x[, which(superchain_ids == k)]) ) - # between-chain variance estimate (B_k in equation 18 in Margossian et al. 2023) + # between-chain variance estimate (Bhat_k in equation 7 in Margossian et al. 2024) if (nchains_per_superchain == 1) { var_between_chain <- 0 } else { @@ -98,7 +98,7 @@ rhat_nested.rvar <- function(x, superchain_ids, ...) { ) } - # within-chain variance estimate (W_k in equation 18 in Margossian et al. 2023) + # within-chain variance estimate (What_k in equation 7 in Margossian et al. 2024) if (niterations == 1) { var_within_chain <- 0 } else { @@ -108,12 +108,12 @@ rhat_nested.rvar <- function(x, superchain_ids, ...) { ) } - # between-superchain variance (nB in equation 17 in Margossian et al. 2023) + # between-superchain variance (Bhat_nu in equation 6 in Margossian et al. 2024) var_between_superchain <- var(superchain_mean) - # within-superchain variance (nW in equation 18 in Margossian et al. 2023) + # within-superchain variance (What_nu in equation 7 in Margossian et al. 2024) var_within_superchain <- mean(var_within_chain + var_between_chain) - # nested Rhat (nRhat in equation 19 in Margossian et al. 2023) + # nested Rhat (Rhat_nu in equation 8 in Margossian et al. 2024) sqrt(1 + var_between_superchain / var_within_superchain) } diff --git a/man-roxygen/ref-margossian-nestedrhat-2023.R b/man-roxygen/ref-margossian-nestedrhat-2024.R similarity index 55% rename from man-roxygen/ref-margossian-nestedrhat-2023.R rename to man-roxygen/ref-margossian-nestedrhat-2024.R index 474881e2..da9d00b2 100644 --- a/man-roxygen/ref-margossian-nestedrhat-2023.R +++ b/man-roxygen/ref-margossian-nestedrhat-2024.R @@ -1,5 +1,5 @@ #' @references #' Charles C. Margossian, Matthew D. Hoffman, Pavel Sountsov, Lionel -#' Riou-Durand, Aki Vehtari and Andrew Gelman (2023). Nested R-hat: +#' Riou-Durand, Aki Vehtari and Andrew Gelman (2024). Nested R-hat: #' Assessing the convergence of Markov chain Monte Carlo when running -#' many short chains. arxiv:arXiv:2110.13017 (version 4) +#' many short chains. *Bayesian Analysis*. doi:10.1214/24-BA1453 From fc295b008f0d1bc1743b6cfdf34fbfc89009dcd4 Mon Sep 17 00:00:00 2001 From: n-kall Date: Mon, 5 Aug 2024 16:08:40 +0300 Subject: [PATCH 2/3] fix typo in R-hat reference --- man-roxygen/ref-vehtari-rhat-2021.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man-roxygen/ref-vehtari-rhat-2021.R b/man-roxygen/ref-vehtari-rhat-2021.R index 91ffea91..baaedd17 100644 --- a/man-roxygen/ref-vehtari-rhat-2021.R +++ b/man-roxygen/ref-vehtari-rhat-2021.R @@ -2,5 +2,5 @@ #' Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and #' Paul-Christian Bürkner (2021). Rank-normalization, folding, and #' localization: An improved R-hat for assessing convergence of -#' MCMC (with discussion). *Bayesian Data Analysis*. 16(2), 667-–718. +#' MCMC (with discussion). *Bayesian Analysis*. 16(2), 667-–718. #' doi:10.1214/20-BA1221 From 88b95de3fa830f7aa06a9f1b168a52b51c3fd1da Mon Sep 17 00:00:00 2001 From: n-kall Date: Tue, 6 Aug 2024 10:19:46 +0300 Subject: [PATCH 3/3] render docs --- man/ess_basic.Rd | 2 +- man/ess_bulk.Rd | 2 +- man/ess_quantile.Rd | 2 +- man/ess_sd.Rd | 2 +- man/ess_tail.Rd | 2 +- man/mcse_quantile.Rd | 2 +- man/mcse_sd.Rd | 2 +- man/rhat.Rd | 2 +- man/rhat_basic.Rd | 2 +- man/rhat_nested.Rd | 10 +++++----- 10 files changed, 14 insertions(+), 14 deletions(-) diff --git a/man/ess_basic.Rd b/man/ess_basic.Rd index 47aeec0e..8d485bd6 100755 --- a/man/ess_basic.Rd +++ b/man/ess_basic.Rd @@ -64,7 +64,7 @@ Hall/CRC. Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 Aki Vehtari (2021). Comparison of MCMC effective sample size estimators. diff --git a/man/ess_bulk.Rd b/man/ess_bulk.Rd index 8baada5c..37206b6d 100755 --- a/man/ess_bulk.Rd +++ b/man/ess_bulk.Rd @@ -57,7 +57,7 @@ ess_bulk(d$Sigma) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 Aki Vehtari (2021). Comparison of MCMC effective sample size estimators. diff --git a/man/ess_quantile.Rd b/man/ess_quantile.Rd index f919ad60..4da4635d 100755 --- a/man/ess_quantile.Rd +++ b/man/ess_quantile.Rd @@ -69,7 +69,7 @@ ess_quantile(d$mu, probs = c(0.1, 0.9)) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 } \seealso{ diff --git a/man/ess_sd.Rd b/man/ess_sd.Rd index 91278bf8..16015ed8 100755 --- a/man/ess_sd.Rd +++ b/man/ess_sd.Rd @@ -54,7 +54,7 @@ ess_sd(d$Sigma) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 } \seealso{ diff --git a/man/ess_tail.Rd b/man/ess_tail.Rd index 36b2772c..9e87d8f1 100755 --- a/man/ess_tail.Rd +++ b/man/ess_tail.Rd @@ -57,7 +57,7 @@ ess_tail(d$Sigma) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 Aki Vehtari (2021). Comparison of MCMC effective sample size estimators. diff --git a/man/mcse_quantile.Rd b/man/mcse_quantile.Rd index 4651181e..a7617a0a 100755 --- a/man/mcse_quantile.Rd +++ b/man/mcse_quantile.Rd @@ -66,7 +66,7 @@ mcse_quantile(d$mu) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 } \seealso{ diff --git a/man/mcse_sd.Rd b/man/mcse_sd.Rd index 02f86ebd..726faeb1 100755 --- a/man/mcse_sd.Rd +++ b/man/mcse_sd.Rd @@ -54,7 +54,7 @@ mcse_sd(d$Sigma) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 J. F. Kenney & E. S. Keeping (1951). \emph{Mathematics of Statistics, Vol. II.} diff --git a/man/rhat.Rd b/man/rhat.Rd index 263561cd..6af3b66b 100755 --- a/man/rhat.Rd +++ b/man/rhat.Rd @@ -54,7 +54,7 @@ rhat(d$Sigma) Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 } \seealso{ diff --git a/man/rhat_basic.Rd b/man/rhat_basic.Rd index 762cce0f..04f47433 100755 --- a/man/rhat_basic.Rd +++ b/man/rhat_basic.Rd @@ -62,7 +62,7 @@ Hall/CRC. Aki Vehtari, Andrew Gelman, Daniel Simpson, Bob Carpenter, and Paul-Christian Bürkner (2021). Rank-normalization, folding, and localization: An improved R-hat for assessing convergence of -MCMC (with discussion). \emph{Bayesian Data Analysis}. 16(2), 667-–718. +MCMC (with discussion). \emph{Bayesian Analysis}. 16(2), 667-–718. doi:10.1214/20-BA1221 } \seealso{ diff --git a/man/rhat_nested.Rd b/man/rhat_nested.Rd index 9f91ad05..71f51195 100644 --- a/man/rhat_nested.Rd +++ b/man/rhat_nested.Rd @@ -45,7 +45,7 @@ passing the draws array for that element of the \code{\link{rvar}} to this funct } \description{ Compute the nested Rhat convergence diagnostic for a single -variable as proposed in Margossian et al. (2023). +variable as proposed in Margossian et al. (2024). } \details{ Nested Rhat is a convergence diagnostic useful when @@ -56,8 +56,8 @@ point. Note that there is a slight difference in the calculation of Rhat and nested Rhat, as nested Rhat is lower bounded by 1. This means that nested Rhat with one chain per superchain will not be -exactly equal to basic Rhat (see Footnote 1 in Margossian et -al. (2023)). +exactly equal to basic Rhat (see Footnote 3 in Margossian et +al. (2024)). } \examples{ mu <- extract_variable_matrix(example_draws(), "mu") @@ -69,9 +69,9 @@ rhat_nested(d$Sigma, superchain_ids = c(1, 1, 2, 2)) } \references{ Charles C. Margossian, Matthew D. Hoffman, Pavel Sountsov, Lionel -Riou-Durand, Aki Vehtari and Andrew Gelman (2023). Nested R-hat: +Riou-Durand, Aki Vehtari and Andrew Gelman (2024). Nested R-hat: Assessing the convergence of Markov chain Monte Carlo when running -many short chains. arxiv:arXiv:2110.13017 (version 4) +many short chains. \emph{Bayesian Analysis}. doi:10.1214/24-BA1453 } \seealso{ Other diagnostics: