.. -- mode: rst --

|Python3|_ |PyPi|_ |Docs|_ |License|_

.. |Python3| image:: https://img.shields.io/badge/python-3-blue.svg .. _Python3: https://badge.fury.io/py/scikit-uplift

.. |PyPi| image:: https://badge.fury.io/py/scikit-uplift.svg .. _PyPi: https://badge.fury.io/py/scikit-uplift

.. |Docs| image:: https://readthedocs.org/projects/scikit-uplift/badge/?version=latest .. _Docs: https://www.uplift-modeling.com/en/latest/

.. |License| image:: https://img.shields.io/badge/license-MIT-green .. _License: https://github.com/maks-sh/scikit-uplift/blob/master/LICENSE

.. |Open In Colab1| image:: https://colab.research.google.com/assets/colab-badge.svg .. _Open In Colab1: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero_EN.ipynb

.. |Open In Colab2| image:: https://colab.research.google.com/assets/colab-badge.svg .. _Open In Colab2: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero.ipynb

.. |Open In Colab3| image:: https://colab.research.google.com/assets/colab-badge.svg .. _Open In Colab3: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/pipeline_usage_EN.ipynb

.. |Open In Colab4| image:: https://colab.research.google.com/assets/colab-badge.svg .. _Open In Colab4: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/pipeline_usage_RU.ipynb

.. _uplift-modeling.com: https://www.uplift-modeling.com/en/latest/

.. image:: https://raw.githubusercontent.com/maks-sh/scikit-uplift/dev/docs/_static/sklift-github-logo.png :align: center :alt: scikit-uplift: uplift modeling in scikit-learn style in python

.. |Contribs| image:: https://contrib.rocks/image?repo=maks-sh/scikit-uplift :target: https://github.com/maks-sh/scikit-uplift/graphs/contributors :alt: Contributors

scikit-uplift

scikit-uplift (sklift) 是一个用于提升建模的 Python 软件包，提供了快速的、类似 scikit-learn 的模型实现、评估指标和可视化工具。

提升建模用于估计干预措施的因果效应，并利用这一效应来有效定位最有可能对营销活动做出响应的客户。

提升建模的应用场景：

• 在营销活动中精准定位目标客户。这在推广某些热门产品时非常有用，因为其中很大一部分客户即使没有受到任何影响也会自行采取目标行动。通过提升建模，您可以找到那些只有在接受干预（例如收到推送通知）时才可能采取目标行动（如安装应用）的客户。

• 将流失模型与提升模型结合，向可能流失的客户群体提供奖励。

• 在单个客户成本较高的营销活动中，选择一小部分目标客户。

更多关于提升建模的问题，请参阅 用户指南 <https://www.uplift-modeling.com/en/latest/user_guide/index.html>__。

俄语文章发表于 habr.com：第一部分 <https://habr.com/ru/company/ru_mts/blog/485980/>， 第二部分 <https://habr.com/ru/company/ru_mts/blog/485976/> 以及 第三部分 <https://habr.com/ru/company/ru_mts/blog/538934/>__。

为什么选择 sklift

• 舒适且直观的类 scikit-learn API；

• 汇集了前所未有的丰富提升模型评估指标！包括像“提升曲线下面积”（AUUC）或“Qini 曲线下面积”（Qini 系数）这样在理想情况下表现优异的指标；

• 支持所有与 scikit-learn 兼容的估计器（例如 Xgboost、LightGBM、Catboost 等）；

• 所有方法都可以集成到 sklearn.pipeline 中。请参阅 教程页面 <https://www.uplift-modeling.com/en/latest/tutorials.html>__ 上的使用示例；

• 评估指标也与 sklearn.model_selection 中的类兼容。请参阅 教程页面 <https://www.uplift-modeling.com/en/latest/tutorials.html>__ 上的使用示例；

• 几乎所有实现的方法都能解决分类和回归问题；

• 提供美观且实用的可视化工具，便于分析模型性能。

安装

从 PyPI 安装该软件包，只需执行以下命令：

.. code-block:: bash

pip install scikit-uplift

或者从源代码安装：

.. code-block:: bash

git clone https://github.com/maks-sh/scikit-uplift.git
cd scikit-uplift
python setup.py install

文档

完整的文档可在 uplift-modeling.com_ 上查阅。

您也可以使用 Sphinx <http://sphinx-doc.org/>_ 1.4 或更高版本在本地构建文档：

.. code-block:: bash

cd docs
pip install -r requirements.txt
make html

然后在浏览器中打开 _build/html/index.html，您将看到文档站点。

快速入门

有关详细信息，请参阅 RetailHero 教程笔记本（英文版 <https://nbviewer.jupyter.org/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero_EN.ipynb>__ |Open In Colab1|，俄文版 <https://nbviewer.jupyter.org/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero.ipynb>_ |Open In Colab2|_)。

训练并预测提升模型

使用直观的 Python API，借助 sklift.models <https://www.uplift-modeling.com/en/latest/api/models/index.html>__ 训练提升模型。

.. code-block:: python

# 导入方法
from sklift.models import SoloModel, ClassTransformation
# 导入任何符合 scikit-learn 规范的估计器。
from lightgbm import LGBMClassifier

# 定义模型
estimator = LGBMClassifier(n_estimators=10)

# 定义元模型
slearner = SoloModel(estimator=estimator)

# 拟合模型
slearner.fit(
    X=X_tr,
    y=y_tr,
    treatment=trmnt_tr,
)

# 预测提升值
uplift_slearner = slearner.predict(X_val)

评估您的提升模型

提升模型的评估指标可在 sklift.metrics <https://www.uplift-modeling.com/en/latest/api/metrics/index.html>__ 中找到。

.. code-block:: python

# 导入用于评估模型的指标
from sklift.metrics import (
    uplift_at_k, uplift_auc_score, qini_auc_score, weighted_average_uplift
)


# Uplift@30%
uplift_at_k = uplift_at_k(y_true=y_val, uplift=uplift_slearner,
                          treatment=trmnt_val,
                          strategy='overall', k=0.3)

# Qini 曲线下面积
qini_coef = qini_auc_score(y_true=y_val, uplift=uplift_slearner,
                           treatment=trmnt_val)

# 提升曲线下面积
uplift_auc = uplift_auc_score(y_true=y_val, uplift=uplift_slearner,
                              treatment=trmnt_val)

# 加权平均提升值
wau = weighted_average_uplift(y_true=y_val, uplift=uplift_slearner,
                              treatment=trmnt_val)

可视化结果

使用 sklift.viz <https://www.uplift-modeling.com/en/latest/api/viz/index.html>__ 可视化性能指标。

.. code-block:: python

from sklift.viz import plot_qini_curve import matplotlib.pyplot as plt

fig, ax = plt.subplots(1, 1)
ax.set_title('Qini曲线')

plot_qini_curve(
    y_test, uplift_slearner, trmnt_test,
    perfect=True, name='Slearner', ax=ax
);

plot_qini_curve(
    y_test, uplift_revert, trmnt_test,
    perfect=False, name='Revert label', ax=ax
);

.. image:: docs/_static/images/quick_start_qini.png :width: 514px :height: 400px :alt: 某些模型的Qini曲线示例，包括完美Qini曲线和随机Qini曲线

开发

我们欢迎所有经验水平的新贡献者。

• 请参阅我们的《贡献指南》以获取更多详细信息：Contributing Guide <https://www.uplift-modeling.com/en/latest/contributing.html>_。
• 参与本项目即表示您同意遵守其《行为准则》：Code of Conduct <https://github.com/maks-sh/scikit-uplift/blob/master/.github/CODE_OF_CONDUCT.md>__。

感谢所有贡献者！

|Contribs|

如果您有任何问题，请通过 team@uplift-modeling.com 联系我们。

重要链接

- 官方源代码仓库：https://github.com/maks-sh/scikit-uplift/
- 问题跟踪器：https://github.com/maks-sh/scikit-uplift/issues
- 文档：https://www.uplift-modeling.com/en/latest/
- 用户指南：https://www.uplift-modeling.com/en/latest/user_guide/index.html
- 贡献指南：https://www.uplift-modeling.com/en/latest/contributing.html
- 发布历史：https://www.uplift-modeling.com/en/latest/changelog.html

===============

论文与资料
---------------------
1. Gutierrez, P., & Gérardy, J. Y.
	因果推断与Uplift建模：文献综述。
	载于国际预测应用与API会议论文集（第1–13页）。

2. Artem Betlei, Criteo Research；Eustache Diemert, Criteo Research；Massih-Reza Amini, 格勒诺布尔-阿尔卑斯大学
	依赖与共享数据表示在不平衡治疗条件下的Uplift预测改进
	FAIM'18因果机器学习研讨会。

3. Eustache Diemert、Artem Betlei、Christophe Renaudin 和 Massih-Reza Amini. 2018.
    Uplift建模的大规模基准测试。
    载于AdKDD & TargetAd (ADKDD’18)会议论文集。ACM，纽约，纽约州，美国，6页。

4. Athey, Susan, 和 Imbens, Guido. 2015.
    用于估计异质性因果效应的机器学习方法。
    预印本，arXiv:1504.01132。Google Scholar。

5. Oscar Mesalles Naranjo. 2012.
    测试Uplift模型的新指标。
    提交给统计学与运筹学硕士学位的论文。

6. Kane, K., V. S. Y. Lo, 和 J. Zheng. 2014.
    利用True-Lift建模挖掘真正响应的客户与潜在客户：
    新旧方法比较。
    市场营销分析期刊 2 (4): 218–238。

7. Maciej Jaskowski 和 Szymon Jaroszewicz.
    临床试验数据的Uplift建模。
    ICML临床数据分析研讨会，2012年。

8. Lo, Victor. 2002.
    True Lift模型——数据库营销中响应建模的一种新颖数据挖掘方法。
    SIGKDD Explorations. 4. 78-86。

9. Zhao, Yan、Fang, Xiao 和 Simchi-Levi, David. 2017.
    多重处理与一般响应类型的Uplift建模。10.1137/1.9781611974973.66。

10. Nicholas J Radcliffe. 2007.
	利用对照组基于预测提升进行目标营销：Uplift模型的构建与评估。直接营销分析期刊，(3):14–21，2007年。

11. Devriendt, F., Guns, T., 和 Verbeke, W. 2020.
	用于Uplift建模的排序学习。ArXiv，abs/2002.05897。

===============

标签

EN: uplift modeling, uplift modelling, causal inference, causal effect, causality, individual treatment effect, true lift, net lift, incremental modeling

RU: аплифт моделирование, Uplift модель

ZH: uplift增量建模, 因果推断, 因果效应, 因果关系, 个体干预因果效应, 真实增量, 净增量, 增量建模

scikit-uplift 快速上手指南

scikit-uplift (sklift) 是一个用于增量建模（Uplift Modeling）的 Python 库。它提供了类似 scikit-learn 风格的 API，用于估算干预措施（如营销活动）的因果效应，帮助开发者精准定位那些“只有受到干预才会产生目标行为”的用户。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.6 及以上版本
• 前置依赖：
  • scikit-learn
  • numpy
  • pandas
  • matplotlib (用于可视化)
  • 可选基学习器：如 lightgbm, xgboost, catboost 等（sklift 支持任何兼容 scikit-learn 接口的估计器）

建议先更新基础包以确保兼容性：

pip install --upgrade pip setuptools wheel

2. 安装步骤

您可以通过 PyPI 直接安装稳定版，这是最推荐的方式。

方式一：通过 PyPI 安装（推荐）

pip install scikit-uplift

国内加速提示：如果您在中国大陆地区，建议使用清华或阿里镜像源以加快下载速度：

pip install scikit-uplift -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

如果您需要最新的功能或参与开发，可以从 GitHub 克隆源码进行安装：

git clone https://github.com/maks-sh/scikit-uplift.git
cd scikit-uplift
python setup.py install

3. 基本使用

sklift 的核心工作流与 scikit-learn 高度一致：定义模型 -> 拟合数据 -> 预测增量 -> 评估指标。

以下是一个基于 LightGBM 作为基学习器的最小化示例：

3.1 训练与预测

# 导入 sklift 模型和任意兼容 scikit-learn 的估计器
from sklift.models import SoloModel
from lightgbm import LGBMClassifier

# 假设您已经有了特征矩阵 X_tr, 标签 y_tr, 以及干预标记 trmnt_tr (0 或 1)
# X_tr: 特征数据
# y_tr: 目标变量 (如是否购买)
# trmnt_tr: 干预组标记 (1=实验组，0=对照组)

# 1. 定义基学习器
estimator = LGBMClassifier(n_estimators=10, random_state=42)

# 2. 定义增量模型 (这里使用 S-Learner 方法)
slearner = SoloModel(estimator=estimator)

# 3. 拟合模型
# 注意：fit 方法需要额外传入 treatment 参数
slearner.fit(
    X=X_tr,
    y=y_tr,
    treatment=trmnt_tr,
)

# 4. 预测增量分数
uplift_scores = slearner.predict(X_val)

3.2 模型评估

sklift 提供了多种专用的增量评估指标，如 Qini 系数、AUUC 等。

from sklift.metrics import uplift_at_k, qini_auc_score, uplift_auc_score

# 计算前 30% 用户的增量效果 (Uplift@30%)
u_at_k = uplift_at_k(
    y_true=y_val, 
    uplift=uplift_scores,
    treatment=trmnt_val,
    strategy='overall', 
    k=0.3
)

# 计算 Qini 曲线下的面积 (Qini Coefficient)
qini_coef = qini_auc_score(
    y_true=y_val, 
    uplift=uplift_scores,
    treatment=trmnt_val
)

# 计算 Uplift 曲线下的面积 (AUUC)
auuc_score = uplift_auc_score(
    y_true=y_val, 
    uplift=uplift_scores,
    treatment=trmnt_val
)

print(f"Uplift@30%: {u_at_k}")
print(f"Qini Coefficient: {qini_coef}")

3.3 结果可视化

使用内置工具绘制 Qini 曲线以直观展示模型性能。

from sklift.viz import plot_qini_curve
import matplotlib.pyplot as plt

plt.figure(figsize=(8, 6))
plot_qini_curve(
    y_true=y_val, 
    uplift=uplift_scores, 
    treatment=trmnt_val,
    perfect=True,  # 是否绘制理想曲线
    name='S-Learner Model'
)
plt.title('Qini Curve')
plt.show()

---

更多详细教程和 API 文档请访问：https://www.uplift-modeling.com