Distributional instrumental variable regression in R.
Overview
divR implements the Distributional Instrumental Variable method of Holovchak, Saengkyongam, Meinshausen, and Shen (2025). The target is the interventional distribution P(Y | do(X)) when treatment is endogenous and an instrument is available. Once the distribution is fit, one can report means, quantiles, or simulated draws.
The package is based on the DistributionIV CRAN package by the same authors. I added vignettes for the paper simulations and applications.
Installation
# Install dependencies
install.packages(c("checkmate", "torch"))
torch::install_torch()
# Install divR
remotes::install_github("xiangao/divR")Usage
library(divR)
# Simulate data with hidden confounding
set.seed(42)
n <- 1000
H <- rnorm(n)
Z <- matrix(rnorm(n), ncol = 1)
X <- matrix(Z + H + rnorm(n), ncol = 1)
Y <- matrix(2 * X + H + rnorm(n), ncol = 1)
# Fit DIV model
model <- divR(Z = Z, X = X, Y = Y, num_epochs = 500, silent = TRUE)
print(model)
# Interventional prediction E[Y | do(X)]
Xtest <- matrix(seq(-3, 3, length.out = 100), ncol = 1)
pred_mean <- predict(model, Xtest = Xtest, type = "mean")
pred_q <- predict(model, Xtest = Xtest, type = "quantile", quantiles = c(0.1, 0.5, 0.9))
pred_s <- predict(model, Xtest = Xtest, type = "sample", nsample = 100)Vignettes
Full documentation: https://xiangao.github.io/divR/
Simulation Studies (Paper Sections 3 & 5)
- Section 3.3: Softplus Example — Motivating example with distributional overlap and density comparisons
- Section 5.1: Sinusoidal DGP — Nonlinear post-additive noise outcome model
- Section 5.2: Binary Treatment & QTE — Quantile treatment effects with logistic DGP
- Section 5.3: Multivariate X — Multiple endogenous variables with partial interventional mean
- Section 5.4: Instrument Strength — DIV robustness to weak instruments (alpha=0 vs alpha=2)
Real-Data Applications (Paper Section 6)
- Section 6.1: Colonial Origins — Acemoglu et al. (2001), DIV vs 2SLS vs OLS
- Section 6.2: Single-Cell Biology — Sachs et al. (2005) protein signaling generalizability