# Random-effects meta-analysis in R
# https://tidyecology.com/posts/random-effects-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-09-27

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

## ---- sci-tex-helper ----
sci_tex <- function(x, digits = 2) {
  s <- formatC(x, format = "e", digits = digits)
  paste0("$", sub("e.*", "", s), " \\times 10^{", as.integer(sub(".*e", "", s)), "}$")
}

## ---- simulate ----
set.seed(151)
mu_true <- 0.40; tau_true <- 0.25; k <- 20
n <- sample(15:120, k, replace = TRUE)          # per-study sample size (per arm)

sim_study <- function(theta, ni) {
  x1 <- rnorm(ni, 0, 1)                          # control arm
  x2 <- rnorm(ni, theta, 1)                      # treatment arm
  sp <- sqrt(((ni - 1) * sd(x1)^2 + (ni - 1) * sd(x2)^2) / (2 * ni - 2))
  d  <- (mean(x2) - mean(x1)) / sp               # Cohen's d
  J  <- 1 - 3 / (4 * (2 * ni - 2) - 1)           # small-sample correction
  g  <- J * d                                    # Hedges' g
  vd <- (2 * ni) / (ni * ni) + d^2 / (2 * (2 * ni))
  c(g = g, v = J^2 * vd)                         # g and its sampling variance
}

theta_i <- rnorm(k, mu_true, tau_true)           # each study's own true effect
gv <- t(mapply(sim_study, theta_i, n))
g  <- gv[, "g"]; v <- gv[, "v"]
se <- sqrt(v)
round(cbind(n, g = g, se = se)[1:6, ], 3)

## ---- fixed-effect ----
wf    <- 1 / v
mu_fe <- sum(wf * g) / sum(wf)
se_fe <- sqrt(1 / sum(wf))
ci_fe <- mu_fe + c(-1, 1) * 1.96 * se_fe
c(estimate = mu_fe, se = se_fe, lower = ci_fe[1], upper = ci_fe[2])

## ---- q-test ----
Q   <- sum(wf * (g - mu_fe)^2)
dfQ <- k - 1
pQ  <- pchisq(Q, dfQ, lower.tail = FALSE)
c(Q = Q, df = dfQ, p = pQ)

## ---- dersimonian-laird ----
Cc      <- sum(wf) - sum(wf^2) / sum(wf)
tau2_dl <- max(0, (Q - dfQ) / Cc)                # DerSimonian-Laird moment estimate
ws      <- 1 / (v + tau2_dl)                     # random-effects weights
mu_re   <- sum(ws * g) / sum(ws)
se_re   <- sqrt(1 / sum(ws))
ci_re   <- mu_re + c(-1, 1) * 1.96 * se_re
c(tau2 = tau2_dl, estimate = mu_re, se = se_re, lower = ci_re[1], upper = ci_re[2])

## ---- reml ----
reml_ll <- function(t2) {
  wi <- 1 / (v + t2)
  mh <- sum(wi * g) / sum(wi)
  -0.5 * sum(log(v + t2)) - 0.5 * log(sum(wi)) - 0.5 * sum(wi * (g - mh)^2)
}
opt       <- optimize(reml_ll, c(0, 5), maximum = TRUE)
tau2_reml <- opt$maximum
wr        <- 1 / (v + tau2_reml)
mu_reml   <- sum(wr * g) / sum(wr)
se_reml   <- sqrt(1 / sum(wr))
ci_reml   <- mu_reml + c(-1, 1) * 1.96 * se_reml
c(tau2 = tau2_reml, estimate = mu_reml, se = se_reml)

## ---- fig-re-forest ----
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])
sdat <- data.frame(
  lab = factor(c("RE (random)", "FE (fixed)"),
               levels = c("RE (random)", "FE (fixed)")),
  est = c(mu_re, mu_fe), lo = c(ci_re[1], ci_fe[1]), hi = c(ci_re[2], ci_fe[2]))

ggplot(fdat, aes(est, lab)) +
  geom_vline(xintercept = 0, linetype = "dashed", colour = pal$faint) +
  geom_pointrange(aes(xmin = lo, xmax = hi), colour = pal$forest,
                  linewidth = 0.4, fatten = 1.6) +
  geom_pointrange(data = sdat, aes(xmin = lo, xmax = hi), colour = pal$warn,
                  shape = 18, linewidth = 0.9, fatten = 3.2) +
  labs(x = "Hedges' g (standardised mean difference)", y = NULL,
       title = "Study effects and two pooled summaries") +
  theme_te()

## ---- coverage ----
cover_at <- function(tt, nsim = 1200) {
  fe <- 0; re <- 0
  for (s in seq_len(nsim)) {
    th <- rnorm(k, mu_true, tt)
    gg <- numeric(k); vv <- numeric(k)
    for (i in seq_len(k)) { r <- sim_study(th[i], n[i]); gg[i] <- r[1]; vv[i] <- r[2] }
    wF <- 1 / vv; mF <- sum(wF * gg) / sum(wF); sF <- sqrt(1 / sum(wF))
    if (abs(mF - mu_true) <= 1.96 * sF) fe <- fe + 1
    QQ <- sum(wF * (gg - mF)^2); CC <- sum(wF) - sum(wF^2) / sum(wF)
    t2 <- max(0, (QQ - (k - 1)) / CC); wS <- 1 / (vv + t2)
    mR <- sum(wS * gg) / sum(wS); sR <- sqrt(1 / sum(wS))
    if (abs(mR - mu_true) <= 1.96 * sR) re <- re + 1
  }
  c(fe = fe / nsim, re = re / nsim)
}
set.seed(2718)
grid   <- c(0, 0.1, 0.2, 0.3, 0.4)
covtab <- as.data.frame(t(sapply(grid, cover_at)))
covtab$tau <- grid
round(covtab[, c("tau", "fe", "re")], 3)

## ---- fig-re-coverage ----
cdat <- rbind(
  data.frame(tau = grid, cover = covtab$fe, model = "Fixed-effect"),
  data.frame(tau = grid, cover = covtab$re, model = "Random-effects"))
ggplot(cdat, aes(tau, cover, colour = model)) +
  geom_hline(yintercept = 0.95, linetype = "dashed", colour = pal$faint) +
  geom_line(linewidth = 0.8) + geom_point(size = 2.2) +
  scale_colour_manual(values = c("Fixed-effect" = pal$warn,
                                 "Random-effects" = pal$forest), name = NULL) +
  labs(x = "true between-study SD (tau)", y = "95% interval coverage",
       title = "Coverage of the pooled mean") +
  coord_cartesian(ylim = c(0.4, 1)) +
  theme_te()

## ---- few-studies ----
kh_at <- function(kk, tt, nsim = 2000) {
  tc <- qt(0.975, kk - 1)
  out <- matrix(NA, nsim, 8)
  for (s in seq_len(nsim)) {
    r  <- mapply(sim_study, rnorm(kk, mu_true, tt), n[seq_len(kk)])
    gg <- r[1, ]; vv <- r[2, ]
    wF <- 1 / vv; mF <- sum(wF * gg) / sum(wF)
    QQ <- sum(wF * (gg - mF)^2); CC <- sum(wF) - sum(wF^2) / sum(wF)
    t2 <- max(0, (QQ - (kk - 1)) / CC); wS <- 1 / (vv + t2)
    mR <- sum(wS * gg) / sum(wS); sR <- sqrt(1 / sum(wS))
    q  <- sum(wS * (gg - mR)^2) / (kk - 1)            # Knapp-Hartung scale
    rl <- function(x) { wi <- 1 / (vv + x); mh <- sum(wi * gg) / sum(wi)
      -0.5 * sum(log(vv + x)) - 0.5 * log(sum(wi)) - 0.5 * sum(wi * (gg - mh)^2) }
    wR <- 1 / (vv + optimize(rl, c(0, 5), maximum = TRUE)$maximum)
    mE <- sum(wR * gg) / sum(wR); qE <- sum(wR * (gg - mE)^2) / (kk - 1)
    out[s, ] <- c(abs(mR - mu_true) <= c(1.96, tc * sqrt(q), tc * sqrt(max(1, q))) * sR,
                  tc * sqrt(q) < 1.96, t2 == 0, q,
                  abs(mE - mu_true) <= c(1.96, tc * sqrt(qE)) * sqrt(1 / sum(wR)))
  }
  colnames(out) <- c("z", "kh", "adhoc", "narrow", "t2zero", "q", "z_reml", "kh_reml")
  stopifnot(out[, "narrow"] == (out[, "q"] < (1.96 / tc)^2),  # narrower iff q below the cut
            out[out[, "t2zero"] == 1, "q"] <= 1 + 1e-12)       # tau2 = 0 forces q <= 1
  out
}
set.seed(2719)
kh_grid <- expand.grid(tau = c(0, 0.1, 0.2, 0.4), kk = c(4, 6, 10))
kh_raw  <- lapply(seq_len(nrow(kh_grid)), function(i) kh_at(kh_grid$kk[i], kh_grid$tau[i]))
kh_tab  <- cbind(kh_grid, t(sapply(kh_raw, colMeans)))
kh_mcse <- sqrt(0.95 * 0.05 / 2000)                    # Monte Carlo SE near 0.95
kh_f3   <- function(x) sprintf("%.3f", round(x, 3))    # prose matches the table
kh_cut  <- (1.96 / qt(0.975, c(4, 6, 10) - 1))^2
kh_nz   <- unlist(lapply(kh_raw[kh_grid$tau <= 0.1], function(m) m[m[, "narrow"] == 1, "t2zero"]))
kh_nzc  <- c(narrow = length(kh_nz), tau2_positive = sum(kh_nz == 0))
kh_n4   <- colMeans(kh_raw[[1]][kh_raw[[1]][, "narrow"] == 1, c("z", "kh")])
kh_reml <- max(abs(kh_tab$z_reml - kh_tab$z), abs(kh_tab$kh_reml - kh_tab$kh))
kh_lo   <- kh_tab$kh[kh_tab$tau > 0 & kh_tab$kk <= 6]; stopifnot(all(kh_lo < 0.95))
round(kh_tab[, c("tau", "kk", "z", "kh", "adhoc", "narrow", "t2zero")], 3)

## ---- fig-re-few-studies ----
kh_lab <- c("z", "Knapp-Hartung", "ad hoc (q at least 1)")
kdat <- data.frame(kh_tab[rep(1:12, 3), c("tau", "kk")], interval = rep(kh_lab, each = 12),
                   cover = c(kh_tab$z, kh_tab$kh, kh_tab$adhoc))
ggplot(kdat, aes(kk, cover, colour = interval)) +
  geom_hline(yintercept = 0.95, linetype = "dashed", colour = pal$faint) +
  geom_line(linewidth = 0.8) + geom_point(size = 2) +
  facet_wrap(~ tau, nrow = 1, labeller = label_both) +
  scale_x_continuous(breaks = c(4, 6, 10)) +
  scale_colour_manual(values = setNames(c(pal$warn, pal$forest, pal$gold), kh_lab),
                      breaks = kh_lab, name = NULL) +
  labs(x = "studies in the synthesis", y = "95% interval coverage",
       title = "Coverage of the pooled mean with few studies") +
  theme_te() + theme(panel.spacing = grid::unit(1.2, "lines"))
