How ayushd64/causal-inference-engine works
1. Repository shape
- This is a notebook-first analytics repo, not a multi-service application.
- The core executable artifact is criteo_causal_analysis.ipynb; the rest is metadata (README.md, requirements.txt, .gitignore).
2. Primary purpose
- The notebook implements an end-to-end causal uplift workflow for the Criteo Uplift Benchmark dataset.
- The goal is to estimate incremental treatment effect and convert it into a cost-aware targeting policy.
3. Input boundary
- External input is the Criteo uplift dataset, likely loaded and transformed inside the notebook.
- The data boundary is the user-level table containing:
- observed features f₀–f₁₁
- treatment assignment
- conversion outcome
- validation/analysis slices
4. Causal modeling subsystem
- The first major subsystem is structural causal analysis.
- It uses a causal graph / backdoor adjustment framing to control for confounding and estimate an average treatment effect.
- This is the repository’s “identification” layer: it distinguishes causal effect from correlation.
5. Refutation / robustness subsystem
- A second subsystem performs DoWhy-style refutation tests.
- The README specifically highlights a Random Common Cause Refuter, used to test whether the causal estimate changes under irrelevant-noise injection.
- Architecturally, this is a validation boundary around the causal estimate, not a modeling step that drives decisions.
6. Heterogeneous treatment effect subsystem
- The uplift modeling layer uses meta-learners:
- T-Learner
- X-Learner
- These are backed by LightGBM, with GPU acceleration mentioned in the design.
- This subsystem produces per-user treatment response scores rather than a single global effect.
7. Multi-treatment decision layer
- The notebook does not stop at uplift prediction; it maps uplift into treatment-specific decisions.
- Two treatment channels are modeled:
- Discount Banner
- Premium Video Ad
- The output is a multi-action assignment rather than binary treat/control classification.
8. Economic optimization boundary
- A distinct policy layer computes Net Expected Value (NEV):
- expected revenue from uplift
- minus treatment delivery cost
- This turns model outputs into an operational decision:
- target with Channel A
- target with Channel B
- or do not target
- This is the business-rule boundary that prevents positive-uplift but negative-profit actions.
9. Output artifacts
- The notebook appears to generate:
- an ATE estimate
- refutation results / p-values
- user-level uplift and NEV tables
- an optimal action allocation summary
- visualizations for analysis
- There is no indication of a deployed API, batch job framework, or persistent model registry in this repo.
10. Technology stack and runtime
- The architecture relies on Python scientific ML tooling:
- DoWhy for causal identification and refutation
- CausalML for uplift/meta-learning
- LightGBM and scikit-learn for estimators
- NumPy / Pandas for data prep
- Matplotlib / Seaborn for plotting
- The mention of GPU acceleration matters only for the training/estimation layer.
11. System-level data flow
- The high-level flow is:
- load Criteo data
- define causal structure and adjustment set
- estimate causal effect
- refute/stress-test estimate
- train uplift models for each treatment
- score users with uplift
- apply NEV rules to select actions
- summarize allocation and impact
12. Architectural takeaway
- This repo is best diagrammed as a single analytical pipeline with four clear boundaries:
- data ingestion
- causal inference
- uplift prediction
- economic policy selection
- The notebook orchestrates all stages; there are no separate microservices, databases, or production deployment components visible in the repository.
Main entry points: criteo_causal_analysis.ipynb Notebook
Components 16
Notebook Pipeline
Single notebook that orchestrates the full analysis flow.
- Notebook · Main executable analysis notebook.
criteo_causal_analysis.ipynb - Criteo Data · Criteo uplift benchmark with features, treatment, and outcome.
- Prep · Loads and reshapes user-level analysis slices and features.
Causal Inference
Identification, estimation, and robustness checks for treatment effect.
- Causal Graph · Defines causal structure and backdoor adjustment set.
- Backdoor Adj. · Controls confounding for causal effect estimation.
- ATE · Global average treatment effect estimate.
- Refuter · Random common cause refutation of the causal estimate.
- Validation · Interprets refutation stability and significance.
Uplift Modeling
Heterogeneous treatment effect modeling for multiple actions.
- T-Learner · Meta-learner for per-user treatment response.
- X-Learner · Meta-learner for heterogeneous uplift estimation.
- LightGBM · Tree-based learner used for uplift submodels.
- Uplift Scores · User-level treatment response scores.
Policy & Outputs
Economic decision layer and analysis artifacts.
- NEV · Net expected value from uplift minus treatment cost.
- Action Mix · Selects discount, video ad, or no target.
- Summary · Allocation summary and impact readout.
- Plots · Notebook charts for analysis and comparison.
Connections 20
- Notebook → Criteo Data: loads · Notebook ingests the benchmark dataset.
- Criteo Data → Prep: transforms · Raw records are prepared for analysis.
- Prep → Causal Graph: defines · Prepared data supports causal structure definition.
- Causal Graph → Backdoor Adj.: guides · Graph implies adjustment set.
- Backdoor Adj. → ATE: estimates · Backdoor adjustment produces ATE.
- ATE → Refuter: tests · ATE is stress-tested with refutation.
- Refuter → Validation: reports · Refutation output is interpreted for stability.
- Prep → T-Learner: feeds · Features and labels train the T-Learner.
- Prep → X-Learner: feeds · Features and labels train the X-Learner.
- T-Learner → LightGBM: uses · T-Learner relies on LightGBM base estimators.
- X-Learner → LightGBM: uses · X-Learner relies on LightGBM base estimators.
- T-Learner → Uplift Scores: predicts · T-Learner emits uplift scores.
- X-Learner → Uplift Scores: predicts · X-Learner emits uplift scores.
- Uplift Scores → NEV: values · Uplift scores are translated into economic value.
- NEV → Action Mix: selects · NEV chooses the best action per user.
- Action Mix → Summary: summarizes · Policy outputs are aggregated into a summary.
- ATE → Summary: includes · Global causal estimate is reported alongside policy results.
- Validation → Summary: includes · Refutation results are included in reporting.
- Uplift Scores → Plots: visualized · Uplift distributions and comparisons are plotted.
- NEV → Plots: visualized · Economic decisions are visualized for analysis.