DOCSEARCHbyAlgolia
Submit Docs

causallib

repository·master·Indexed 21 days ago

https://github.com/biomedsciai/causallib

A Python package for flexible and modular causal inference modeling using a scikit-learn-inspired API. It provides tools for estimating counterfactual outcomes and treatment effects via methods such as Inverse Probability Weighting (IPW), Standardization, and Doubly Robust methods. The library includes a contrib module with experimental algorithms like the Heterogeneous Effect Mixture Model (HEMM) and Adversarial Balancing, as well as utilities for synthetic data generation via CausalSimulator and model evaluation.

Tokens
20.6K
Snippets
53
Records
87
Agent score
73%

What's inside causallib

  1. Overview of the `preprocessing` module

    master

    The preprocessing module in causallib provides specialized filters and transformers designed to augment scikit-learn. These tools are particularly useful for causal inference workflows where handling missing values (NaNs) and feature selection based on outcome association are critical.

    Available Filters

    Filters in this module remove features based on several criteria:

    • Almost constant features: Removes features that are nearly constant in value (rather than just variance).
    • Highly correlated features: Removes features that show high correlation with other features.
    • Low variance features: Removes features with low variance (supports datasets containing NaN values).
    • Mostly NaN features: Removes features that consist primarily of missing values.
    • Outcome-associated features: Removes features that have a high association with the outcome (beyond simple correlation).

    Available Transformers

    • Standard Scaler: A scaler that handles NaN values.
    • Min/Max Scaler: A standard min-max scaling transformer.

    Note: A transformer to convert numpy arrays to pandas is planned for future releases.

  2. Use contributed causal methods in `causallib.contrib`

    master

    The causallib.contrib module provides experimental implementations of novel causal algorithms. While these models are more experimental and may have less test coverage than the core estimation module, they generally adhere to the standard causallib API (such as IndividualOutcomeEstimator or WeightEstimator).

    Available contributed methods include:

    # Adversarial Balancing
from causallib.contrib.adversarial_balancing import AdversarialBalancing

# HEMM
from causallib.contrib.hemm import HEMM

# Faiss-powered Nearest Neighbors
from causallib.contrib.faissknn import FaissNearestNeighbors

  3. Use `causallib.estimation` for causal effect estimation

    master

    The causallib.estimation module provides tools to estimate counterfactual outcomes and treatment effects. It supports various causal inference methods, each of which can be paired with an underlying machine learning model.

    To use a custom model with these estimators, the model must follow a scikit-learn-like interface:

    • Implement .fit()
    • Implement .predict()
    • Implement .predict_proba() (required for models predicting categorical outcomes).

  4. Install and use causallib for causal inference

    master

    Overview

    causallib is a package designed for estimating causal effects and counterfactual outcomes from observational data.

    Core Paradigm

    • ML-Centric Design: Every causal model uses a machine learning model at its core. You can mix and match different causal models with various machine learning tools by plugging them into the causal model.
    • Scikit-learn Inspired: Causal models follow a design similar to scikit-learn. Once trained, they can be applied to out-of-bag samples.
    • Integrated Evaluation: The library provides performance evaluation schemes that evaluate the underlying machine learning core within a causal inference context.

  5. What is the Heterogeneous Effect Mixture Model (HEMM)?

    master

    The Heterogeneous Effect Mixture Model (HEMM) is a causal inference tool designed for discovering subgroups that exhibit enhanced or diminished treatment effects. It operates within a potential outcomes framework and uses sparsity to maintain interpretability.

    The model consists of two primary components:

    1. Subgroup discovery component: Identifies specific subgroups within the data.
    2. Outcome prediction component: Predicts outcomes based on subgroup assignment and interactions with confounders using a Multi-Layer Perceptron (MLP).

    To better adjust for confounding, the outcome model is extended with neural networks, and a joint inference procedure is used for both the graphical model and the neural networks.

  6. Understand the two-step approach to causal inference

    master

    The package separates the estimation process into two distinct steps:

    1. Potential outcome prediction: Estimating the counterfactual outcomes (what would have happened under different treatment assignments).
    2. Effect estimation: Calculating the causal effect based on the predicted potential outcomes.

    This separation allows for better support of multi-treatment problems where a single 'effect' might not be clearly defined, and it enables users to specify different types of average treatment effects (ATE, ATT, etc.) by choosing how they stratify the data during the outcome prediction step.

  7. How causallib's modular estimator architecture works

    master

    causallib uses a modular design that allows you to mix and match causal estimators with arbitrary machine learning models.

    Key principles:

    • Scikit-Learn Compatibility: Any ML estimator passed to a causal estimator must adhere to the Scikit-Learn fit and predict API. This allows you to use models like XGBoost or Spark as the underlying engines.
    • Thin Wrapper Pattern: causallib often acts as a thin wrapper around statistical estimators, performing the causal logic while the underlying models handle the heavy computational lifting.

    Supported Causal Estimator Types:

    • IPW (Inverse Propensity Weighting): Reweights samples by inverse probability of treatment.
    • Standardization: Direct outcome modeling (e.g., S-Learner, T-Learner).
    • Doubly Robust Methods: Combines propensity and outcome models (e.g., AIPW, TMLE).
    • Meta-Learners: Uses flexible ML models in elaborate ways (e.g., R-Learner, X-Learner).
    • Matching: Finds similar treated and control units.
    • Survival models: Designed for time-to-event data.

  9. Estimate causal effects using the `estimation` module

    master

    The estimation module contains various estimator classes for calculating causal effects. These estimators accept one or more machine learning models that are trained via .fit() and used for prediction via .predict() to estimate outcomes of interest.

    Supported methods include:

    • Inverse Probability Weighting (IPW)
    • Standardization
    • Doubly-robust methods (3 versions available)

  10. Data structure requirements for causallib

    master

    When providing data to causallib estimators, ensure your inputs follow these formats (typically pandas objects):

    VariableDescriptionType
    XCovariates/featurespandas DataFrame
    aTreatment assignmentpandas Series
    yOutcome variablepandas Series
    tOptional time variable (for survival analysis)pandas Series

  11. Weight models vs Direct outcome models

    master

    The package distinguishes between two primary families of causal inference models:

    • Weight models: These models weight the data to balance treatment and control groups, then estimate potential outcomes using a weighted average of observed outcomes. A common example is Inverse Probability of Treatment Weighting (IPW).
    • Direct outcome models: Also known as Standardization models, these use covariates and treatment assignment to build a model that predicts the outcome directly. These models can be used to predict outcomes under any treatment assignment and are currently the only models in the package capable of generating individual effect estimation (Conditional Average Treatment Effect, or CATE).

  12. Estimate ATE and ATT using population outcome estimation

    master

    Because causallib allows for out-of-bag estimation, you can control the population on which the effect is estimated by how you pass data to estimate_population_outcome:

    • Average Treatment Effect (ATE): Estimate the effect on the entire sample by passing the full dataset: model.estimate_population_outcome(X, a).
    • Average Treatment Effect on the Treated (ATT): Estimate the effect by stratifying on the treated group: model.estimate_population_outcome(X.loc[a==1], a.loc[a==1]).