mcmc_gr_test: Evaluate Gelman-Rubin Diagnostics for User-Supplied Target...

In LugsailGR: Generalized Gelman-Rubin Diagnostic and Effective Sample Size for MCMC

Evaluate Gelman-Rubin Diagnostics for User-Supplied Target Density Function

Description

Runs Markov chain Monte Carlo (MCMC) sampling for a user-supplied probability density function (PDF) or log-likelihood function of variable and parameters with data, and returns upgraded lugsail Gelman-Rubin convergence test statistics, effective sample sizes, parameter estimates, and termination decisions.

Usage

mcmc_gr_test(
  target_pdf,
  data = NULL,
  start_par,
  n_iter = 2000,
  n_chains = 3,
  burn_in = 0.5,
  scale = 0.5,
  alpha = 0.05,
  epsilon = 0.1,
  ...
)

Arguments

target_pdf	Function taking parameter vector par as its first argument and optional data. It should return the probability density value or log-density value for par.
data	Optional data vector, matrix, data.frame, or list passed to target_pdf.
start_par	Initial parameter vector. If named, parameter names will be preserved.
n_iter	Integer, total number of MCMC iterations per chain (default 2000).
n_chains	Integer, number of parallel MCMC chains to generate (default 3).
burn_in	Numeric, fraction of initial burn-in samples to discard (default 0.50).
scale	Numeric or vector, proposal standard deviation for random walk Metropolis-Hastings sampler (default 0.5).
alpha	Numeric, significance level for convergence bound (default 0.05).
epsilon	Numeric, relative volume tolerance (default 0.10).
...	Additional parameters passed to target_pdf.

Value

An object of class "lugsail_gr" containing Gelman-Rubin test statistics, effective sample sizes, cutoff thresholds, parameter estimates, standard errors, and MCMC chain samples.

References

Vats, D. and Knudson, C. (2021). Revisiting the Gelman–Rubin Diagnostic. Statistical Science, 36(4), 518–529. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1214/20-STS812")}.

Examples

# Example 1: Normal distribution target PDF with data
set.seed(42)
true_mean <- 3
my_data <- rnorm(50, mean = true_mean, sd = 1)

# Log-posterior density function for parameter mu
log_post <- function(mu, data) {
  sum(dnorm(data, mean = mu, sd = 1, log = TRUE))
}

# Run diagnostic test
fit <- mcmc_gr_test(target_pdf = log_post, data = my_data, start_par = c(mu = 0), 
                    n_iter = 1000, n_chains = 3)
print(fit)

LugsailGR documentation built on Aug. 5, 2026, 9:08 a.m.