# Bayesian hierarchical models with MCMC
# https://tidyecology.com/posts/bayesian-hierarchical-model-mcmc/
#
# 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-08

## ---- 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())

## ---- data ----
set.seed(4217)
J <- 10L
n_j <- c(2, 2, 3, 3, 4, 5, 6, 8, 10, 12)          # visits per site (uneven effort)
mu_true <- log(5); tau_true <- 0.6                 # true hyperparameters
alpha_true <- rnorm(J, mu_true, tau_true)          # true site log-rates
y <- lapply(seq_len(J), function(j) rpois(n_j[j], exp(alpha_true[j])))
S <- sapply(y, sum); ybar <- S / n_j               # site totals and mean counts
nopool <- log(pmax(ybar, 0.5))                     # each site alone (log scale)
pool   <- log(sum(S) / sum(n_j))                   # one rate for all sites
round(rbind(visits = n_j, mean_count = ybar), 2)

## ---- sampler ----
# log full conditional for alpha_j (up to a constant):
#   S_j * a - n_j * exp(a) - (a - mu)^2 / (2 tau^2)
mwg <- function(n_iter, prop_sd = 0.25, init_mu = 0, init_tau2 = 1) {
  a <- rep(init_mu, J); mu <- init_mu; tau2 <- init_tau2
  A <- matrix(0, n_iter, J); MU <- numeric(n_iter); TAU2 <- numeric(n_iter); acc <- 0L
  for (t in seq_len(n_iter)) {
    for (j in seq_len(J)) {                                   # Metropolis for each alpha_j
      prop <- a[j] + rnorm(1, 0, prop_sd)
      lp_cur  <- S[j] * a[j] - n_j[j] * exp(a[j]) - (a[j] - mu)^2 / (2 * tau2)
      lp_prop <- S[j] * prop - n_j[j] * exp(prop) - (prop - mu)^2 / (2 * tau2)
      if (log(runif(1)) < lp_prop - lp_cur) { a[j] <- prop; acc <- acc + 1L }
    }
    mu   <- rnorm(1, mean(a), sqrt(tau2 / J))                 # Gibbs for mu
    tau2 <- 1 / rgamma(1, shape = J / 2, rate = sum((a - mu)^2) / 2)   # Gibbs for tau^2
    A[t, ] <- a; MU[t] <- mu; TAU2[t] <- tau2
  }
  list(A = A, mu = MU, tau2 = TAU2, acc = acc / (n_iter * J))
}

n_iter <- 20000L; burn <- 2000L; keep <- (burn + 1):n_iter
starts <- c(-1, 0.5, 2, 3.5)                                  # over-dispersed starts
set.seed(555)
chains <- lapply(starts, function(s) mwg(n_iter, prop_sd = 0.25, init_mu = s))
acc <- mean(sapply(chains, function(c) c$acc))
mu_draws  <- unlist(lapply(chains, function(c) c$mu[keep]))
tau_draws <- sqrt(unlist(lapply(chains, function(c) c$tau2[keep])))
A_draws   <- do.call(rbind, lapply(chains, function(c) c$A[keep, , drop = FALSE]))
alpha_pm  <- colMeans(A_draws)
round(c(acceptance = acc,
        mu_mean = mean(mu_draws), mu_lo = quantile(mu_draws, .025), mu_hi = quantile(mu_draws, .975),
        tau_mean = mean(tau_draws), tau_lo = quantile(tau_draws, .025), tau_hi = quantile(tau_draws, .975)), 3)

## ---- rhat ----
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)
  sqrt((((n2 - 1) / n2) * W + B / n2) / W)
}
rhat_mu    <- rhat_split(sapply(chains, function(c) c$mu[keep]))
rhat_tau   <- rhat_split(sapply(chains, function(c) sqrt(c$tau2[keep])))
rhat_alpha <- sapply(seq_len(J), function(j) rhat_split(sapply(chains, function(c) c$A[keep, j])))
round(c(rhat_mu = rhat_mu, rhat_tau = rhat_tau, rhat_alpha_max = max(rhat_alpha)), 3)

## ---- fig-shrinkage ----
grand <- exp(pool); nopool_c <- exp(nopool); partial_c <- exp(alpha_pm)
ci <- t(apply(A_draws, 2, function(col) exp(quantile(col, c(0.025, 0.975)))))
seg <- data.frame(site = factor(seq_len(J)), n = n_j, nopool = nopool_c, partial = partial_c,
                  lo = ci[, 1], hi = ci[, 2])
seg$x <- 2 + (seq_len(J) - (J + 1) / 2) * 0.022   # spread the partial column so each interval is readable
long <- rbind(data.frame(site = seg$site, n = seg$n, x = 1, y = seg$nopool),
              data.frame(site = seg$site, n = seg$n, x = seg$x, y = seg$partial))
ggplot() +
  geom_hline(yintercept = grand, colour = faint, linetype = "longdash", linewidth = 0.4) +
  geom_line(data = long, aes(x, y, group = site, colour = n), linewidth = 0.7) +
  geom_point(data = long, aes(x, y, colour = n), size = 2) +
  geom_errorbar(data = seg, aes(x = x, ymin = lo, ymax = hi, colour = n), width = 0.018, linewidth = 0.5) +
  scale_colour_gradient(low = brick, high = forest, name = "visits per site (n)") +
  scale_x_continuous(breaks = c(1, 2),
                     labels = c("no pooling\n(each site alone)", "partial pooling\n(hierarchical)"),
                     limits = c(0.8, 2.35)) +
  annotate("text", x = 2.33, y = grand, label = "grand mean", hjust = 1, vjust = -0.6,
           colour = faint, size = 3) +
  labs(x = NULL, y = "estimated mean count per visit",
       title = "Site estimates under no pooling and under partial pooling",
       subtitle = "each line is one site; the dashed line is the grand mean")

## ---- shrinkage-numbers ----
poor <- 2L    # index of a site visited twice
rich <- 10L   # index of the site visited twelve times
round(c(poor_visits = n_j[poor], poor_raw = exp(nopool[poor]), poor_partial = exp(alpha_pm[poor]),
        rich_visits = n_j[rich], rich_raw = exp(nopool[rich]), rich_partial = exp(alpha_pm[rich])), 2)

## ---- ppc ----
T_obs <- sd(ybar)                                           # observed among-site spread
set.seed(88)                                                # hierarchical replicates
idx <- sample(nrow(A_draws), 4000)
T_hier <- sapply(idx, function(i) {
  a <- A_draws[i, ]
  sd(sapply(seq_len(J), function(j) mean(rpois(n_j[j], exp(a[j])))))
})
set.seed(89)                                                # complete-pooling replicates
lam_draws <- rgamma(4000, shape = sum(S) + 0.001, rate = sum(n_j) + 0.001)
T_pool <- sapply(lam_draws, function(lam)
  sd(sapply(seq_len(J), function(j) mean(rpois(n_j[j], lam)))))
round(c(observed = T_obs, hier_mean = mean(T_hier), hier_p = mean(T_hier >= T_obs),
        pool_mean = mean(T_pool), pool_p = mean(T_pool >= T_obs)), 3)

## ---- fig-ppc ----
ppc <- rbind(data.frame(T = T_hier, model = "hierarchical (partial pooling)"),
             data.frame(T = T_pool, model = "single Poisson (complete pooling)"))
ppc$model <- factor(ppc$model, levels = c("hierarchical (partial pooling)",
                                          "single Poisson (complete pooling)"))
ggplot(ppc, aes(T, fill = model)) +
  geom_histogram(aes(y = after_stat(density)), binwidth = 0.12, colour = NA, alpha = 0.55,
                 position = "identity") +
  geom_vline(xintercept = T_obs, colour = ink, linewidth = 0.7) +
  annotate("text", x = T_obs, y = 0, label = "  observed", hjust = 0, vjust = -0.5, colour = ink, size = 3.2) +
  scale_fill_manual(values = c("hierarchical (partial pooling)" = sage,
                               "single Poisson (complete pooling)" = warm), name = NULL) +
  labs(x = "among-site SD of mean counts (replicated)", y = "density",
       title = "Replicated among-site spread under the two models")
