---
title: "Augmented Balancing Weights as Linear Regression"
author: "Shikhar Tyagi, Arvind Pandey, Bhupendra Singh, Vrijesh Tripathi"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Augmented Balancing Weights as Linear Regression}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(AugBalWeight)
```

# Introduction

The `AugBalWeight` package implements the methodology established in **Bruns-Smith, Dukes, Feller, and Ogburn (2026)** (*Journal of the Royal Statistical Society Series B*, DOI: [10.1093/jrsssb/qkaf019](https://doi.org/10.1093/jrsssb/qkaf019)). 

The paper establishes novel numeric equivalences showing that combining outcome regression models with balancing weights (automatic debiased machine learning) is numerically equivalent to a single linear model with coefficients that are a weighted combination of estimated OLS coefficients and the base outcome model coefficients.

# Quick Start with LaLonde (1986) Job Training Dataset

We demonstrate the estimation of the Average Treatment Effect on the Treated (ATT) using the canonical LaLonde (1986) job training dataset.

```{r lalonde_example}
# Load canonical LaLonde dataset
data(lalonde_data)

# Specify covariates
covariates <- c("age", "educ", "black", "hisp", "married", "re74", "re75", "age2", "educ2", "re742")
X <- as.matrix(lalonde_data[, covariates])
Y <- lalonde_data$re78
Z <- lalonde_data$treat

# Estimate ATT using Ridge-augmented L2 balancing weights
fit_att <- aug_bal_att(
  Y = Y,
  Z = Z,
  X = X,
  type = "l2",
  outcome_model = "ridge",
  tuning_method = "cv_outcome"
)

# Print ATT estimate and confidence interval
print(fit_att)
```

# Summary and Coefficient Comparison

We can examine the summary table comparing OLS coefficients, base outcome model coefficients, and implied augmented coefficients $\hat{\beta}_{\text{aug}}$.

```{r summary_example}
summary(fit_att)
```

# Balance Diagnostics

The package includes safe graphical routines for diagnosing covariate imbalance pre- and post-balancing.

```{r plot_example, fig.width = 7, fig.height = 5}
# Plot covariate balance diagnostic
plot(fit_att, which = 1)

# Plot distribution of estimated balancing weights
plot(fit_att, which = 2)
```

# Double Lasso ($\ell_\infty$ Balancing)

For high-dimensional settings, `double_lasso` performs $\ell_\infty$ balancing weights combined with a lasso outcome model, demonstrating the double selection phenomenon ($I_{\text{aug}} = I_\lambda \cup I_\delta$).

```{r double_lasso_example}
fit_lasso <- double_lasso(
  Y = Y[Z == 0],
  X_p = X[Z == 0, ],
  target_mean = colMeans(X[Z == 1, ]),
  lambda = 0.05,
  delta = 0.05
)

cat("Active outcome features :", fit_lasso$active_outcome, "\n")
cat("Active balance features :", fit_lasso$active_balance, "\n")
cat("Active union features   :", fit_lasso$active_union, "\n")
```

# References

- Bruns-Smith, D., Dukes, O., Feller, A., & Ogburn, E. L. (2026). Augmented balancing weights as linear regression. *Journal of the Royal Statistical Society Series B: Statistical Methodology*, 88(3), 699–723. <doi:10.1093/jrsssb/qkaf019>
- Robins, J. M., Rotnitzky, A., & Zhao, L. P. (1994). Estimation of regression coefficients when some regressors are not always observed. *Journal of the American Statistical Association*, 89(427), 846–866.
- Chernozhukov, V., Chetverikov, D., Demirer, M., Duflo, E., Hansen, C., Newey, W., & Robins, J. (2018). Double/debiased machine learning for treatment and structural parameters. *The Econometrics Journal*, 21(1), C1–C68.