Fast convergence plots for R-hat (samplers-only), thresholded

Builds samplers-only convergence diagnostics based on \(\hat{R}\) with:

1. median \(\hat{R}\) by family (bar chart with threshold line), and

2. top-k worst nodes by \(\hat{R}\) (bar chart with threshold line). configurable threshold (default 1.01). Prefers Rhat_split if available, falls back to Rhat_classic otherwise. Produces:

3. median R-hat by family (bar chart with threshold line), and

4. top-k worst nodes by R-hat (bar chart with threshold line).

Usage

plot_convergence_rhat_sampled_fast(
  diag_tbl,
  threshold = 1.01,
  sampled_only = TRUE,
  conf.mcmc = NULL,
  samples_ml = NULL,
  out_dir = NULL,
  top_k = 20L,
  prefer_split = TRUE
)

Arguments

diag_tbl

A data.frame with at least column target and one of Rhat_split or Rhat_classic having finite values.

threshold

Numeric; R-hat reference line (default 1.01).

sampled_only

Logical (default TRUE). When TRUE, keep only nodes that are targets of configured samplers and also present in samples_ml. Raises an error if none remain (strict behavior).

conf.mcmc

Nimble MCMC configuration (required when sampled_only=TRUE).

samples_ml

A coda::mcmc.list providing column names to intersect with sampler targets.

out_dir

Optional output directory. Saves: Rhat_median_by_family__samplers_only_thr_*.png, TopK_worst_Rhat__samplers_only_thr_*.png, and two CSV summaries.

top_k

Integer; number of worst nodes by R-hat to display (default 20L).

prefer_split

Logical; if TRUE (default), use Rhat_split when available/finite, otherwise fallback to Rhat_classic.

Value

(invisible) A list with ggplot objects and tables: list(p_family, p_top, table_family, table_top, threshold).

Examples

if (FALSE) { # \dontrun{
conf <- nimble::configureMCMC(m)
rhat_res <- plot_convergence_rhat_sampled_fast(
  diag_tbl     = diag_tbl,
  threshold    = 1.01,
  sampled_only = TRUE,
  conf.mcmc    = conf,
  samples_ml   = samples_mla,
  out_dir      = "outputs/diagnostics_fast_rhat",
  top_k        = 20L,
  prefer_split = TRUE
)
} # }