rhat: Split-\widehat{R} convergence diagnostic

In choicer: Discrete Choice Models for Economic Applications

Split-\widehat{R} convergence diagnostic

Description

Computes the split-\widehat{R} (potential scale reduction factor) of Gelman et al. for each column of a matrix of posterior draws. Every chain is split in half, so the diagnostic detects non-stationarity within a single chain as well as disagreement across chains; values near 1 indicate convergence, and values above roughly 1.05 warrant a longer run.

Usage

rhat(draws, rank = FALSE)

Arguments

draws

A matrix of posterior draws (rows = iterations, columns = parameters) for a single chain, or a list of such matrices (one per chain, identical dimensions).

rank

Logical; if FALSE (default) computes the classic split \widehat{R} (unchanged from prior releases, bit-for-bit). If TRUE, computes the rank-normalized, folded \widehat{R} of Vehtari, Gelman, Simpson, Carpenter & Buerkner (2021, Bayesian Analysis): the max of a bulk (rank-normalized draws) and a fold (rank- normalized absolute deviation from the pooled median) split-R-hat, which is more robust to heavy tails and scale differences across chains.

Value

Named numeric vector with one \widehat{R} per parameter (NA for parameters with zero variance).

Examples

set.seed(42)
draws <- matrix(rnorm(2000), ncol = 2,
                dimnames = list(NULL, c("a", "b")))
rhat(draws)          # ~1: white noise is stationary
drifting <- cbind(a = cumsum(rnorm(1000)))
rhat(drifting)       # >> 1: a random walk is not
rhat(draws, rank = TRUE)   # rank-normalized variant

choicer documentation built on Sept. 5, 2026, 1:07 a.m.