# Propensity score matching
# https://tidyecology.com/posts/propensity-score-matching/
#
# 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 ----
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", message = FALSE, warning = FALSE,
                      dev = "png", dpi = 110, fig.width = 8, fig.height = 4.4)
library(ggplot2)
te <- list(ink="#16241d", body="#2c3a31", forest="#275139", label="#46604a",
           paper="#f5f4ee", line="#dad9ca", faint="#5d6b61", grazed="#cda23f",
           mown="#2f8f63", abandoned="#b5534e", high="#1d5b4e", low="#c9b458")
theme_te <- function(base_size = 12) {
  theme_minimal(base_size = base_size) +
    theme(plot.background=element_rect(fill=te$paper,colour=NA),
          panel.background=element_rect(fill=te$paper,colour=NA),
          panel.grid.major=element_line(colour=te$line,linewidth=0.3),
          panel.grid.minor=element_blank(),
          axis.text=element_text(colour=te$faint), axis.title=element_text(colour=te$body),
          plot.title=element_text(colour=te$ink,face="bold"), plot.subtitle=element_text(colour=te$body),
          legend.text=element_text(colour=te$body), legend.title=element_text(colour=te$body),
          plot.margin=margin(10,12,10,10))
}
expit <- function(z) 1 / (1 + exp(-z))

## ---- dgp ----
expit <- function(z) 1 / (1 + exp(-z))
pa <- c(a0=-0.3, a1=0.7, a2=0.5, a3=0.5)                 # propensity
pb <- c(b0=-0.4, bD=log(1.8), b1=0.6, b2=0.5, b3=0.5)    # outcome

gen <- function(n) {
  x1 <- rnorm(n); x2 <- rnorm(n); x3 <- rbinom(n, 1, 0.5)
  ps <- expit(pa["a0"] + pa["a1"]*x1 + pa["a2"]*x2 + pa["a3"]*x3)
  d  <- rbinom(n, 1, ps)
  py <- expit(pb["b0"] + pb["bD"]*d + pb["b1"]*x1 + pb["b2"]*x2 + pb["b3"]*x3)
  y  <- rbinom(n, 1, py)
  data.frame(y, d, x1, x2, x3)
}
true_att <- function(dat) {                              # E[Y(1) - Y(0) | D = 1]
  t <- dat$d == 1
  l1 <- pb["b0"]+pb["bD"]*1+pb["b1"]*dat$x1+pb["b2"]*dat$x2+pb["b3"]*dat$x3
  l0 <- pb["b0"]+pb["bD"]*0+pb["b1"]*dat$x1+pb["b2"]*dat$x2+pb["b3"]*dat$x3
  as.numeric(mean((expit(l1)-expit(l0))[t]))
}

## ---- match-fns ----
match_repl <- function(lps, d, y, caliper=NULL) {        # nearest neighbour, with replacement
  it <- which(d==1); ic <- which(d==0)
  Dm <- abs(outer(lps[it], lps[ic], "-"))
  nn <- max.col(-Dm, ties.method="first")                # index of nearest control per treated
  md <- Dm[cbind(seq_along(it), nn)]
  keep <- if (is.null(caliper)) rep(TRUE, length(it)) else md <= caliper
  list(att=mean(y[it][keep]-y[ic][nn[keep]]), n_keep=sum(keep), n_t=length(it),
       t_idx=it[keep], c_idx=ic[nn[keep]])
}
match_norepl <- function(lps, d, y, caliper=NULL) {      # greedy, without replacement, high-PS first
  it <- which(d==1); ic <- which(d==0)
  ord <- it[order(lps[it], decreasing=TRUE)]
  avail <- rep(TRUE, length(ic)); tu <- cu <- integer(0)
  for (t in ord) {
    dd <- abs(lps[ic]-lps[t]); dd[!avail] <- Inf
    j <- which.min(dd)
    if (is.finite(dd[j]) && (is.null(caliper) || dd[j] <= caliper)) {
      avail[j] <- FALSE; tu <- c(tu, t); cu <- c(cu, ic[j])
    }
  }
  list(att=mean(y[tu]-y[cu]), n_keep=length(tu), n_t=length(it), t_idx=tu, c_idx=cu)
}
ipw_att <- function(e, d, y) {                           # ATT by weighting controls by e/(1-e)
  w <- e/(1-e)
  mean(y[d==1]) - sum(w[d==0]*y[d==0])/sum(w[d==0])
}
smd_treated <- function(x, ti, ci) (mean(x[ti]) - mean(x[ci])) / sd(x[ti])

## ---- data ----
set.seed(168)
n <- 2000
dat <- gen(n)
ps  <- glm(d ~ x1 + x2 + x3, binomial, dat)
e   <- fitted(ps); lps <- qlogis(e)
cal <- 0.2 * sd(lps)                                     # standard caliper on the logit scale
TA  <- true_att(dat)
c(n_treated = sum(dat$d), n_control = sum(1-dat$d),
  overlap_low = max(min(e[dat$d==1]), min(e[dat$d==0])),
  overlap_high = min(max(e[dat$d==1]), max(e[dat$d==0])), caliper = cal)

## ---- estimates ----
naive <- mean(dat$y[dat$d==1]) - mean(dat$y[dat$d==0])
mr    <- match_repl(lps, dat$d, dat$y)                   # with replacement, no caliper
mrc   <- match_repl(lps, dat$d, dat$y, cal)              # with replacement, caliper
mn    <- match_norepl(lps, dat$d, dat$y, cal)            # without replacement, caliper
iw    <- ipw_att(e, dat$d, dat$y)
lin0  <- pb["b0"] + pb["b1"]*dat$x1 + pb["b2"]*dat$x2 + pb["b3"]*dat$x3     # true outcome logit, untreated
TA_mn <- mean((expit(lin0 + pb["bD"]) - expit(lin0))[mn$t_idx])          # true ATT of the subset mn keeps
exp_mn <- mean(expit(lin0[mn$t_idx] + pb["bD"]) - expit(lin0[mn$c_idx]))  # contrast the model expects from mn's pairs
smd_mn <- smd_treated(lps, mn$t_idx, mn$c_idx)                            # logit-score balance of mn

data.frame(
  estimator = c("naive (treated - all controls)","matching with replacement",
                "matching with replacement + caliper","matching without replacement + caliper",
                "IPW (ATT weights)"),
  att = round(c(naive, mr$att, mrc$att, mn$att, iw), 4),
  matched = c(sum(dat$d), mr$n_keep, mrc$n_keep, mn$n_keep, sum(dat$d)))

## ---- balance ----
vars <- c("x1","x2","x3")
ti0 <- which(dat$d==1); ci0 <- which(dat$d==0)
bal <- data.frame(
  variable = c(vars, "logit-PS"),
  before = c(sapply(vars, function(v) smd_treated(dat[[v]], ti0, ci0)), smd_treated(lps, ti0, ci0)),
  after  = c(sapply(vars, function(v) smd_treated(dat[[v]], mrc$t_idx, mrc$c_idx)),
             smd_treated(lps, mrc$t_idx, mrc$c_idx)))
round(bal[, -1], 3) -> bal[, -1]; bal

## ---- fig-love ----
lp <- rbind(data.frame(var=bal$variable, smd=abs(bal$before), when="before matching"),
            data.frame(var=bal$variable, smd=abs(bal$after),  when="after matching"))
lp$var  <- factor(lp$var, levels=rev(c("logit-PS","x1","x2","x3")))
lp$when <- factor(lp$when, levels=c("before matching","after matching"))
ggplot(lp, aes(smd, var)) +
  geom_line(aes(group=var), colour=te$line, linewidth=1) +
  geom_vline(xintercept=0.1, linetype="dashed", colour=te$label) +
  geom_point(aes(colour=when), size=3.2) +
  annotate("text", x=0.1, y=4.42, label="0.1 threshold", hjust=-0.06, size=3, colour=te$label) +
  scale_colour_manual(values=c("before matching"=te$abandoned, "after matching"=te$forest), name=NULL) +
  scale_x_continuous(limits=c(0, 0.9)) +
  labs(x="absolute standardised mean difference", y=NULL,
       title="Matching brings every covariate into balance",
       subtitle="Standardised mean differences fall below 0.1 after nearest-neighbour matching") +
  theme_te() + theme(legend.position="top")

## ---- fig-att ----
lab <- c("naive (treated - all controls)"="naive (treated vs all controls)",
         "matching with replacement + caliper"="matching (with replacement, caliper)",
         "matching without replacement + caliper"="matching (without replacement, caliper)",
         "IPW (ATT weights)"="IPW (ATT weights)")
es <- data.frame(estimator=names(lab),
                 att=c(naive, mrc$att, mn$att, iw))
es$label <- factor(lab[es$estimator],
  levels=rev(c("naive (treated vs all controls)","matching (with replacement, caliper)",
               "matching (without replacement, caliper)","IPW (ATT weights)")))
es$kind <- ifelse(es$estimator=="naive (treated - all controls)", "naive", "adjusted")
ggplot(es, aes(att, label, colour=kind)) +
  geom_vline(xintercept=TA, linetype="dashed", colour=te$ink) +
  geom_point(size=3.4) +
  annotate("text", x=TA, y=0.6, label=paste0("true ATT ", sprintf('%.3f', TA)),
           hjust=-0.05, size=3, colour=te$ink) +
  scale_colour_manual(values=c(naive=te$abandoned, adjusted=te$mown), guide="none") +
  scale_x_continuous(limits=c(0.10, 0.26)) +
  labs(x="estimated ATT (risk difference among the treated)", y=NULL,
       title="Estimated ATT by method, against the true value",
       subtitle="Naive contrast, two matching estimates and ATT weighting; the true ATT is marked") +
  theme_te() +
  theme(plot.title.position = "plot")

## ---- mc ----
set.seed(16800)
nsim <- 500
En <- Em <- Ei <- tr <- se_pair <- numeric(nsim); frac <- numeric(nsim)
for (s in 1:nsim) {
  ds <- gen(n); tr[s] <- true_att(ds)
  p <- glm(d ~ x1 + x2 + x3, binomial, ds); ee <- fitted(p); ll <- qlogis(ee)
  En[s] <- mean(ds$y[ds$d==1]) - mean(ds$y[ds$d==0])
  mm <- match_repl(ll, ds$d, ds$y, 0.2*sd(ll)); Em[s] <- mm$att; frac[s] <- mm$n_keep/sum(ds$d)
  se_pair[s] <- sd(ds$y[mm$t_idx] - ds$y[mm$c_idx]) / sqrt(mm$n_keep)   # pairs treated as independent
  Ei[s] <- ipw_att(ee, ds$d, ds$y)
}
mt <- mean(tr)
cover_pair <- mean(abs(Em - tr) <= qnorm(0.975) * se_pair)
data.frame(estimator = c("naive","matching (repl + caliper)","IPW (ATT)"),
           mean = round(c(mean(En), mean(Em), mean(Ei)), 4),
           bias = round(c(mean(En), mean(Em), mean(Ei)) - mt, 4),
           sd   = round(c(sd(En), sd(Em), sd(Ei)), 4))
