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 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 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: