calculate_diagnostics: Calculate MCMC-style Diagnostics for Sampling Chains

In topolow: Force-Directed Euclidean Embedding of Dissimilarity Data

Calculate MCMC-style Diagnostics for Sampling Chains

Description

Calculates standard MCMC-style convergence diagnostics for multiple chains from an optimization or sampling run. It computes the R-hat (potential scale reduction factor) and effective sample size (ESS) to help assess if the chains have converged to a stable distribution.

Usage

calculate_diagnostics(chain_files, mutual_size = 500)

Arguments

chain_files	Character vector. Paths to CSV files, where each file represents a chain of samples.
mutual_size	Integer. Number of samples to use from the end of each chain for calculations.

Value

A list object of class topolow_diagnostics containing convergence diagnostics for the MCMC chains.

rhat	A numeric vector of the R-hat (potential scale reduction factor) statistic for each parameter. Values close to 1 indicate convergence.
ess	A numeric vector of the effective sample size for each parameter.
chains	A list of data frames, where each data frame is a cleaned and trimmed MCMC chain.
param_names	A character vector of the parameter names being analyzed.
mutual_size	The integer number of samples used from the end of each chain for calculations.

Examples

# This example demonstrates how to use the function with temporary files.
# Create dummy chain files in a temporary directory
temp_dir <- tempdir()
chain_files <- character(3)
par_names <- c("log_N", "log_k0", "log_cooling_rate", "log_c_repulsion")
sample_data <- data.frame(
  log_N = rnorm(100), log_k0 = rnorm(100),
  log_cooling_rate = rnorm(100), log_c_repulsion = rnorm(100),
  NLL = runif(100), Holdout_MAE = runif(100)
)
for (i in 1:3) {
  chain_files[i] <- file.path(temp_dir, paste0("chain", i, ".csv"))
  write.csv(sample_data, chain_files[i], row.names = FALSE)
}

# Calculate diagnostics
diag_results <- calculate_diagnostics(chain_files, mutual_size = 50)
print(diag_results)

# Clean up the temporary files and directory
unlink(chain_files)
unlink(temp_dir, recursive = TRUE)

topolow documentation built on Aug. 31, 2025, 1:07 a.m.