# Multiple imputation by chained equations
# https://tidyecology.com/posts/multiple-imputation-chained-equations/
#
# 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); library(dplyr); library(tidyr); library(MASS)
ink <- "#2b2b2b"; grid_col <- "#d9d5cc"; paper <- "#f5f4ee"
theme_te <- function(base = 12) {
  theme_minimal(base_size = base) +
    theme(panel.grid.minor = element_blank(),
          panel.grid.major = element_line(colour = grid_col, linewidth = 0.3),
          plot.background = element_rect(fill = paper, colour = NA),
          panel.background = element_rect(fill = paper, colour = NA),
          strip.text = element_text(face = "bold", colour = ink),
          plot.title = element_text(face = "bold", colour = ink),
          axis.title = element_text(colour = ink),
          legend.position = "top")
}

## ---- step-fn ----
## draw sigma^2 from its scaled inverse chi-square posterior, then beta given sigma^2,
## then fill the gaps with the predicted mean plus a residual draw
step <- function(target, mask, preds) {
  obs <- !mask
  Xo <- cbind(1, preds[obs, , drop = FALSE]); Vo <- target[obs]
  XtXinv <- chol2inv(chol(crossprod(Xo)))
  bhat <- XtXinv %*% crossprod(Xo, Vo)
  dfree <- sum(obs) - ncol(Xo)
  s2 <- sum((Vo - Xo %*% bhat)^2) / dfree
  s2star <- s2 * dfree / rchisq(1, dfree)                    # posterior draw of variance
  bstar <- bhat + t(chol(s2star * XtXinv)) %*% rnorm(ncol(Xo))  # posterior draw of coefficients
  out <- target
  Xm <- cbind(1, preds[mask, , drop = FALSE])
  out[mask] <- as.numeric(Xm %*% bstar) + rnorm(sum(mask), 0, sqrt(s2star))
  out
}

## ---- chain-fn ----
one_impute <- function(x, y, z, mx, my, cycles = 5) {
  xc <- x; xc[mx] <- sample(x[!mx], sum(mx), TRUE)   # random start
  yc <- y; yc[my] <- sample(y[!my], sum(my), TRUE)
  for (c in seq_len(cycles)) {
    xc <- step(x, mx, cbind(yc, z))                  # x given current y and z
    yc <- step(y, my, cbind(xc, z))                  # y given current x and z
  }
  data.frame(x = xc, y = yc)
}

## ---- dgp ----
set.seed(5108)
n <- 400
z <- rnorm(n)
x_true <- 0.7 * z + rnorm(n, 0, sqrt(1 - 0.49))         # x correlated with z
y_true <- 1 + 0.8 * x_true + rnorm(n, 0, 1.2)           # slope of interest is 0.8
## missing at random: high z makes both x and y more likely to be missing (about 30% each)
ax <- uniroot(function(a) mean(plogis(a + z)) - 0.30, c(-6, 6))$root
mx <- runif(n) < plogis(ax + z)
my <- runif(n) < plogis(ax + z)
x <- x_true; x[mx] <- NA
y <- y_true; y[my] <- NA

full <- lm(y_true ~ x_true)
full_b <- unname(coef(full)[2]); full_se <- summary(full)$coef[2, 2]
cc <- !mx & !my
ccf <- lm(y[cc] ~ x[cc])
cc_b <- unname(coef(ccf)[2]); cc_se <- summary(ccf)$coef[2, 2]

## ---- many ----
m <- 50
ests <- ses <- numeric(m)
for (k in 1:m) {
  d <- one_impute(x, y, z, mx, my, cycles = 5)
  f <- lm(y ~ x, data = d)
  ests[k] <- coef(f)[2]; ses[k] <- summary(f)$coef[2, 2]
}

## ---- rubin ----
pool <- function(ests, ses, m, nu_com) {
  Qbar <- mean(ests)                       # pooled estimate
  Ubar <- mean(ses^2)                      # within-imputation variance
  B <- var(ests)                           # between-imputation variance
  Tt <- Ubar + (1 + 1 / m) * B             # total variance
  lambda <- (1 + 1 / m) * B / Tt           # share of variance due to missing data
  nu_old <- (m - 1) / lambda^2
  nu_obs <- (nu_com + 1) / (nu_com + 3) * nu_com * (1 - lambda)
  df <- nu_old * nu_obs / (nu_old + nu_obs) # Barnard-Rubin degrees of freedom
  c(Q = Qbar, se = sqrt(Tt), B = B, Ubar = Ubar, lambda = lambda, df = df)
}
pl <- pool(ests, ses, m, nu_com = n - 2)
round(pl, 4)

## ---- fig-caterpillar ----
ord <- order(ests)
cap <- data.frame(idx = 1:m, est = ests[ord], lo = ests[ord] - 1.96 * ses[ord],
                  hi = ests[ord] + 1.96 * ses[ord])
tcrit <- qt(0.975, pl["df"])
lo_p <- pl["Q"] - tcrit * pl["se"]; hi_p <- pl["Q"] + tcrit * pl["se"]
ggplot(cap, aes(y = idx)) +
  geom_segment(aes(x = lo, xend = hi, yend = idx), colour = "#b9b4a8", linewidth = 0.4) +
  geom_point(aes(x = est), colour = "#4a7a8c", size = 1.1) +
  geom_vline(xintercept = 0.8, colour = ink, linetype = "dotted", linewidth = 0.6) +
  annotate("segment", x = lo_p, xend = hi_p, y = -3, yend = -3, colour = "#a24b4b", linewidth = 1.4) +
  annotate("point", x = pl["Q"], y = -3, colour = "#a24b4b", size = 3.2) +
  annotate("text", x = pl["Q"], y = -9, label = "Pooled (Rubin's rules)",
           colour = "#a24b4b", size = 3.3, fontface = "bold") +
  scale_y_continuous(breaks = c(1, 10, 20, 30, 40, 50)) +
  labs(title = "Fifty imputations and their pooled estimate",
       subtitle = "Pooling adds the spread between imputations to the interval",
       x = "Slope of y on x", y = "Imputation") + theme_te()

## ---- monte-carlo ----
reps <- 400; mM <- 20; b1 <- 0.8
res <- matrix(NA, reps, 7,
  dimnames = list(NULL, c("cc_b", "cc_cov", "cc_w", "si_cov", "si_w", "mi_cov", "mi_w")))
si_b <- mi_b <- numeric(reps)
set.seed(909)
for (r in 1:reps) {
  zz <- rnorm(n); xt <- 0.7 * zz + rnorm(n, 0, sqrt(1 - 0.49))
  yt <- 1 + 0.8 * xt + rnorm(n, 0, 1.2)
  a <- uniroot(function(a) mean(plogis(a + zz)) - 0.30, c(-6, 6))$root
  mxx <- runif(n) < plogis(a + zz); myy <- runif(n) < plogis(a + zz)
  xx <- xt; xx[mxx] <- NA; yy <- yt; yy[myy] <- NA
  cr <- !mxx & !myy; cf <- lm(yy[cr] ~ xx[cr]); cb <- coef(cf)[2]; cs <- summary(cf)$coef[2, 2]
  res[r, "cc_b"] <- cb; res[r, "cc_w"] <- 2 * 1.96 * cs
  res[r, "cc_cov"] <- (cb - 1.96 * cs <= b1) & (b1 <= cb + 1.96 * cs)
  es <- ss <- numeric(mM)
  for (k in 1:mM) { d <- one_impute(xx, yy, zz, mxx, myy, cycles = 4)
    f <- lm(y ~ x, data = d); es[k] <- coef(f)[2]; ss[k] <- summary(f)$coef[2, 2] }
  si_b[r] <- es[1]
  res[r, "si_cov"] <- (es[1] - 1.96 * ss[1] <= b1) & (b1 <= es[1] + 1.96 * ss[1])
  res[r, "si_w"] <- 2 * 1.96 * ss[1]
  p <- pool(es, ss, mM, n - 2); tc <- qt(0.975, p["df"])
  mi_b[r] <- p["Q"]
  res[r, "mi_cov"] <- (p["Q"] - tc * p["se"] <= b1) & (b1 <= p["Q"] + tc * p["se"])
  res[r, "mi_w"] <- 2 * tc * p["se"]
}
tab <- data.frame(
  method = c("Complete-case", "Single imputation", "Multiple imputation"),
  bias = c(mean(res[, "cc_b"]) - b1, mean(si_b) - b1, mean(mi_b) - b1),
  coverage = c(mean(res[, "cc_cov"]), mean(res[, "si_cov"]), mean(res[, "mi_cov"])),
  width = c(mean(res[, "cc_w"]), mean(res[, "si_w"]), mean(res[, "mi_w"])))
round(tab[, -1], 3)

## ---- fig-coverage ----
sm <- data.frame(method = factor(c("Complete-case", "Single imputation", "Multiple imputation"),
                                 levels = c("Complete-case", "Single imputation", "Multiple imputation")),
                 coverage = c(mean(res[, "cc_cov"]), mean(res[, "si_cov"]), mean(res[, "mi_cov"])),
                 width = c(mean(res[, "cc_w"]), mean(res[, "si_w"]), mean(res[, "mi_w"])))
ggplot(sm, aes(width, coverage, colour = method)) +
  geom_hline(yintercept = 0.95, colour = ink, linetype = "dashed", linewidth = 0.5) +
  geom_point(size = 4) +
  geom_text(aes(label = method), size = 3.4, show.legend = FALSE,
            hjust = ifelse(sm$method == "Multiple imputation", 1.08, 0.5),
            vjust = ifelse(sm$method == "Multiple imputation", 0.5, -1.1)) +
  scale_colour_manual(values = c("Complete-case" = "#c08a3e",
                                 "Single imputation" = "#8a8578",
                                 "Multiple imputation" = "#a24b4b"), guide = "none") +
  scale_y_continuous(labels = function(v) paste0(round(100 * v), "%")) +
  coord_cartesian(xlim = c(0.2, 0.38), ylim = c(0.74, 0.99)) +
  labs(title = "Nominal coverage at a narrower interval",
       subtitle = "Single imputation undercovers; complete-case is honest but wide",
       x = "Mean 95% interval width", y = "Interval coverage") + theme_te()
