🔬 Uplift Lab: 全栈因果推断与增益模型框架

Uplift Lab 是一个轻量级、原生实现（Built-from-scratch）且完全白盒化的 Uplift Modeling 算法库。

不同于 EconML 或 CausalML 等封装库，本项目旨在解构算法内核。我们不依赖黑盒调用，而是基于 NumPy、Scikit-Learn 和 PyTorch 从底层构建了主流的因果推断模型。这使得研究者和工程师能够完全掌控模型的每一个假设、梯度的流向以及去混杂（De-confounding）的具体细节。

---

🗺️ 覆盖场景与算法矩阵

本项目针对三种不同的**策略变量（Treatment）**类型，提供了对应的解决方案：

场景类型	典型业务	推荐算法	核心机制
二元 (Binary) $T \in {0, 1}$	发券/不发券 流失干预	Meta-Learners (S/T/X) Uplift Forest Class Transformation	差分估计 / 异质性分裂 / 目标变换
多元 (Multi) $T \in {0, 1, ..., K}$	素材优选 多阶梯优惠	Universal Uplift Forest DRNet (Deep Learning)	向量化分裂增益 / Shared-Bottom 多头网络
连续 (Continuous) $T \in \mathbb{R}$	动态定价 精准剂量	DML (Double ML)	正交化去偏 / 残差回归 (R-Learner)

---

🧠 核心方法论与实现逻辑

1. 元学习器 (Meta-Learners)

将因果推断问题分解为标准的监督学习问题。

• S-Learner (Single): 将 $T$ 作为特征输入。 $$\hat{\tau}(x) = \hat{\mu}(x, 1) - \hat{\mu}(x, 0)$$
• T-Learner (Two): 为处理组和对照组分别建立模型。 $$\hat{\tau}(x) = \hat{\mu}_1(x) - \hat{\mu}_0(x)$$
• X-Learner (Cross): [推荐] 专为不平衡数据设计。利用对方的模型预测伪效应 $D$，再加权融合。 $$\hat{\tau}(x) = g(x)\hat{\tau}_0(x) + (1-g(x))\hat{\tau}_1(x)$$

2. 类变换法 (Class Transformation)

通过数学变换，构建一个新的目标变量 $Y^*$，使得回归模型直接预测 CATE。

• 核心公式: $$Y^* = Y \cdot \frac{T - e(x)}{e(x)(1-e(x))}$$ 其中 $e(x)$ 为倾向性得分。
• 实现亮点: 内置了 Propensity Clipping 机制，防止 $e(x) \to 0$ 导致的数值爆炸。

3. 通用 Uplift 树与森林 (Universal Uplift Tree/Forest)

脱离 Sklearn 树结构，手写递归分裂逻辑，直接最大化 CATE 的异质性。

• 分裂准则 (Splitting Criterion): 最大化左右子节点的欧氏范数平方和。 $$Gain = N_L \cdot \sum_{k=1}^K (\tau_{k, L})^2 + N_R \cdot \sum_{k=1}^K (\tau_{k, R})^2$$
• 实现亮点:
  • 全能兼容: 同一套代码无缝支持二元和多元 Treatment。
  • 严格风控: 内置 min_samples_treatment 约束，确保每个叶子节点在所有干预组都有足够样本（满足 Positivity 假设）。

4. 双重机器学习 (DML / R-Learner)

处理连续变量（如价格）的黄金标准。利用 FWL 定理 进行正交化去偏。

• 核心逻辑:
  1. 去偏: $\tilde{Y} = Y - E[Y|X], \quad \tilde{T} = T - E[T|X]$
  2. 因果回归: $\tilde{Y} = \theta(x) \cdot \tilde{T} + \epsilon$
• 实现亮点: 手动实现了 K-Fold Cross-Fitting 循环，防止过拟合带来的因果偏差。

5. 深度学习 DRNet (Shared-Bottom)

适用于大规模数据和 Embedding 特征的神经网络。

• 架构设计:

  graph TD
  A[Input X] --> B[Shared Representation Layers];
  B --> C[Head T=0];
  B --> D[Head T=1];
  B --> E[Head T=...];
  

  Loading
• 损失函数: 最小化与 双重鲁棒 (Doubly Robust) 伪标签 的误差。 $$\hat{Y}_{DR} = \hat{\mu}(x, t) + \frac{Y - \hat{\mu}(x, t)}{\hat{e}(x, t)}$$

---

📂 项目结构

uplift_lab/
├── data/                  # 数据生成器 (含二元/多元/连续场景模拟)
├── models/                # 核心算法实现
│   ├── meta_learners.py   # S/T/X-Learner
│   ├── class_transform.py # Class Transformation
│   ├── tree.py            # Universal Uplift Tree/Forest
│   ├── dml.py             # DML (R-Learner)
│   └── drnet.py           # PyTorch DRNet
├── evaluation.py          # 评估与可视化模块 (AUUC, Policy Value, Dose-Response)
└── examples/
    └── run_demo.py        # 🚀 一键运行综合演示脚本

---

🚀 快速开始 (Quick Start)

1. 环境准备

pip install numpy pandas scikit-learn matplotlib seaborn torch joblib xgboost

2. 运行综合 Demo

我们在 examples/run_demo.py 中提供了一个全流程脚本，自动生成三种类型的模拟数据，训练对应模型，并绘制评估图表。

python examples/run_demo.py

3. 代码调用示例

场景：使用 X-Learner 处理营销发券数据

from xgboost import XGBRegressor, XGBClassifier
from uplift_lab.models.meta_learners import XLearner

# 1. 初始化模型 (注入基模型)
learner = XLearner(
    outcome_learner=XGBRegressor(max_depth=3),
    effect_learner=XGBRegressor(max_depth=3),
    propensity_learner=XGBClassifier()
)

# 2. 训练 (支持观测数据)
learner.fit(X_train, y_train, T_train)

# 3. 预测 Uplift
uplift_pred = learner.predict(X_test)

# 4. 决策
# 对 uplift_pred > 0 的用户发券

场景：使用 DML 处理动态定价数据

from sklearn.ensemble import RandomForestRegressor
from uplift_lab.models.dml import DML_RLearner

# DML 处理连续 Treatment
dml = DML_RLearner(
    model_y=RandomForestRegressor(), # 去除 Y 的混杂
    model_t=RandomForestRegressor(), # 去除 T 的混杂 (价格内生性)
    model_final=RandomForestRegressor(), # 拟合弹性曲线
    discrete_treatment=False
)

dml.fit(X, y, Price)
elasticity = dml.predict(X)

---

📈 评估与可视化

本项目内置了针对观测数据（Observational Data）校正的评估指标：

1. 二元场景:
   • Uplift Curve (AUUC): 累积增益曲线。
   • Decile Chart: 十分位图（业务最爱），展示 Top 10% 人群的真实增益。
2. 多元场景:
   • Expected Policy Value: 策略价值评估。
   • Policy Distribution: 推荐策略分布。
3. 连续场景:
   • Dose-Response Curve: 剂量反应曲线，验证高/低敏感人群的斜率差异。

---

⚠️ 实践注意事项

在使用本库处理实际业务数据时，请务必遵守 因果推断三大公理：

1. 无混杂 (Unconfoundedness): 特征 $X$ 必须包含所有同时影响 $T$ 和 $Y$ 的混杂因子。
2. 正值性 (Positivity): 避免确定性干预。每个用户被干预的概率 $0 < P(T|X) < 1$。
3. 特征选择: 严禁将 干预后变量 (Post-treatment variables) 或 工具变量 (IV) 放入模型特征中，否则会产生严重偏差。

---

🤝 贡献与许可

本项目采用 MIT License 开源。欢迎提交 PR 修复 Bug 或贡献新的算法实现。

---

Made with ❤️ for Causal Inference.