day9_Scores.Rmd

---
title: |
 | Statistical Adjustment in Observational Studies,
 | Assessment of Adjustment,
 | Matched Stratification for One and Multiple Variables,
 | Tools for improving the design
date: '`r format(Sys.Date(), "%B %d, %Y")`'
author: |
  | ICPSR 2023 Session 1
  | Jake Bowers \& Tom Leavitt
bibliography:
 - 'BIB/MasterBibliography.bib'
fontsize: 10pt
geometry: margin=1in
graphics: yes
biblio-style: authoryear-comp
biblatexoptions:
  - natbib=true
urlcolor: orange
linkcolor: orange
output:
  beamer_presentation:
    slide_level: 2
    keep_tex: true
    latex_engine: xelatex
    citation_package: biblatex
    template: icpsr.beamer
    incremental: true
    includes:
        in_header:
           - defs-all.sty
    md_extensions: +raw_attribute-tex_math_single_backslash+autolink_bare_uris+ascii_identifiers+tex_math_dollars
    pandoc_args: [ "--csl", "chicago-author-date.csl" ]
---


<!-- To show notes  -->
<!-- https://stackoverflow.com/questions/44906264/add-speaker-notes-to-beamer-presentations-using-rmarkdown -->

```{r setup1_env, echo=FALSE, include=FALSE}
library(here)
source(here::here("rmd_setup.R"))
```

```{r setup2_loadlibs, echo=FALSE, include=FALSE}
## Load all of the libraries that we will use when we compile this file
## We are using the renv system. So these will all be loaded from a local library directory
library(dplyr)
library(ggplot2)
library(coin)
library(RItools)
library(optmatch)
```


## Today

  1. Agenda:  Continue to think about an adjustment strategy to enhance
     counterfactual causal interpretations in non-randomized studies:
      - Workflow:
         a. choose basis or covariates that need adjusting $\rightarrow$
         b. create a stratification of the data / a stratified research design (ex. `fullmatch`) $\rightarrow$
         c. choose one or more approaches to evaluate the stratification (ex. `balanceTest`) $\rightarrow$
         d. (probably) improve the stratified design / iterate
      - How to do this with one variable?
      - How to do this with  more than one variable?
      - How to create strata to clarify comparison along continuous or multi-valued
        "treatment" variables ("non-bipartite" matching) Feel free to read
        ahead.
 2. Questions arising from the reading or assignments or life?


```{r echo=FALSE, cache=TRUE}
load(url("http://jakebowers.org/Data/meddat.rda"))
meddat <- mutate(meddat,
  HomRate03 = (HomCount2003 / Pop2003) * 1000,
  HomRate08 = (HomCount2008 / Pop2008) * 1000
)
row.names(meddat) <- meddat$nh
```

## The optmatch workflow: The distance matrix

To minimize overall differences `optmatch` requires a matrix
of those differences (in general terms, a matrix of distances between the
treated and control units)

```{r optm1, echo=TRUE}
tmp <- meddat$nhAboveHS
names(tmp) <- rownames(meddat)
absdist <- match_on(tmp, z = meddat$nhTrt, data = meddat)
absdist[1:3, 1:3]
meddat %>%
  group_by(nhTrt) %>%
  summarize(nhAboveHS[1])
abs(meddat$nhAboveHS[meddat$nhTrt == 1][1] - meddat$nhAboveHS[meddat$nhTrt == 0][1])
```

## Created a Stratified Research Design

`fullmatch` and `pairmatch` use a distance matrix to produce strata.

```{r fm1, echo=TRUE}
fm1 <- fullmatch(absdist, data = meddat)
summary(fm1, min.controls = 0, max.controls = Inf)
table(meddat$nhTrt, fm1)
pm1 <- pairmatch(absdist, data = meddat)
summary(pm1, min.controls = 0, max.controls = Inf)
table(meddat$nhTrt, pm1, exclude = c())
```

## Created a Stratified Research Design

Maybe we don't want to compare any neighborhoods that differ by more than 6 pct
points in %HS, also maybe want no more than 2 treated per control:

```{r, echo=TRUE}
quantile(as.vector(absdist),seq(0,1,.1))
fm2 <- fullmatch(absdist + caliper(absdist,.06), data = meddat, min.controls = .5)
stratumStructure(fm2)

summary(unlist(matched.distances(fm1,absdist)))

summary(unlist(matched.distances(fm2,absdist)))
```


## Evaluate the design: Within set differences

```{r echo=FALSE}
meddat$fm2 <- fm2
meddat$fm1 <- fm1
meddat$pm1 <- pm1
```

Differences within sets versus raw differences.

```{r echo=FALSE, out.width=".9\\textwidth"}
library(gridExtra)
bpfm1 <- ggplot(meddat, aes(x = fm1, y = nhAboveHS)) +
  geom_boxplot() +
  stat_summary(fun = mean, geom = "point", shape = 20, size = 3, color = "red", fill = "red")
meddat$nostrata <- rep(1, 45)
bporig <- ggplot(meddat, aes(x = nostrata, y = nhAboveHS)) +
  geom_boxplot() +
  stat_summary(
    fun = mean, geom = "point",
    shape = 20, size = 3, color = "red", fill = "red"
  )

grid.arrange(bpfm1, bporig, ncol = 2, layout_matrix = matrix(c(1, 1, 1, 1, 2), nrow = 1))
```

## Evaluate the design: Within-set differences
Differences within sets versus raw differences.

```{r echo=FALSE, out.width=".9\\textwidth"}
bpfm2 <- ggplot(meddat, aes(x = fm2, y = nhAboveHS)) +
  geom_boxplot() +
  stat_summary(fun = mean, geom = "point", shape = 20, size = 3, color = "red", fill = "red")

grid.arrange(bpfm2, bporig, ncol = 2, layout_matrix = matrix(c(1, 1, 1, 1, 2), nrow = 1))
```



## Evaluate the design: Within-set differences
Differences within sets versus raw differences.

```{r echo=FALSE, out.width=".9\\textwidth"}
bppm1 <- ggplot(meddat, aes(x = pm1, y = nhAboveHS)) +
  geom_boxplot() +
  stat_summary(fun = mean, geom = "point", shape = 20, size = 3, color = "red", fill = "red")

grid.arrange(bppm1, bporig, ncol = 2, layout_matrix = matrix(c(1, 1, 1, 1, 2), nrow = 1))
```

## Evaluate the design: Inspect within-set differences

Use what we know about Medellin neighborhoods, about Metrocable, to assess the research design:

```{r sdiffs, echo=FALSE}
rawmndiffs <- with(meddat, mean(nhAboveHS[nhTrt == 1]) - mean(nhAboveHS[nhTrt == 0]))
setdiffsfm1 <- meddat %>%
  group_by(fm1) %>%
  summarize(
    mneddiffs =
      mean(nhAboveHS[nhTrt == 1]) -
        mean(nhAboveHS[nhTrt == 0]),
    mnAboveHS = mean(nhAboveHS),
    minAboveHS = min(nhAboveHS),
    maxAboveHS = max(nhAboveHS)
  )

setdiffsfm1 %>% arrange(desc(abs(mneddiffs)))
# summary(setdiffs$mneddiffs)
# quantile(setdiffs$mneddiffs, seq(0,1,.1))
```



## Evaluate the design: Inspect within set differences

Use what we know about Medellin neighborhoods, about Metrocable, to assess the research design:

```{r echo=FALSE, warnings=FALSE}
setdiffspm1 <- meddat %>%
  group_by(pm1) %>%
  summarize(
    mneddiffs =
      mean(nhAboveHS[nhTrt == 1]) -
        mean(nhAboveHS[nhTrt == 0]),
    mnAboveHS = mean(nhAboveHS),
    minAboveHS = min(nhAboveHS),
    maxAboveHS = max(nhAboveHS)
  )

setdiffspm1 %>% arrange(desc(abs(mneddiffs)))
```


## Evaluate the design: Compare to a randomized experiment. {.allowframebreaks}

The observed within-set differences differ from those that would be expected
from a randomized experiment. Here, we compare 3 designs that keep all
observations, just organized into sets differently.

```{r xbhs2, echo=TRUE}
xbfm1 <- balanceTest(nhTrt ~ nhAboveHS + strata(fm1) + strata(fm2) + strata(pm1),
  data = meddat
)
xbfm1$results[,,]
xbfm1$overall
```


## What is balanceTest doing?

```{r xbagain, echo=TRUE}
setmeanDiffs_fm1 <- meddat %>%
  group_by(fm1) %>%
  summarise(
    diffAboveHS = mean(nhAboveHS[nhTrt == 1]) - mean(nhAboveHS[nhTrt == 0]),
    nb = n(),
    nTb = sum(nhTrt),
    nCb = sum(1 - nhTrt),
    hwt = (2 * (nCb * nTb) / (nTb + nCb))
  )
setmeanDiffs_fm1 %>% arrange(desc(abs(diffAboveHS)))
```

## What is balanceTest doing with multiple sets/blocks?

The test statistic is a weighted average of the set-specific differences (same
approach as we would use to test the null in a block-randomized experiment)

```{r wtmns, echo=TRUE}
## The descriptive mean difference using block-size weights
with(setmeanDiffs_fm1, sum(diffAboveHS*nTb/sum(nTb)))
## The mean diff used as the observed value in the testing
with(setmeanDiffs_fm1, sum(diffAboveHS * hwt / sum(hwt)))
## Compare to balanceTest output
xbfm1$results[, , "fm1"]
```

## What do we mean by "compare to a randomized experiment"?

Recall that $p$-values require distributions, and distributions require processes that can be repeated (even in a Bayesian formulation). What are we repeating in an experiment? (The assignment mechanism).

```{r d1v2, echo=TRUE}
## The strata-adjusted difference in means
dstatv3 <- function(zz, mm, ss) {
  dat <- data.frame(mm = mm, z = zz, s = ss)
  datb <- dat %>%
    group_by(s) %>%
    summarize(
      mndiff = mean(mm[z == 1]) - mean(mm[z == 0]),
      nb = n(),
      pib = mean(z),
      nbwt = nb / nrow(dat),
      hbwt0 = pib * (1 - pib) * nbwt
    )
  datb$hbwt <- datb$hbwt0 / sum(datb$hbwt0)
  adjmn <- with(datb, sum(mndiff * hbwt))
  return(adjmn)
}

## The strata-specific randomization from the experimental analogue
newexp <- function(zz, ss) {
  ## newz <- unlist(lapply(split(zz,ss),sample),ss)
  newzdat <- data.frame(zz = zz, ss = ss) %>%
    group_by(ss) %>%
    mutate(newz = sample(zz))
  return(newzdat$newz)
}
```

## What do we mean by "compare to a randomized experiment"?

Recall that $p$-values require distributions, and distributions require processes that can be repeated (even in a Bayesian formulation). What are we repeating in an experiment? (The assignment mechanism).

```{r xbdist, echo=TRUE, messages=FALSE, warning=FALSE}
set.seed(123455)
nulldist <- replicate(10000, with(meddat, dstatv3(zz = newexp(zz = nhTrt, ss = fm1), mm = nhAboveHS, ss = fm1)))
obsdstat <- with(meddat, dstatv3(zz = nhTrt, mm = nhAboveHS, ss = fm1))
perm_p_value <- 2 * min(mean(nulldist >= obsdstat), mean(nulldist <= obsdstat))
perm_p_value
xbfm1$results[,,"fm1"]
```


## What do we mean by "compare to a randomized experiment"?

Recall that $p$-values require distributions, and distributions require processes that can be repeated (even in a Bayesian formulation). What are we repeating in an experiment? (The assignment mechanism).

```{r plotxbnulldist, out.width=".6\\textwidth"}
plot(density(nulldist))
curve(dnorm(x,sd=sd(nulldist)),from=min(nulldist),to=max(nulldist),col="blue",add=TRUE)
rug(nulldist)
abline(v = obsdstat)
```

#  Matching on Many Covariates: Using Mahalnobis Distance

## Dimension reduction using the Mahalanobis Distance

The general idea: dimension reduction. When we convert many columns into one
column we reduce the dimensions of the dataset (to one column). We can use the
idea of **multivariate distance** to produce distance matrices to minimize
**multivariate distances**.


```{r out.width=".7\\textwidth"}
X <- meddat[, c("nhAboveHS", "nhPopD")]
plot(meddat$nhAboveHS, meddat$nhPopD, xlim = c(-.3, .6), ylim = c(50, 700))
```

## Dimension reduction using the Mahalanobis Distance

First, let's look at Euclidean distance: $\sqrt{ (x_1 - x_2)^2 + (y_1 - y_2)^2 }$

```{r echo=FALSE, out.width=".8\\textwidth"}
par(mgp = c(1.25, .5, 0), oma = rep(0, 4), mar = c(3, 3, 0, 0))
plot(meddat$nhAboveHS, meddat$nhPopD, xlim = c(-.3, .6), ylim = c(50, 700))
points(mean(X[, 1]), mean(X[, 2]), pch = 19, cex = 1)
arrows(mean(X[, 1]), mean(X[, 2]), X["407", 1], X["407", 2])
text(.4, 200, label = round(dist(rbind(colMeans(X), X["407", ])), 2))
text(.3,100, label="Distance from the mean of both dimensions")
text(.3,75,bquote("(" * bar(x) * " = " * .(mean(X[,1])) * ", " *  bar(y) * " = " * .(mean(X[,2])) * ")"))
```

## Dimension reduction using the Mahalanobis Distance

First, let's look at Euclidean distance: $\sqrt{ (x_1 - x_2)^2 + (y_1 - y_2)^2 }$

```{r echo=FALSE, out.width=".5\\textwidth"}
par(mgp = c(1.25, .5, 0), oma = rep(0, 4), mar = c(3, 3, 0, 0))
plot(meddat$nhAboveHS, meddat$nhPopD, xlim = c(-.3, .6), ylim = c(50, 700))
points(mean(X[, 1]), mean(X[, 2]), pch = 19, cex = 1)
arrows(mean(X[, 1]), mean(X[, 2]), X["407", 1], X["407", 2])
text(.4, 200, label = round(dist(rbind(colMeans(X), X["407", ])), 2))
```

Distance between point in middle of the plot and unit "407".

```{r, echo=TRUE}
tmp <- rbind(colMeans(X), X["407", ])
tmp
sqrt((tmp[1, 1] - tmp[2, 1])^2 + (tmp[1, 2] - tmp[2, 2])^2)
```

Problem: overweights variables with bigger scales (Population Density dominates here).

## Dimension reduction using the Mahalanobis Distance

Now the standardized Euclidean distance so neither variable is overly dominant.

```{r echo=TRUE}
Xsd <- scale(X)
apply(Xsd, 2, sd) ## should be 1
round(apply(Xsd, 2, mean),8) ## should be 0
```

```{r echo=FALSE,out.width=".6\\textwidth"}
plot(Xsd[, 1], Xsd[, 2], xlab = "nhAboveHS/sd", ylab = "nhPopD/sd")
points(mean(Xsd[, 1]), mean(Xsd[, 2]), pch = 19, cex = 1)
arrows(mean(Xsd[, 1]), mean(Xsd[, 2]), Xsd["407", 1], Xsd["407", 2])
text(2, -1.2, label = round(dist(rbind(colMeans(Xsd), Xsd["407", ])), 2))
```


## Dimension reduction using the Mahalanobis Distance

The mahalanobis distance avoids the scale problem in the euclidean distance.^[For more [see here](https://stats.stackexchange.com/questions/62092/bottom-to-top-explanation-of-the-mahalanobis-distance)] Here each circle are points of the same MH distance.

```{r mhfig, echo=FALSE,out.width=".6\\textwidth"}
library(chemometrics) ## for drawMahal
library(mvtnorm)

par(mgp = c(1.5, .5, 0), oma = rep(0, 4), mar = c(3, 3, 0, 0))
mh <- mahalanobis(X, center = colMeans(X), cov = cov(X))
drawMahal(X,
  center = colMeans(X), covariance = cov(X),
  quantile = c(0.975, 0.75, 0.5, 0.25)
)
abline(v = mean(meddat$nhAboveHS), h = mean(meddat$nhPopD))
pts <- c("401", "407", "411", "202")
arrows(rep(mean(X[, 1]), 4), rep(mean(X[, 2]), 4), X[pts, 1], X[pts, 2])
text(X[pts, 1], X[pts, 2], labels = round(mh[pts], 2), pos = 1)
```

```{r}
Xsd <- scale(X)
tmp <- rbind(c(0, 0), Xsd["407", ])
mahalanobis(tmp, center = c(0, 0), cov = cov(Xsd))
edist <- sqrt((tmp[1, 1] - tmp[2, 1])^2 + (tmp[1, 2] - tmp[2, 2])^2)
edist
```

## Dimension reduction using the Mahalanobis Distance

The standardized data

```{r}
plot(Xsd[, 1], Xsd[, 2], xlab = "nhAboveHS/sd", ylab = "nhPopD/sd")
```

## Dimension reduction using the Mahalanobis Distance

With mahalanobis distance contours calculated on standardized data, but then
applied to the raw data.

```{r}
drawMahal(X, center = colMeans(X), covariance = cov(X), quantile = c(.1, .2))
```

```{r}
covX <- cov(X)
newcovX <- covX
newcovX[1, 2] <- 0
newcovX[2, 1] <- 0
```

## Dimension reduction using the Mahalanobis Distance

Using a new covariance matrix (assuming no covariance between the variables).

```{r}
drawMahal(X, center = colMeans(X), covariance = newcovX, quantile = c(.1, .2))
```

## Matching on the Mahalanobis Distance

Here using the rank based Mahalanobis distance following DOS Chap. 8 (but comparing to the ordinary version).

```{r echo=TRUE}
mhdist <- match_on(nhTrt ~ nhPopD + nhAboveHS, data = meddat, method = "rank_mahalanobis")
mhdist[1:3, 1:3]
mhdist2 <- match_on(nhTrt ~ nhPopD + nhAboveHS, data = meddat)
mhdist2[1:3, 1:3]
mhdist2[, "407"]
```

## Matching on the Mahalanobis Distance

Here using the rank based Mahalanobis distance following DOS Chap. 8 (but comparing to the ordinary version).

```{r out.width=".5\\textwidth"}
par(mgp = c(1.5, .5, 0), oma = rep(0, 4), mar = c(3, 3, 0, 0))
drawMahal(X,
  center = colMeans(X), covariance = cov(X),
  quantile = c(0.975, 0.75, 0.5, 0.25)
)
abline(v = mean(meddat$nhAboveHS), h = mean(meddat$nhPopD))
cpts <- c("401", "407", "411")
tpts <- c("101", "102", "202")
arrows(X[tpts, 1], X[tpts, 2], rep(X["407", 1]), rep(X["407", 2]))
text(X[tpts, 1], X[tpts, 2], labels = round(mhdist2[tpts, "407"], 2), pos = 1)
```

```{r echo=TRUE}
mhdist2[tpts, "407"]
```

## More on the Mahalanobis distance

To Review: The Mahalanobis distance \citep{mahalanobis1930test}, avoids the scale and correlation problem in the euclidean distance.^[For more see <https://stats.stackexchange.com/questions/62092/bottom-to-top-explanation-of-the-mahalanobis-distance>] $dist_M =  \sqrt{ (\mathbf{x} - \mathbf{\bar{x}})^T \mathbf{M}^{-1} (\mathbf{y} - \mathbf{\bar{y}}) }$ where $\mathbf{M}=\begin{bmatrix} \var(x) & \cov(x,y)  \\ \cov(x,y) & \var(y) \end{bmatrix}$


Here, using simulated data: The contour lines show points with the same
Mahalanobis distance and the numbers are Euclidean distance.

```{r}
set.seed(12345)
newX <- rmvnorm(n=45,mean=colMeans(X),sigma=matrix(c(.03,-7,-7,14375),2,2))
row.names(newX) <- row.names(X)
#plot(newX)
cor(newX)
```

```{r echo=FALSE, out.width=".4\\textwidth"}
mhnew <- mahalanobis(newX,center=colMeans(newX),cov=cov(newX))
drawMahal(newX,center=colMeans(newX),covariance=cov(newX),
          quantile = c(0.975, 0.75, 0.5, 0.25))
abline(v=mean(newX[,1]),h=mean(newX[,2]),col="gray")
points(mean(newX[,1]),mean(newX[,2]),pch=19,cex=1)
newpts <- c(3,16,17,20,22,30,42)
row.names(newX[newpts,])
arrows(mean(newX[,1]),mean(newX[,2]),newX[newpts,1],newX[newpts,2],length=.1)
edist <- as.matrix(dist(rbind(centers=colMeans(newX),newX[newpts,])))
text(newX[newpts,1]-.02,newX[newpts,2]-10,
     label=round(edist[-1,"centers"],2),font=2)
```

## Dimension reduction using the Mahalanobis distance

The contour lines show points with the same
Mahalanobis distance, the numbers are Euclidean distance. Notice that the point with Euclidean distance of 161 is farther from the center than 250 in Mahalanobis terms.

```{r echo=FALSE, results="hide", out.width=".75\\textwidth"}
mhnew <- mahalanobis(newX,center=colMeans(newX),cov=cov(newX))
drawMahal(newX,center=colMeans(newX),covariance=cov(newX),
          quantile = c(0.975, 0.75, 0.5, 0.25))
abline(v=mean(newX[,1]),h=mean(newX[,2]),col="gray")
points(mean(newX[,1]),mean(newX[,2]),pch=19,cex=1)
newpts <- c(3,16,17,20,22,30,42)
row.names(newX[newpts,])
arrows(mean(newX[,1]),mean(newX[,2]),newX[newpts,1],newX[newpts,2],length=.1)
edist <- as.matrix(dist(rbind(centers=colMeans(newX),newX[newpts,])))
text(newX[newpts,1]-.02,newX[newpts,2]-10,
     label=round(edist[-1,"centers"],2),font=2)
```


## Dimension reduction using the Mahalanobis distance

The contour lines show points with the same
Mahalanobis distance and the numbers are Euclidean distance (on the
standardized variables). (notice that 1.63 is farther from the center in
Mahalanobis terms than 2.11, but 2.11 is farther in Eucliean terms.)


```{r echo=FALSE}
newXsd <- scale(newX)
drawMahal(newXsd,center=colMeans(newXsd),covariance=cov(newXsd),
          quantile = c(0.975, 0.75, 0.5, 0.25))
abline(v=mean(newXsd[,1]),h=mean(newXsd[,2]),col="gray")
points(mean(newXsd[,1]),mean(newXsd[,2]),pch=19,cex=1)
arrows(mean(newXsd[,1]),mean(newXsd[,2]),newXsd[newpts,1],newXsd[newpts,2],length=.1)
edistSd <- as.matrix(dist(rbind(centers=colMeans(newXsd),newXsd[newpts,])))
text(newXsd[newpts,1]-.1,newXsd[newpts,2]-.1,
     label=round(edistSd[-1,"centers"],2),font=2)
```


## Matching on the Mahalanobis Distance

```{r echo=TRUE}
mhdist <- match_on(nhTrt ~ nhPopD + nhAboveHS, data = meddat, method = "rank_mahalanobis")

fmMh <- fullmatch(mhdist, data = meddat)
summary(fmMh, min.controls = 0, max.controls = Inf)
summary(unlist(matched.distances(fmMh,mhdist)))

quantile(as.vector(mhdist),seq(0,1,.1))
fmMh1 <- fullmatch(mhdist + caliper(mhdist,1) , data = meddat) #, min.controls = 1)
summary(fmMh1, min.controls = 0, max.controls = Inf)
summary(unlist(matched.distances(fmMh1,mhdist)))

```

```{r echo=TRUE}

xbMh <- balanceTest(nhTrt ~ nhAboveHS + nhPopD+strata(fmMh)+strata(fmMh1),  data = meddat)
xbMh$results[,,]
xbMh$overall
```


#  Matching on Many Covariates: Using Propensity Scores

## Matching on the propensity score

**Make the score**^[Note that we will be using `brglm` or `bayesglm` in the
future because of logit separation problems when the number of covariates
increases.]

```{r echo=TRUE}
theglm <- glm(nhTrt ~ nhPopD + nhAboveHS + HomRate03, data = meddat, family = binomial(link = "logit"))
thepscore <- theglm$linear.predictor
thepscore01 <- predict(theglm, type = "response")
```

We tend to match on the linear predictor rather than the version required to
range only between 0 and 1.

```{r echo=FALSE, out.width=".7\\textwidth"}
par(mfrow = c(1, 2), oma = rep(0, 4), mar = c(3, 3, 2, 0), mgp = c(1.5, .5, 0))
boxplot(split(thepscore, meddat$nhTrt), main = "Linear Predictor (XB)")
stripchart(split(thepscore, meddat$nhTrt), add = TRUE, vertical = TRUE)

boxplot(split(thepscore01, meddat$nhTrt), main = "Inverse Link Function (g^-1(XB)")
stripchart(split(thepscore01, meddat$nhTrt), add = TRUE, vertical = TRUE)
```

## Matching on the propensity score

```{r echo=TRUE}
psdist <- match_on(theglm, data = meddat)
psdist[1:4, 1:4]
fmPs <- fullmatch(psdist, data = meddat)
summary(fmPs, min.controls = 0, max.controls = Inf)
```

## Why a propensity score? {.fragile}

1. The Mahanobis distance weights all covariates equally (and the rank based version especially tries to do this). But, maybe not all covariates matter equally for $Z$. Or maybe we care most about covariates that drive the selection or other process by which units get $Z=1$ versus $Z=0$.


\begin{center}
\begin{tikzcd}[column sep=large,every arrow/.append style=-latex]
& Z  \arrow[from=1-2,to=1-3, "\tau"] &  y \\
x_1 \arrow[from=2-1,to=1-2, "\beta_1" ] \arrow[from=2-1,to=1-3,grey] &
x_2 \arrow[from=2-2,to=1-2, "\beta_2" ] \arrow[from=2-2,to=1-3,grey] &
\ldots &
x_p \arrow[from=2-4,to=1-2,  "\beta_p" near start ] \arrow[from=2-4,to=1-3,grey]
\end{tikzcd}
\end{center}

2. @rosenbaum:rubi:1983 and @rosenbaum:rubi:1984a show that if we knew the true propensity score (ex. we knew the true model and the correct covariates) then we could stratify on the p-score and have adjusted for all of the covariates. (In practice, we don't know either. But the propensity score often performs well as an ingredient in a matched design)



## Matching on the propensity score: What do the distance matrix entries mean?

`optmatch` creates a scaled propensity score distance by default --- scaling by,
roughly, the pooled median absolute deviation of the covariate (or here, the
propensity score). So, the distance matrix entries are like standard deviations
--- standardized scores.


```{r glm1, echo=TRUE}
meddat <- as.data.frame(meddat)
row.names(meddat) <- meddat$nh
theglm <- glm(nhTrt ~ nhPopD + nhAboveHS + HomRate03, data = meddat, family = binomial(link = "logit"))
thepscore <- theglm$linear.predictor
```

```{r echo=TRUE}
## Create a distance matrix using the propensity scores
psdist <- match_on(theglm, data = meddat)
psdist[1:4, 1:4]
```

## Matching on the propensity score: What do the distance matrix entries mean? {.allowframebreaks}

What do those distances mean? (They are standardized absolute differences.)

```{r echo=TRUE}
## Calculate the simple absolute distances in propensity score
simpdist <- outer(thepscore, thepscore, function(x, y) {
  abs(x - y)
})
simpdist["101", c("401", "402", "403")]
## Notice that these are not the same
psdist["101", c("401", "402", "403")]
## But they are perfectly linearly related
cor(as.vector(simpdist["101",colnames(psdist)]),as.vector(psdist["101",]))
## Notice that they have a fixed relationship
simpdist["101", c("401", "402", "403")] / psdist["101", c("401", "402", "403")]
```

Optmatch scales the scores so that we can interpret them as standardized differences:

```{r}
## Median Absolute Deviations
mad(thepscore[meddat$nhTrt == 1],na.rm=TRUE)
mad(thepscore[meddat$nhTrt == 0], na.rm=TRUE)
## Pooled median absolute deviation (average MAD between the treated and control groups)
(mad(thepscore[meddat$nhTrt == 1],na.rm=TRUE) + mad(thepscore[meddat$nhTrt == 0],na.rm=TRUE)) / 2
pooledmad <- (mad(thepscore[meddat$nhTrt == 1],na.rm=TRUE) + mad(thepscore[meddat$nhTrt == 0],na.rm=TRUE)) / 2
## We can see the actual R function here: optmatch:::match_on_szn_scale
optmatch:::match_on_szn_scale(thepscore, trtgrp = meddat$nhTrt)
simpdist["101", c("401", "402", "403")] / 1.569
## Same as:
psdist["101", c("401", "402", "403")]
```


## What about using many covariates? The separation problem in logistic regression

What if we want to match on more than two covariates? Let's step through the following to discover a problem with logistic regression when the number of covariates is large relative to the size of the dataset.

```{r echo=TRUE}
library(splines)
library(arm)
thecovs <- unique(c(names(meddat)[c(5:7, 9:24)], "HomRate03"))
balfmla <- reformulate(thecovs, response = "nhTrt")
psfmla <- update(balfmla, . ~ . + ns(HomRate03, 2) + ns(nhPopD, 2) + ns(nhHS, 2))
glm0 <- glm(balfmla, data = meddat, family = binomial(link = "logit"))
glm1 <- glm(psfmla, data = meddat, family = binomial(link = "logit"))
bayesglm0 <- bayesglm(balfmla, data = meddat, family = binomial(link = "logit"))
bayesglm1 <- bayesglm(psfmla, data = meddat, family = binomial(link = "logit"))
psg1 <- predict(glm1, type = "response")
psg0 <- predict(glm0, type = "response")
psb1 <- predict(bayesglm1, type = "response")
psb0 <- predict(bayesglm0, type = "response")
```
## The separation problem

Logistic regression is excellent at discriminating between groups \ldots often **too excellent** for us \autocite{gelman2008weakly}. First evidence of this is big and/or missing coefficients in the propensity score model. See the coefficients below (recall that we are predicting `nhTrt` with these covariates in those models):

```{r echo=FALSE}
thecoefs <- rbind(
  glm0 = coef(glm0)[1:20],
  glm1 = coef(glm1)[1:20],
  bayesglm0 = coef(bayesglm0)[1:20],
  bayesglm1 = coef(bayesglm1)[1:20]
)
thecoefs[, 1:5]
```

## The separation problem

```{r, echo=FALSE, out.width=".9\\textwidth"}
par(mfrow = c(1, 2))
matplot(t(thecoefs), axes = FALSE)
axis(2)
axis(1, at = 0:19, labels = colnames(thecoefs), las = 2)
matplot(t(thecoefs), axes = FALSE, ylim = c(-15, 10))
axis(2)
axis(1, at = 0:19, labels = colnames(thecoefs), las = 2)
legend("topright", col = 1:4, lty = 1:4, legend = c("glm0", "glm1", "bayesglm0", "bayesglm1"))
```


## The separation problem in logistic regression

So, if we are interested in using the propensity score to compare observations in regards the multi-dimensional space of many covariates, we would probably prefer a dimensional reduction model like `bayesglm` over `glm`.

```{r out.width=".9\\textwidth", echo=FALSE}
par(mfrow = c(2, 2), mar = c(3, 3, 2, .1))
boxplot(psg0 ~ meddat$nhTrt, main = paste("Logit", length(coef(glm0)), " parms", sep = " "))
stripchart(psg0 ~ meddat$nhTrt, vertical = TRUE, add = TRUE)
boxplot(psg1 ~ meddat$nhTrt, main = paste("Logit", length(coef(glm1)), " parms", sep = " "))
stripchart(psg1 ~ meddat$nhTrt, vertical = TRUE, add = TRUE)
boxplot(psb0 ~ meddat$nhTrt, main = paste("Shrinkage Logit", length(coef(bayesglm0)), " parms", sep = " "))
stripchart(psb0 ~ meddat$nhTrt, vertical = TRUE, add = TRUE)
boxplot(psb1 ~ meddat$nhTrt, main = paste("Shrinkage Logit", length(coef(bayesglm1)), " parms", sep = " "))
stripchart(psb1 ~ meddat$nhTrt, vertical = TRUE, add = TRUE)
```


# Major Matching modes: Briefly, Greed versus Optimal Matching

##  Optimal (communitarian) vs greedy (individualistic) matching {.fragile}

Compare the greedy to optimal matched designs:

\begin{center}
    \begin{tabular}{l|cccc}
      & \multicolumn{4}{c}{Illustrator} \\
Writer & Mo& John & Terry  & Pat \\ \hline
Ben    & 0 & 1 & 1 & 10 \\
Jake   & 10& 0 & 10 & 10 \\
Tom    &  1& 1 & 20 & $\infty$ \\ \hline
    \end{tabular}
  \end{center}

##  Optimal (communitarian) vs greedy (individualistic) matching {.fragile}

Compare the greedy to optimal matched designs:

\begin{center}
    \begin{tabular}{l|cccc}
      & \multicolumn{4}{c}{Illustrator} \\
Writer & Mo& John & Terry  & Pat \\ \hline
Ben    & 0 & 1 & 1 & 10 \\
Jake   & 10& 0 & 10 & 10 \\
Tom    &  1& 1 & 20 & $\infty$ \\ \hline
    \end{tabular}
  \end{center}


Greedy match without replacement has mean distance (0+0+20)/3=6.67. The optimal
match keeps all the obs, and has mean distance (1+0+1)/3=.67.

```{r simpmatch, echo=TRUE, warning=FALSE, messages=FALSE}
bookmat <- matrix(c(0, 1, 1, 10, 10, 0, 10, 10, 1, 1, 20, 100 / 0), nrow = 3, byrow = TRUE)
dimnames(bookmat) <- list(c("Ben", "Jake", "Tom"), c("Mo", "John", "Terry", "Pat"))
pairmatch(bookmat)
fullmatch(bookmat)
```

\note{
*Greedy:* Ben-Mo (0) , Jake-John (0), Tom-Terry (20)
*Optimal:* Ben-Terry (1), Jake-John (0), Tom-Mo (1)
}


# Matching Tricks of the Trade: Calipers, Exact Matching, Missing Data

## Calipers {.allowframebreaks}

The optmatch package allows calipers (which forbids certain pairs from being matched).^[You can implement penalties by hand.] Here, for example, we forbid comparisons which differ by more than 2 propensity score standardized distances.

```{r echo=TRUE}
## First inspect the distance matrix itself: how are the distances distributed?
quantile(as.vector(psdist), seq(0, 1, .1))
```

## Calipers {.shrink}


```{r echo=TRUE}
## Next, apply a caliper (setting entries to Infinite)
psdistCal <- psdist + caliper(psdist, 2)
as.matrix(psdist)[5:10, 5:10]
as.matrix(psdistCal)[5:10, 5:10]
```

## Calipers

The optmatch package allows calipers (which forbid certain pairs from being matched).^[You can implement penalties by hand.] Here, for example, we forbid comparisons which differ by more than 2 standard deviations on the propensity score. (Notice that we also use the `propensity.model` option to `summary` here to get a quick look at the balance test:)

```{r echo=TRUE}
fmCal1 <- fullmatch(psdist + caliper(psdist, 2), data = meddat, tol = .00001)
summary(fmCal1, min.controls = 0, max.controls = Inf, propensity.model = theglm)
pmCal1 <- pairmatch(psdist + caliper(psdist, 2), data = meddat, remove.unmatchables = TRUE)
summary(pmCal1, propensity.model = theglm)
```

## Calipers

Another example: We may want to match on propensity distance but disallow any pairs with extreme mahalnobis distance and/or extreme differences in baseline homicide rates (here using many covariates all together).


```{r echo=TRUE}
## Create an R formula object from vectors of variable names
balfmla <- reformulate(c("nhPopD", "nhAboveHS"), response = "nhTrt")
## Create a mahalanobis distance matrix (of rank transformed data)
mhdist <- match_on(balfmla, data = meddat, method = "rank_mahalanobis")
## Now make a matrix recording absolute differences between neighborhoods in
## terms of baseline homicide rate
tmpHom03 <- meddat$HomRate03
names(tmpHom03) <- rownames(meddat)
absdist <- match_on(tmpHom03, z = meddat$nhTrt, data = meddat)
absdist[1:3, 1:3]
quantile(as.vector(absdist), seq(0, 1, .1))
quantile(as.vector(mhdist), seq(0, 1, .1))
```

## Calipers

Another example: We may want to match on propensity distance but disallow any pairs with extreme mahalnobis distance and/or extreme differences in baseline homicide rates (here using many covariates all together).

```{r echo=TRUE}
## Now create a new distance matrix using two calipers:
distCal <- psdist + caliper(mhdist, 3) + caliper(absdist, 2)
as.matrix(distCal)[5:10, 5:10]
## Compare to:
as.matrix(mhdist)[5:10, 5:10]
```

## Calipers

Now, use this new matrix for the creation of stratified designs --- but possibly excluding some units (also showing here the `tol` argument. The version with the tighter tolerance produces a solution with smaller overall distances)

```{r echo=TRUE}
fmCal2a <- fullmatch(distCal, data = meddat, tol = .1)
summary(fmCal2a, min.controls = 0, max.controls = Inf, propensity.model = theglm)
fmCal2b <- fullmatch(distCal, data = meddat, tol = .00001)
summary(fmCal2b, min.controls = 0, max.controls = Inf, propensity.model = theglm)

meddat$fmCal2a <- fmCal2a
meddat$fmCal2b <- fmCal2b

fmCal2a_dists <- matched.distances(fmCal2a, distCal)
fmCal2b_dists <- matched.distances(fmCal2b, distCal)

mean(unlist(fmCal2a_dists))
mean(unlist(fmCal2b_dists))
```

## Exact Matching

We often have covariates that are categorical/nominal and for which we really care about strong balance. One approach to solve this problem is match **exactly** on one or more of such covariates. If `fullmatch` or `match_on` is going slow, this is also an approach to speed things up.

```{r echo=FALSE}
meddat$classLowHi <- ifelse(meddat$nhClass %in% c(2, 3), "hi", "lo")
```

```{r echo=TRUE}
dist2 <- psdist + exactMatch(nhTrt ~ classLowHi, data = meddat)
## or mhdist <- match_on(balfmla,within=exactMatch(nhTrt~classLowHi,data=meddat),data=meddat,method="rank_mahalanobis")
## or fmEx1 <- fullmatch(update(balfmla,.~.+strata(classLowHi)),data=meddat,method="rank_mahalanobis")
fmEx1 <- fullmatch(dist2, data = meddat, tol = .00001)
fmEx1 <- fullmatch(dist2, data = meddat, tol = .00001, min.controls=c("hi"=1,"lo"=.5))
summary(fmEx1, min.controls = 0, max.controls = Inf, propensity.model = theglm)
print(fmEx1, grouped = T)
meddat$fmEx1 <- fmEx1
```

## Exact Matching

Showing treatment and control by matched set (including the variable defining
exactly matched sets)

```{r echo=TRUE}
ftable(Class = meddat$classLowHi, Trt = meddat$nhTrt, fmEx1, col.vars = c("Class", "Trt"))
```

## Missing data and matching

What if `nhPopD` had some missing data?

```{r md1, echo=TRUE}
set.seed(12345)
meddat$nhPopD[sample(1:45, 10)] <- NA
summary(meddat$nhPopD)
xb0 <- balanceTest(nhTrt ~ nhPopD + nhAboveHS + HomRate03, data = meddat)
```

We would want to compare units who are equally likely to have `nhPopD` missing. So, we create a new variable:

```{r md2, echo=TRUE}
newdat <- fill.NAs(meddat[, c("nhAboveHS", "nhPopD")])
head(newdat)
stopifnot(all.equal(row.names(newdat), row.names(meddat)))
```

## Missing data and matching

What if `nhPopD` had some missing data?
We would want to compare units who are equally likely to have `nhPopD` missing. So, we create a new variable:

```{r echo=TRUE}
newdat <- cbind(newdat, meddat[, c("nhTrt", "HomRate08", "HomRate03")])
head(newdat)
```

## Missing data and matching

And we include that variable in our balance testing and matching:

```{r echo=TRUE}
theglm <- arm::bayesglm(nhTrt ~ nhAboveHS + nhPopD + nhPopD.NA + HomRate03, data = newdat)
psdist <- match_on(theglm, data = meddat)
maxCaliper(theglm$linear.predictor, z = newdat$nhTrt, widths = c(.1, .5, 1))
balfmla <- formula(theglm)
fm0 <- fullmatch(psdist + caliper(psdist, 2), data = newdat)
summary(fm0, min.controls = 0, max.controls = Inf, propensity.model = theglm)
summary(unlist(matched.distances(fm0, psdist)))
newdat$fm0 <- fm0
xb0 <- balanceTest(update(balfmla,.~.+strata(fm0)), data = newdat)
xb0$overall
xb0$results[,,]
```

## Missing Data and Matching

So:

 1. Missing data on covariates is not a big problem --- such data reveals
    information to us about the units pre-treatment, so we just stratify on it.
    We treat missing data as just another covariate.
 2. Missing data on treatment assignment or the outcome is a bigger problem: we
    will tend to use bounds to report on the range of possible answers in such
    cases.





## Summary:

 - Statistical adjustment with linear regression models is hard to justify.
 - Stratification via matching is easier to justify and assess (and describe).
 - We can build a stratified research design allowing an algorithm to do some
   work, and bringing in our substantive expertise and rhetorical strategies
   for other work (choosing the covariates, deciding which covariates should be
   closely matched-on and which not so closely).
 - Matching solves the problem of making comparisons that are transparent
   (Question: "Did you adjust enough for X?" Ans: "Here is some evidence about
   how well I did.")
 - You can adjust for one variable or more than one (if more than one, you
   need to choose one or more methods for reducing many columns to one
   column).
 - The workflow involves the creation of a distance matrix, asking an
   algorithm to find the best configuration of sets that minimize the
   distances within set, and checking balance. (Eventually, it will also be
   concerned about the effective sample size.)
 - We can restrict certain matches --- using calipers or exact-matching, using
   different distance matrices.
 - We can match on missing values on covariates.
 - Some choices of score creation / dimension reduction raise other questions
   and problems (ex. Mahalanobis versus Rank-Based Mahalanobis distances;
   Propensity Score creation without overfitting.)


## References