CausalML Documentation

CausalML is a Python package designed for uplift modeling and causal inference using machine learning. It provides a standard interface to estimate the Conditional Average Treatment Effect (CATE), which measures the causal impact of an intervention T on an outcome Y for users with observed features X.

Key use cases include:

• Campaign targeting optimization: Identifying customers who will respond favorably to an ad exposure to increase ROI.
• Personalized engagement: Estimating heterogeneous treatment effects for different customer/treatment combinations to build optimal recommendation systems.

CausalML provides several categories of algorithms for causal inference and uplift modeling:

• Tree-based algorithms: Includes Uplift Random Forests (with various criteria like KL divergence, Euclidean Distance, Chi-Square, or Contextual Treatment Selection), Interaction Trees (IT), and Causal Inference Trees (CIT).
• Meta-learner algorithms: Frameworks to estimate Conditional Average Treatment Effect (CATE) using base learners, including S-learner, T-learner, X-learner, R-learner, and Doubly Robust (DR) learner.
• Instrumental variables algorithms: Includes 2-Stage Least Squares (2SLS) and Doubly Robust Instrumental Variable (DRIV) learner.
• Neural network based algorithms: CEVAE and DragonNet.
• Treatment optimization algorithms: Counterfactual Unit Selection and Counterfactual Value Estimator.

CausalML provides several utility modules for data preparation, matching, and evaluation:

• causalml.dataset: Utilities for handling causal datasets.
• causalml.match: Methods for causal matching (e.g., propensity score matching).
• causalml.propensity: Tools for estimating propensity scores.
• causalml.metrics: Metrics for evaluating causal models and uplift.
• causalml.optimize: Optimization routines for causal inference.
• causalml.features: Feature engineering and transformation tools.
• causalml.feature_selection: Methods for selecting relevant features for causal models.

The causalml.inference package provides various methods for estimating causal effects. Depending on your data and modeling requirements, you can use the following submodules:

• causalml.inference.tree: Tree-based causal inference methods.
• causalml.inference.meta: Meta-learners (e.g., S-Learner, T-Learner, X-Learner).
• causalml.inference.iv: Instrumental Variable (IV) methods.
• causalml.inference.nn: Neural Network-based causal inference.
• causalml.inference.tf: TensorFlow-based causal inference implementations.

To get started quickly with CausalML, use the following resources:

• Quickstart: Access code snippets and basic usage guides at the Quickstart documentation.
• Example Notebooks: Explore practical implementations and complex workflows through the Example Notebooks.

To install from source, clone the repository and use pip install -e ..

Prerequisite: If you need Graphviz, install it via conda install python-graphviz, brew install graphviz (macOS), or sudo apt-get install graphviz (Linux).

Use the following commands to install with specific backends:

• .[tf] for tensorflow
• .[torch] for torch
• .[jax] for jax

git clone https://github.com/uber/causalml.git
cd causalml

# Base source install
pip install -e .

# With TensorFlow
pip install -e ".[tf]"

# With PyTorch
pip install -e ".[torch]"

# With JAX
pip install -e ".[jax]"

Matching methods aim to mimic randomized controlled trials by finding treated and non-treated units that are as similar as possible based on relevant characteristics.

Commonly, this is achieved using the propensity score $e_i(X_i) = P(W_i = 1 | X_i)$. Units are then matched using a distance criterion, such as $k:1$ nearest neighbors. This method typically estimates the Average Treatment Effect on the Treated (ATT): $$\mathbb{E}[Y(1) | W = 1] - \mathbb{E}[Y(0) | W = 1]$$

You can test causal methodologies using simulations that generate data with known causal and non-causal links. causalml implements several synthetic data generation mechanisms based on Nie (2017):

• Mechanism 1: Complex outcome regression with an easy treatment effect.
• Mechanism 2: Simulates a randomized trial (fair coin flip for treatment).
• Mechanism 3: Easy propensity score but a difficult control outcome.
• Mechanism 4: Unrelated treatment and control arms.

Since ground-truth treatment effects are never observed, CausalML provides surrogate metrics to evaluate the effect-magnitude accuracy of fitted CATE models using only observed data:

• DR (Doubly Robust) pseudo-outcome loss: Constructs a doubly-robust pseudo-outcome $\phi$ using cross-fitted propensity and outcome models. The loss is calculated as the mean squared error between the model's CATE estimate and the pseudo-outcome: $\text{DR loss}(\hat{\tau}) = \frac{1}{n}\sum_i (\hat{\tau}(X_i) - \phi_i)^2$. Lower is better.
• Plug-in T-learner loss: A simpler baseline that uses a cross-fit T-learner's held-out estimate as a proxy for the true CATE. The loss is $\text{T-loss}(\hat{\tau}) = \frac{1}{n}\sum_i (\hat{\tau}(X_i) - (\hat{\mu}_1(X_i) - \hat{\mu}_0(X_i)))^2$.