scikit-uplift 0.0.3

Classic approaches of Uplift modelling in scikit-learn style in python

scikit-uplift

scikit-uplift is a Python module for classic approaches for uplift modelling built on top of scikit-learn.

Features:

• Comfortable and intuitive style of modelling like scikit-learn;
• Applying any estimator adheres to scikit-learn conventions;
• A lot of metrics (Such as Area Under Uplift Curve or Area Under Qini Curve) are implemented to evaluate your uplift model.

Installation

Install the package by the following command:

pip install scikit-uplift

Documentation

The full documentation is available at scikit-uplift.readthedocs.io.

Quick Start

See the RetailHero tutorial notebook for details.

Train and predict uplift model

# import approaches
from sklift.models import SoloModel, ClassTransformation, TwoModels
# import any estimator adheres to scikit-learn conventions.
from catboost import CatBoostClassifier

# define approach
sm = SoloModel(CatBoostClassifier(verbose=100, random_state=777))
# fit model
sm = sm.fit(X_train, y_train, treat_train, estimator_fit_params={{'plot': True})

# predict uplift
uplift_sm = sm.predict(X_val)

Evaluate your uplift model

# import metrics to evaluate your model
from sklift.metrics import auqc, auuc, uplift_at_k

# Uplift@30%
sm_uplift_at_k = uplift_at_k(y_true=y_val, uplift=uplift_sm, treatment=treat_val, k=0.3)
# Area Under Qini Curve
sm_auqc = auqc(y_true=y_val, uplift=uplift_sm, treatment=treat_val)
# Area Under Uplift Curve
sm_auuc = auuc(y_true=y_val, uplift=uplift_sm, treatment=treat_val)

Vizualize the results

# import vizualisation tools
from sklift.viz import plot_uplift_probs, plot_uplift_qini_curves

# get conditional probabilities of performing a target action
# with interaction for each object
sm_trmnt_proba = sm.trmnt_proba_
# get conditional probabilities of performing a target action
# without interaction for each object
sm_ctrl_proba = sm.ctrl_proba_

# draw probability distributions and their difference (uplift)
plot_uplift_probs(trmnt_proba=sm_trmnt_proba, ctrl_proba=sm_ctrl_proba);

# draw Uplift and Qini curves
plot_uplift_qini_curves(y_true=y_val, uplift=uplift_sm, treatment=treat_val);

Development

We welcome new contributors of all experience levels.

Important links

• Official source code repo: https://github.com/maks-sh/scikit-uplift/
• Issue tracker: https://github.com/maks-sh/scikit-uplift/issues

---

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.