# MCMC convergence diagnostics from scratch
# https://tidyecology.com/posts/mcmc-convergence-diagnostics/
#
# The R code of this Tidy Ecology tutorial, chunk by chunk, in the order of the post.
# Run it top to bottom in a fresh R session. Code the post shows but does not run
# is commented out. The prose, and the numbers it quotes, are in the post itself.
# Post last modified: 2026-10-15

## ---- setup ----
library(ggplot2)
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE,
                      fig.align = "center", dpi = 150)
paper <- "#f5f4ee"; ink <- "#16241d"; forest <- "#275139"; sage <- "#93a87f"
line_col <- "#dad9ca"; faint <- "#5d6b61"; accent2 <- "#c9b458"; warm <- "#cda23f"; brick <- "#b5534e"
theme_te <- function(base = 12) theme_minimal(base_size = base) + theme(
  plot.background = element_rect(fill = paper, colour = NA),
  panel.background = element_rect(fill = paper, colour = NA),
  panel.grid.major = element_line(colour = line_col, linewidth = 0.3),
  panel.grid.minor = element_blank(),
  axis.title = element_text(colour = ink), axis.text = element_text(colour = faint),
  plot.title = element_text(colour = ink, face = "bold"),
  plot.subtitle = element_text(colour = faint),
  legend.title = element_text(colour = ink), legend.text = element_text(colour = faint),
  legend.position = "top",
  strip.text = element_text(colour = ink, face = "bold"))
theme_set(theme_te())

## ---- target ----
log_post <- function(theta) log(0.5 * dnorm(theta, -4, 0.55) + 0.5 * dnorm(theta, 4, 0.55))

metropolis <- function(n_iter, prop_sd, init) {
  draws <- numeric(n_iter); cur <- init; cur_lp <- log_post(cur); acc <- 0L
  for (i in seq_len(n_iter)) {
    prop <- cur + rnorm(1, 0, prop_sd); prop_lp <- log_post(prop)
    if (log(runif(1)) < prop_lp - cur_lp) { cur <- prop; cur_lp <- prop_lp; acc <- acc + 1L }
    draws[i] <- cur
  }
  list(draws = draws, acc_rate = acc / n_iter)
}

# exact reference by a fine grid
gx <- seq(-8, 8, length.out = 200001)
gd <- 0.5 * dnorm(gx, -4, 0.55) + 0.5 * dnorm(gx, 4, 0.55)
gd <- gd / (sum(gd) * (gx[2] - gx[1]))
true_mean <- sum(gx * gd) * (gx[2] - gx[1])
true_q <- approx(cumsum(gd) * (gx[2] - gx[1]), gx, c(0.025, 0.975))$y
round(c(true_mean = true_mean, lower = true_q[1], upper = true_q[2]), 3)

## ---- solo ----
n_iter <- 15000L; burn <- 1500L
keep <- (burn + 1):n_iter
set.seed(101)
solo <- metropolis(n_iter, prop_sd = 0.5, init = -4)$draws[keep]
round(c(mean = mean(solo), sd = sd(solo),
        lower = unname(quantile(solo, 0.025)), upper = unname(quantile(solo, 0.975))), 3)

## ---- diagnostics-functions ----
rhat_split <- function(mat) {                 # mat: iterations x chains
  n <- nrow(mat); half <- n %/% 2
  sp <- cbind(mat[1:half, , drop = FALSE], mat[(n - half + 1):n, , drop = FALSE])
  n2 <- half
  cm <- colMeans(sp); cv <- apply(sp, 2, var)
  W <- mean(cv); B <- n2 * var(cm)             # within and between variance
  var_plus <- ((n2 - 1) / n2) * W + B / n2
  sqrt(var_plus / W)
}

## ---- rhat-narrow ----
starts <- c(-7, -3, 3, 7)
set.seed(202)
narrow <- sapply(starts, function(s) metropolis(n_iter, 0.5, s)$draws)
narrow_k <- narrow[keep, ]
rhat_narrow <- rhat_split(narrow_k)
round(c(chain_means = colMeans(narrow_k)), 2)

## ---- fig-traces ----
K <- 1500
chain_cols <- c("1" = forest, "2" = warm, "3" = brick, "4" = sage)
solo_df <- data.frame(iter = 1:K, value = solo[1:K], chain = "1",
                      panel = "A single chain looks converged (split R-hat 1.00)")
nar <- narrow_k[1:K, ]
narrow_df <- do.call(rbind, lapply(1:4, function(j)
  data.frame(iter = 1:K, value = nar[, j], chain = as.character(j),
             panel = "Four chains from spread starts disagree (R-hat 7.9)")))
tr <- rbind(solo_df, narrow_df)
tr$panel <- factor(tr$panel, levels = c("A single chain looks converged (split R-hat 1.00)",
                                        "Four chains from spread starts disagree (R-hat 7.9)"))
ggplot(tr, aes(iter, value, colour = chain)) +
  geom_line(linewidth = 0.3) +
  facet_wrap(~panel, ncol = 1) +
  scale_colour_manual(values = chain_cols, guide = "none") +
  labs(x = "iteration (after burn-in)", y = expression(theta),
       title = "One chain is not evidence of convergence",
       subtitle = "the same narrow proposal, run once, hides the second mode entirely")

## ---- ess-function ----
ess_bda <- function(mat) {
  n <- nrow(mat); m <- ncol(mat)
  cm <- colMeans(mat); cv <- apply(mat, 2, var)
  W <- mean(cv); B <- n * var(cm)
  var_plus <- ((n - 1) / n) * W + B / n
  acov <- sapply(seq_len(m), function(j)
    acf(mat[, j], lag.max = n - 1, type = "covariance", plot = FALSE, demean = TRUE)$acf)
  acov_bar <- rowMeans(acov)                     # index 1 is lag 0
  rho <- 1 - (W - acov_bar[-1]) / var_plus         # combined autocorrelation
  tau <- 1 + 2 * rho[1]; t <- 2                    # Geyer initial positive sequence:
  while (t + 1 <= length(rho)) {                   # lags 0 and 1, then pairs (2, 3), (4, 5), ...
    pair <- rho[t] + rho[t + 1]
    if (pair < 0) break
    tau <- tau + 2 * pair; t <- t + 2
  }
  (m * n) / tau
}
ess_narrow <- ess_bda(narrow_k)
round(c(stored_draws = length(narrow_k), effective = ess_narrow), 0)

## ---- wide ----
set.seed(303)
wide <- sapply(starts, function(s) metropolis(n_iter, 4.0, s)$draws)
wide_k <- wide[keep, ]
rhat_wide <- rhat_split(wide_k)
ess_wide  <- ess_bda(wide_k)
round(c(rhat = rhat_wide, ess = ess_wide, pooled_mean = mean(wide_k),
        frac_left = mean(wide_k < 0)), 3)

## ---- fig-posterior ----
dens <- data.frame(x = gx, dens = gd)
hist_df <- rbind(
  data.frame(v = solo, src = "single stuck chain"),
  data.frame(v = as.vector(wide_k), src = "four wide chains pooled"))
hist_df$src <- factor(hist_df$src, levels = c("four wide chains pooled", "single stuck chain"))
ggplot() +
  geom_histogram(data = hist_df, aes(v, after_stat(density), fill = src),
                 binwidth = 0.2, colour = NA, alpha = 0.55, position = "identity") +
  geom_line(data = dens, aes(x, dens), colour = ink, linewidth = 0.7) +
  scale_fill_manual(values = c("four wide chains pooled" = sage, "single stuck chain" = brick), name = NULL) +
  coord_cartesian(xlim = c(-7, 7)) +
  labs(x = expression(theta), y = "density",
       title = "The stuck chain saw only half the posterior",
       subtitle = "black: true target; the trapped chain misses the right mode entirely")
