# Heterogeneity in meta-analysis
# https://tidyecology.com/posts/heterogeneity-in-meta-analysis/
#
# 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.width = 7.5, fig.height = 4.5, dpi = 100)
pal <- list(ink = "#16241d", body = "#2c3a31", forest = "#275139",
            label = "#46604a", sage = "#93a87f", paper = "#f5f4ee",
            line = "#dad9ca", faint = "#5d6b61", gold = "#cda23f",
            mown = "#2f8f63", warn = "#b5534e", low = "#c9b458", high = "#1d5b4e")
theme_te <- function(base_size = 12) {
  theme_minimal(base_size = base_size) +
    theme(panel.grid.minor = element_blank(),
          panel.grid.major = element_line(colour = pal$line, linewidth = 0.3),
          plot.background = element_rect(fill = pal$paper, colour = NA),
          panel.background = element_rect(fill = pal$paper, colour = NA),
          axis.text = element_text(colour = pal$body),
          axis.title = element_text(colour = pal$ink),
          plot.title = element_text(colour = pal$ink, face = "bold"),
          plot.subtitle = element_text(colour = pal$faint),
          legend.position = "bottom",
          legend.text = element_text(colour = pal$body),
          legend.title = element_text(colour = pal$ink))
}

## ---- simulate ----
set.seed(201)
mu_true <- 0.35; tau_true <- 0.22; k <- 18
n <- sample(18:130, k, replace = TRUE)

sim_study <- function(theta, ni) {
  x1 <- rnorm(ni, 0, 1); x2 <- rnorm(ni, theta, 1)
  sp <- sqrt(((ni - 1) * sd(x1)^2 + (ni - 1) * sd(x2)^2) / (2 * ni - 2))
  d  <- (mean(x2) - mean(x1)) / sp
  J  <- 1 - 3 / (4 * (2 * ni - 2) - 1)
  g  <- J * d
  vd <- (2 * ni) / (ni * ni) + d^2 / (2 * (2 * ni))
  c(g = g, v = J^2 * vd)
}
theta_i <- rnorm(k, mu_true, tau_true)
gv <- t(mapply(sim_study, theta_i, n))
g  <- gv[, "g"]; v <- gv[, "v"]
wf <- 1 / v; mu_fe <- sum(wf * g) / sum(wf)

## ---- q-i2 ----
Q  <- sum(wf * (g - mu_fe)^2)
df <- k - 1
pQ <- pchisq(Q, df, lower.tail = FALSE)
I2 <- max(0, (Q - df) / Q)
c(Q = Q, df = df, p = pQ, I2 = I2)

## ---- i2-ci ----
H   <- sqrt(Q / df)
if (Q > k) {
  se_lnH <- 0.5 * (log(Q) - log(df)) / (sqrt(2 * Q) - sqrt(2 * df - 1))
} else {
  se_lnH <- sqrt(1 / (2 * (df - 1)) * (1 - 1 / (3 * (df - 1)^2)))
}
lnH  <- log(H)
Hlo  <- exp(lnH - 1.96 * se_lnH); Hhi <- exp(lnH + 1.96 * se_lnH)
I2lo <- max(0, (Hlo^2 - 1) / Hlo^2); I2hi <- max(0, (Hhi^2 - 1) / Hhi^2)
c(I2 = I2, lower = I2lo, upper = I2hi)

## ---- tau2-ci ----
Cc   <- sum(wf) - sum(wf^2) / sum(wf)
tau2 <- max(0, (Q - df) / Cc)
Qgen <- function(t2) { wi <- 1 / (v + t2); mh <- sum(wi * g) / sum(wi); sum(wi * (g - mh)^2) }
lo_t <- tryCatch(uniroot(function(t2) Qgen(t2) - qchisq(.975, df), c(0, 10))$root,
                 error = function(e) 0)
hi_t <- uniroot(function(t2) Qgen(t2) - qchisq(.025, df), c(0, 10))$root
c(tau2 = tau2, lower = lo_t, upper = hi_t)

## ---- prediction-interval ----
ws  <- 1 / (v + tau2)
mre <- sum(ws * g) / sum(ws); se_re <- sqrt(1 / sum(ws))
ci  <- mre + c(-1, 1) * 1.96 * se_re                       # interval for the mean
pri <- mre + c(-1, 1) * qt(.975, k - 2) * sqrt(tau2 + se_re^2)  # prediction interval
rbind(mean_CI = ci, prediction = pri)

## ---- fig-het-forest ----
se <- sqrt(v); ord <- order(g)
fdat <- data.frame(
  lab = factor(paste0("S", seq_len(k))[ord], levels = paste0("S", seq_len(k))[ord]),
  est = g[ord], lo = g[ord] - 1.96 * se[ord], hi = g[ord] + 1.96 * se[ord])
ggplot(fdat, aes(est, lab)) +
  geom_vline(xintercept = 0, linetype = "dashed", colour = pal$faint) +
  annotate("segment", x = pri[1], xend = pri[2], y = 1, yend = 1,
           colour = pal$sage, linewidth = 3) +
  geom_pointrange(aes(xmin = lo, xmax = hi), colour = pal$forest,
                  linewidth = 0.4, fatten = 1.6) +
  annotate("point", x = mre, y = 1, shape = 18, size = 4, colour = pal$warn) +
  annotate("segment", x = ci[1], xend = ci[2], y = 1, yend = 1,
           colour = pal$warn, linewidth = 1) +
  annotate("text", x = pri[2], y = 1.45, label = " prediction interval",
           hjust = 0, size = 3, colour = pal$sage) +
  scale_y_discrete(limits = c("", levels(fdat$lab)),
                   expand = expansion(add = c(1.1, 0.6))) +
  labs(x = "Hedges' g", y = NULL, title = "Mean effect versus prediction interval") +
  theme_te()

## ---- fig-het-i2 ----
t2f  <- tau_true^2
nseq <- seq(10, 300, by = 2)
vtyp <- 2 / nseq + mu_true^2 / (4 * nseq)          # typical g variance at per-arm n
I2seq <- t2f / (t2f + vtyp)
mark  <- data.frame(nn = c(20, 200),
                    ii = t2f / (t2f + (2 / c(20, 200) + mu_true^2 / (4 * c(20, 200)))))
ggplot(data.frame(nn = nseq, ii = I2seq), aes(nn, ii)) +
  geom_line(colour = pal$forest, linewidth = 0.9) +
  geom_point(data = mark, aes(nn, ii), colour = pal$warn, size = 2.6) +
  geom_text(data = mark, aes(nn, ii, label = sprintf("%.0f%%", 100 * ii)),
            colour = pal$warn, hjust = 1.3, vjust = -0.3, size = 3.4) +
  annotate("text", x = 300, y = 0.12, hjust = 1,
           label = "same tau-squared throughout", colour = pal$faint, size = 3.4) +
  labs(x = "per-arm sample size", y = "I-squared",
       title = "I-squared depends on study precision") +
  scale_y_continuous(labels = function(x) sprintf("%.0f%%", 100 * x)) +
  theme_te()
