hbal – User Manual

Welcome

This manual serves as a user guide for the hbal package in R, which implements hierarchically regularized entropy balancing. For the technical details, see Xu and Yang (2022).

hbal is suitable for estimating the average treatment effect on the treated (ATT) with a binary treatment under strong ignorability. It is an extension of entropy balancing: it automatically expands the covariate space to include higher-order terms (squared and cubic terms and interactions), then seeks approximate balance on the expanded covariates using ridge penalties with a hierarchical structure, chosen by cross-validation.

Installation

You can install hbal in three ways. The CRAN release is the stable version:

install.packages("hbal")

The main branch on GitHub mirrors the CRAN release:

install.packages("devtools") # if not already installed
devtools::install_github("xuyiqing/hbal")

The dev branch carries the up-to-date development version. New features and fixes land there first and reach CRAN with the next release. This manual is written against the development version, so if an example here does not run on your CRAN install, install from dev:

devtools::install_github("xuyiqing/hbal@dev")

Installing from GitHub compiles the package’s C++ code. That needs a compiler: Rtools on Windows, or the Xcode command-line tools on macOS.

# Check installed version
installed.packages()["hbal", "Version"]
#> [1] "1.3.0"

hbal depends on the following packages, which should be installed automatically when hbal is being installed. You can also install them manually.

install_all <- function(packages) {
  installed_pkgs <- installed.packages()[, "Package"]
  for (pkg in packages) {
    if (!pkg %in% installed_pkgs) {
      install.packages(pkg)
    }
  }
}
packages <- c("estimatr", "glmnet", "ggplot2", "gridExtra", "gtable",
              "nloptr", "Rcpp", "RcppEigen", "stringr", "generics")
install_all(packages)

Quick reference

hbal provides two main functions:

• hbal(): performs hierarchically regularized entropy balancing.
• att(): calculates the average treatment effect on the treated (ATT) from an hbal object returned by hbal().

And two S3 methods:

• summary(): summarizes the balancing results.
• plot(): visualizes covariate balance before and after weighting, or the distribution of balancing weights.

Organization

• Chapter 1  Basic Usage — Simulating toy data, the basic hbal() / summary() workflow, and how hbal relates to entropy balancing (ebal).
• Chapter 2  Obtaining the ATT — Obtaining the ATT with att(): the default augmented balancing weights estimator (method = "abw"), the legacy estimators, and simulation evidence comparing them.
• Chapter 3  Additional Options — Additional hbal() options: exact/approximate balancing, user-supplied penalties, controlling serial expansion, double selection, and keeping/excluding covariates.
• Chapter 4  Example 1: Lalonde Data — Worked example on the LaLonde job-training data.
• Chapter 5  Example 2: Black and Owens (2016) — Worked example on Black and Owens (2016)’s study of circuit court judges.

How to Cite

To cite the hbal package, please use:

Xu, Yiqing, and Eddie Yang. 2022. “Hierarchically Regularized Entropy Balancing.” Political Analysis. https://doi.org/10.1017/pan.2022.12.

@article{XuYang2022,
  title = {Hierarchically Regularized Entropy Balancing},
  author = {Xu, Yiqing and Yang, Eddie},
  journal = {Political Analysis},
  year = {2022},
  doi = {10.1017/pan.2022.12}
}

Contributors

• Yiqing Xu
• Eddie Yang
• StatsClaw (Agentic System for Statistical Software Development)

Report bugs

Please report bugs to yiqingxu [at] stanford.edu or open an issue on GitHub.

Athey, Susan, Guido W Imbens, and Stefan Wager. 2018. “Approximate Residual Balancing: Debiased Inference of Average Treatment Effects in High Dimensions.” Journal of the Royal Statistical Society: Series B (Statistical Methodology) 80 (4): 597–623.

Belloni, Alexandre, Victor Chernozhukov, and Christian Hansen. 2014. “Inference on Treatment Effects After Selection Among High-Dimensional Controls.” The Review of Economic Studies 81 (2): 608–50.

Ben-Michael, Eli, Avi Feller, David A Hirshberg, and José R Zubizarreta. 2021. “The Balancing Act in Causal Inference.” arXiv Preprint arXiv:2110.14831.

Black, Ryan C, and Ryan J Owens. 2016. “Courting the President: How Circuit Court Judges Alter Their Behavior for Promotion to the Supreme Court.” American Journal of Political Science 60 (1): 30–43.

Bruns-Smith, David, Oliver Dukes, Avi Feller, and Elizabeth L Ogburn. 2023. “Augmented Balancing Weights as Linear Regression.” arXiv Preprint arXiv:2304.14545.

Dehejia, Rajeev H, and Sadek Wahba. 1999. “Causal Effects in Nonexperimental Studies: Reevaluating the Evaluation of Training Programs.” Journal of the American Statistical Association 94 (448): 1053–62.

Golub, Gene H, Michael Heath, and Grace Wahba. 1979. “Generalized Cross-Validation as a Method for Choosing a Good Ridge Parameter.” Technometrics 21 (2): 215–23.

Hainmueller, Jens. 2012. “Entropy Balancing for Causal Effects: A Multivariate Reweighting Method to Produce Balanced Samples in Observational Studies.” Political Analysis 20 (1): 25–46.

LaLonde, Robert J. 1986. “Evaluating the Econometric Evaluations of Training Programs with Experimental Data.” The American Economic Review, 604–20.

Lin, Winston. 2013. “Agnostic Notes on Regression Adjustments to Experimental Data: Reexamining Freedman’s Critique.” The Annals of Applied Statistics 7 (1): 295–318.

Xu, Yiqing, and Eddie Yang. 2022. “Hierarchically Regularized Entropy Balancing.” Political Analysis forthcoming.