scikit-uplift 0.5.1

Why sklift

• Сomfortable and intuitive scikit-learn-like API;

• More uplift metrics than you have ever seen in one place! Include brilliants like Area Under Uplift Curve (AUUC) or Area Under Qini Curve (Qini coefficient) with ideal cases;

• Supporting any estimator compatible with scikit-learn (e.g. Xgboost, LightGBM, Catboost, etc.);

• All approaches can be used in the sklearn.pipeline. See the example of usage on the Tutorials page;

• Also metrics are compatible with the classes from sklearn.model_selection. See the example of usage on the Tutorials page;

• Almost all implemented approaches solve classification and regression problems;

• Nice and useful viz for analysing a performance model.

Installation

Install the package by the following command from PyPI:

pip install scikit-uplift

Or install from source:

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

Documentation

The full documentation is available at uplift-modeling.com.

Or you can build the documentation locally using Sphinx 1.4 or later:

cd docs
pip install -r requirements.txt
make html

And if you now point your browser to _build/html/index.html, you should see a documentation site.

Quick Start

See the RetailHero tutorial notebook (EN , RU ) for details.

Train and predict uplift model

Use the intuitive python API to train uplift models with sklift.models.

# import approaches
from sklift.models import SoloModel, ClassTransformation
# import any estimator adheres to scikit-learn conventions.
from lightgbm import LGBMClassifier

# define models
estimator = LGBMClassifier(n_estimators=10)

# define metamodel
slearner = SoloModel(estimator=estimator)

# fit model
slearner.fit(
    X=X_tr,
    y=y_tr,
    treatment=trmnt_tr,
)

# predict uplift
uplift_slearner = slearner.predict(X_val)

Evaluate your uplift model

Uplift model evaluation metrics are available in sklift.metrics.

# import metrics to evaluate your model
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)

# Area Under Qini Curve
qini_coef = qini_auc_score(y_true=y_val, uplift=uplift_slearner,
                           treatment=trmnt_val)

# Area Under Uplift Curve
uplift_auc = uplift_auc_score(y_true=y_val, uplift=uplift_slearner,
                              treatment=trmnt_val)

# Weighted average uplift
wau = weighted_average_uplift(y_true=y_val, uplift=uplift_slearner,
                              treatment=trmnt_val)

Vizualize the results

Visualize performance metrics with sklift.viz.

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

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

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
);

Development

We welcome new contributors of all experience levels.

• Please see our Contributing Guide for more details.

• By participating in this project, you agree to abide by its Code of Conduct.

Thanks to all our contributors!

If you have any questions, please contact us at team@uplift-modeling.com

Papers and materials

1. Gutierrez, P., & Gérardy, J. Y.

   Causal Inference and Uplift Modelling: A Review of the Literature. In International Conference on Predictive Applications and APIs (pp. 1-13).

2. Artem Betlei, Criteo Research; Eustache Diemert, Criteo Research; Massih-Reza Amini, Univ. Grenoble Alpes

   Dependent and Shared Data Representations improve Uplift Prediction in Imbalanced Treatment Conditions FAIM’18 Workshop on CausalML.

3. Eustache Diemert, Artem Betlei, Christophe Renaudin, and Massih-Reza Amini. 2018.

   A Large Scale Benchmark for Uplift Modeling. In Proceedings of AdKDD & TargetAd (ADKDD’18). ACM, New York, NY, USA, 6 pages.

4. Athey, Susan, and Imbens, Guido. 2015.

   Machine learning methods for estimating heterogeneous causal effects. Preprint, arXiv:1504.01132. Google Scholar.

5. Oscar Mesalles Naranjo. 2012.

   Testing a New Metric for Uplift Models. Dissertation Presented for the Degree of MSc in Statistics and Operational Research.

6. Kane, K., V. S. Y. Lo, and J. Zheng. 2014.

   Mining for the Truly Responsive Customers and Prospects Using True-Lift Modeling: Comparison of New and Existing Methods. Journal of Marketing Analytics 2 (4): 218–238.

7. Maciej Jaskowski and Szymon Jaroszewicz.

   Uplift modeling for clinical trial data. ICML Workshop on Clinical Data Analysis, 2012.

8. Lo, Victor. 2002.

   The True Lift Model - A Novel Data Mining Approach to Response Modeling in Database Marketing. SIGKDD Explorations. 4. 78-86.

9. Zhao, Yan & Fang, Xiao & Simchi-Levi, David. 2017.

   Uplift Modeling with Multiple Treatments and General Response Types. 10.1137/1.9781611974973.66.

10. Nicholas J Radcliffe. 2007.

    Using control groups to target on predicted lift: Building and assessing uplift model. Direct Marketing Analytics Journal, (3):14–21, 2007.

11. Devriendt, F., Guns, T., & Verbeke, W. 2020.

    Learning to rank for uplift modeling. ArXiv, abs/2002.05897.