{"id":13710159,"url":"https://github.com/maks-sh/scikit-uplift","last_synced_at":"2025-05-06T18:34:27.823Z","repository":{"id":37333808,"uuid":"229347545","full_name":"maks-sh/scikit-uplift","owner":"maks-sh","description":":exclamation: uplift modeling in scikit-learn style in python :snake:","archived":false,"fork":false,"pushed_at":"2023-10-21T16:05:46.000Z","size":8165,"stargazers_count":732,"open_issues_count":32,"forks_count":98,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-11-07T12:48:28.743Z","etag":null,"topics":["causal-inference","causality","individual-treatment-effects","machine-learning","net-lift","true-lift","uplift","uplift-modeling","uplift-modelling"],"latest_commit_sha":null,"homepage":"https://www.uplift-modeling.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maks-sh.png","metadata":{"files":{"readme":"Readme.rst","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-20T22:51:58.000Z","updated_at":"2024-11-03T05:08:26.000Z","dependencies_parsed_at":"2022-07-12T16:17:32.097Z","dependency_job_id":"31865642-09cc-42df-9434-c7ed31d357c8","html_url":"https://github.com/maks-sh/scikit-uplift","commit_stats":{"total_commits":280,"total_committers":27,"mean_commits":10.37037037037037,"dds":0.3035714285714286,"last_synced_commit":"0038e659428f6e7a49b935b850651cd9a9db3f54"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maks-sh%2Fscikit-uplift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maks-sh%2Fscikit-uplift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maks-sh%2Fscikit-uplift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maks-sh%2Fscikit-uplift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maks-sh","download_url":"https://codeload.github.com/maks-sh/scikit-uplift/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224521594,"owners_count":17325262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["causal-inference","causality","individual-treatment-effects","machine-learning","net-lift","true-lift","uplift","uplift-modeling","uplift-modelling"],"created_at":"2024-08-02T23:00:52.528Z","updated_at":"2024-11-13T20:31:21.969Z","avatar_url":"https://github.com/maks-sh.png","language":"Python","funding_links":[],"categories":["Causal Inference","Tools"],"sub_categories":["Uplift Evaluation"],"readme":".. -*- mode: rst -*-\n\n|Python3|_ |PyPi|_ |Docs|_ |License|_\n\n.. |Python3| image:: https://img.shields.io/badge/python-3-blue.svg\n.. _Python3: https://badge.fury.io/py/scikit-uplift\n\n.. |PyPi| image:: https://badge.fury.io/py/scikit-uplift.svg\n.. _PyPi: https://badge.fury.io/py/scikit-uplift\n\n.. |Docs| image:: https://readthedocs.org/projects/scikit-uplift/badge/?version=latest\n.. _Docs: https://www.uplift-modeling.com/en/latest/\n\n.. |License| image:: https://img.shields.io/badge/license-MIT-green\n.. _License: https://github.com/maks-sh/scikit-uplift/blob/master/LICENSE\n\n.. |Open In Colab1| image:: https://colab.research.google.com/assets/colab-badge.svg\n.. _Open In Colab1: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero_EN.ipynb\n\n.. |Open In Colab2| image:: https://colab.research.google.com/assets/colab-badge.svg\n.. _Open In Colab2: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero.ipynb\n\n.. |Open In Colab3| image:: https://colab.research.google.com/assets/colab-badge.svg\n.. _Open In Colab3: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/pipeline_usage_EN.ipynb\n\n.. |Open In Colab4| image:: https://colab.research.google.com/assets/colab-badge.svg\n.. _Open In Colab4: https://colab.research.google.com/github/maks-sh/scikit-uplift/blob/master/notebooks/pipeline_usage_RU.ipynb\n\n.. _uplift-modeling.com: https://www.uplift-modeling.com/en/latest/\n\n.. image:: https://raw.githubusercontent.com/maks-sh/scikit-uplift/dev/docs/_static/sklift-github-logo.png\n    :align: center\n    :alt: scikit-uplift: uplift modeling in scikit-learn style in python\n\n.. |Contribs| image:: https://contrib.rocks/image?repo=maks-sh/scikit-uplift\n   :target: https://github.com/maks-sh/scikit-uplift/graphs/contributors\n   :alt: Contributors\n\nscikit-uplift\n===============\n\n**scikit-uplift (sklift)** is an uplift modeling python package that provides fast sklearn-style models implementation, evaluation metrics and visualization tools.\n\nUplift modeling estimates a causal effect of treatment and uses it to effectively target customers that are most likely to respond to a marketing campaign.\n\n**Use cases for uplift modeling:**\n\n* Target customers in the marketing campaign. Quite useful in promotion of some popular product where there is a big part of customers who make a target action by themself without any influence. By modeling uplift you can find customers who are likely to make the target action (for instance, install an app) only when treated (for instance, received a push).\n\n* Combine a churn model and an uplift model to offer some bonus to a group of customers who are likely to churn.\n\n* Select a tiny group of customers in the campaign where a price per customer is high.\n\nRead more about uplift modeling problem in `User Guide \u003chttps://www.uplift-modeling.com/en/latest/user_guide/index.html\u003e`__.\n\nArticles in russian on habr.com: `Part 1 \u003chttps://habr.com/ru/company/ru_mts/blog/485980/\u003e`__ ,\n`Part 2 \u003chttps://habr.com/ru/company/ru_mts/blog/485976/\u003e`__\nand `Part 3 \u003chttps://habr.com/ru/company/ru_mts/blog/538934/\u003e`__.\n\nWhy sklift\n-------------\n\n- Сomfortable and intuitive *scikit-learn*-like API;\n\n- 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;\n\n- Supporting any estimator compatible with scikit-learn (e.g. Xgboost, LightGBM, Catboost, etc.);\n\n- All approaches can be used in the ``sklearn.pipeline``. See the example of usage on `the Tutorials page \u003chttps://www.uplift-modeling.com/en/latest/tutorials.html\u003e`__;\n\n- Also metrics are compatible with the classes from ``sklearn.model_selection``. See the example of usage on `the Tutorials page \u003chttps://www.uplift-modeling.com/en/latest/tutorials.html\u003e`__;\n\n- Almost all implemented approaches solve classification and regression problems;\n\n- Nice and useful viz for analysing a performance model.\n\nInstallation\n-------------\n\n**Install** the package by the following command from PyPI:\n\n.. code-block:: bash\n\n    pip install scikit-uplift\n\nOr install from source:\n\n.. code-block:: bash\n\n    git clone https://github.com/maks-sh/scikit-uplift.git\n    cd scikit-uplift\n    python setup.py install\n\nDocumentation\n--------------\n\nThe full documentation is available at `uplift-modeling.com`_.\n\nOr you can build the documentation locally using `Sphinx \u003chttp://sphinx-doc.org/\u003e`_ 1.4 or later:\n\n.. code-block:: bash\n\n    cd docs\n    pip install -r requirements.txt\n    make html\n\nAnd if you now point your browser to ``_build/html/index.html``, you should see a documentation site.\n\nQuick Start\n-----------\n\nSee the **RetailHero tutorial notebook** (`EN \u003chttps://nbviewer.jupyter.org/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero_EN.ipynb\u003e`__ |Open In Colab1|_, `RU \u003chttps://nbviewer.jupyter.org/github/maks-sh/scikit-uplift/blob/master/notebooks/RetailHero.ipynb\u003e`__ |Open In Colab2|_) for details.\n\n**Train and predict uplift model**\n\nUse the intuitive python API to train uplift models with `sklift.models  \u003chttps://www.uplift-modeling.com/en/latest/api/models/index.html\u003e`__.\n\n.. code-block:: python\n\n    # import approaches\n    from sklift.models import SoloModel, ClassTransformation\n    # import any estimator adheres to scikit-learn conventions.\n    from lightgbm import LGBMClassifier\n\n    # define models\n    estimator = LGBMClassifier(n_estimators=10)\n\n    # define metamodel\n    slearner = SoloModel(estimator=estimator)\n\n    # fit model\n    slearner.fit(\n        X=X_tr,\n        y=y_tr,\n        treatment=trmnt_tr,\n    )\n\n    # predict uplift\n    uplift_slearner = slearner.predict(X_val)\n\n**Evaluate your uplift model**\n\nUplift model evaluation metrics are available in `sklift.metrics  \u003chttps://www.uplift-modeling.com/en/latest/api/metrics/index.html\u003e`__.\n\n.. code-block:: python\n\n    # import metrics to evaluate your model\n    from sklift.metrics import (\n        uplift_at_k, uplift_auc_score, qini_auc_score, weighted_average_uplift\n    )\n\n\n    # Uplift@30%\n    uplift_at_k = uplift_at_k(y_true=y_val, uplift=uplift_slearner,\n                              treatment=trmnt_val,\n                              strategy='overall', k=0.3)\n\n    # Area Under Qini Curve\n    qini_coef = qini_auc_score(y_true=y_val, uplift=uplift_slearner,\n                               treatment=trmnt_val)\n\n    # Area Under Uplift Curve\n    uplift_auc = uplift_auc_score(y_true=y_val, uplift=uplift_slearner,\n                                  treatment=trmnt_val)\n\n    # Weighted average uplift\n    wau = weighted_average_uplift(y_true=y_val, uplift=uplift_slearner,\n                                  treatment=trmnt_val)\n\n**Vizualize the results**\n\nVisualize performance metrics with `sklift.viz  \u003chttps://www.uplift-modeling.com/en/latest/api/viz/index.html\u003e`__.\n\n.. code-block:: python\n\n    from sklift.viz import plot_qini_curve\n    import matplotlib.pyplot as plt\n\n    fig, ax = plt.subplots(1, 1)\n    ax.set_title('Qini curves')\n\n    plot_qini_curve(\n        y_test, uplift_slearner, trmnt_test,\n        perfect=True, name='Slearner', ax=ax\n    );\n\n    plot_qini_curve(\n        y_test, uplift_revert, trmnt_test,\n        perfect=False, name='Revert label', ax=ax\n    );\n\n.. image:: docs/_static/images/quick_start_qini.png\n    :width: 514px\n    :height: 400px\n    :alt: Example of some models qini curves, perfect qini curve and random qini curve\n\nDevelopment\n-----------\n\nWe welcome new contributors of all experience levels.\n\n- Please see our `Contributing Guide \u003chttps://www.uplift-modeling.com/en/latest/contributing.html\u003e`_ for more details.\n- By participating in this project, you agree to abide by its `Code of Conduct \u003chttps://github.com/maks-sh/scikit-uplift/blob/master/.github/CODE_OF_CONDUCT.md\u003e`__.\n\nThanks to all our contributors!\n\n|Contribs|\n\nIf you have any questions, please contact us at team@uplift-modeling.com\n\nImportant links\n~~~~~~~~~~~~~~~\n\n- Official source code repo: https://github.com/maks-sh/scikit-uplift/\n- Issue tracker: https://github.com/maks-sh/scikit-uplift/issues\n- Documentation: https://www.uplift-modeling.com/en/latest/\n- User Guide: https://www.uplift-modeling.com/en/latest/user_guide/index.html\n- Contributing guide: https://www.uplift-modeling.com/en/latest/contributing.html\n- Release History: https://www.uplift-modeling.com/en/latest/changelog.html\n\n===============\n\nPapers and materials\n---------------------\n1. Gutierrez, P., \u0026 Gérardy, J. Y.\n\tCausal Inference and Uplift Modelling: A Review of the Literature.\n\tIn International Conference on Predictive Applications and APIs (pp. 1-13).\n\n2. Artem Betlei, Criteo Research; Eustache Diemert, Criteo Research; Massih-Reza Amini, Univ. Grenoble Alpes\n\tDependent and Shared Data Representations improve Uplift Prediction in Imbalanced Treatment Conditions\n\tFAIM'18 Workshop on CausalML.\n\n3. Eustache Diemert, Artem Betlei, Christophe Renaudin, and Massih-Reza Amini. 2018.\n    A Large Scale Benchmark for Uplift Modeling.\n    In Proceedings of AdKDD \u0026 TargetAd (ADKDD’18). ACM, New York, NY, USA, 6 pages.\n\n4. Athey, Susan, and Imbens, Guido. 2015.\n    Machine learning methods for estimating heterogeneous causal effects.\n    Preprint, arXiv:1504.01132. Google Scholar.\n\n5. Oscar Mesalles Naranjo. 2012.\n    Testing a New Metric for Uplift Models.\n    Dissertation Presented for the Degree of MSc in Statistics and Operational Research.\n\n6. Kane, K., V. S. Y. Lo, and J. Zheng. 2014.\n    Mining for the Truly Responsive Customers and Prospects Using True-Lift Modeling:\n    Comparison of New and Existing Methods.\n    Journal of Marketing Analytics 2 (4): 218–238.\n\n7. Maciej Jaskowski and Szymon Jaroszewicz.\n    Uplift modeling for clinical trial data.\n    ICML Workshop on Clinical Data Analysis, 2012.\n\n8. Lo, Victor. 2002.\n    The True Lift Model - A Novel Data Mining Approach to Response Modeling in Database Marketing.\n    SIGKDD Explorations. 4. 78-86.\n\n9. Zhao, Yan \u0026 Fang, Xiao \u0026 Simchi-Levi, David. 2017.\n    Uplift Modeling with Multiple Treatments and General Response Types. 10.1137/1.9781611974973.66.\n\n10. Nicholas J Radcliffe. 2007.\n\tUsing control groups to target on predicted lift: Building and assessing uplift model. Direct Marketing Analytics Journal, (3):14–21, 2007.\n\n11. Devriendt, F., Guns, T., \u0026 Verbeke, W. 2020.\n\tLearning to rank for uplift modeling. ArXiv, abs/2002.05897.\n\n===============\n\nTags\n~~~~~~~~~~~~~~~\n**EN**: uplift modeling, uplift modelling, causal inference, causal effect, causality, individual treatment effect, true lift, net lift, incremental modeling\n\n**RU**: аплифт моделирование, Uplift модель\n\n**ZH**: uplift增量建模, 因果推断, 因果效应, 因果关系, 个体干预因果效应, 真实增量, 净增量, 增量建模\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaks-sh%2Fscikit-uplift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaks-sh%2Fscikit-uplift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaks-sh%2Fscikit-uplift/lists"}