Merge branch 'feature/user_guide_and_docs_improving' into dev

Author: maks-sh

.github/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team. All
+reported by contacting the project team at [email protected]. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

Readme.rst

@@ -36,27 +36,36 @@
 scikit-uplift
 ===============
 
-**scikit-uplift** is a Python module for classic approaches for uplift modeling built on top of scikit-learn.
+**scikit-uplift (sklift)** is an uplift modeling python package that provides fast sklearn-style models implementation, evaluation metrics and visualization tools.
 
-Uplift prediction aims to estimate the causal impact of a treatment at the individual level.
+Uplift modeling estimates a causal effect of treatment and uses it to effectively target customers that are most likely to respond to a marketing campaign.
+
+**Use cases for uplift modeling:**
+
+* 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).
+
+* Combine a churn model and an uplift model to offer some bonus to a group of customers who are likely to churn.
+
+* Select a tiny group of customers in the campaign where a price per customer is high.
 
 Read more about uplift modeling problem in `User Guide <https://scikit-uplift.readthedocs.io/en/latest/user_guide/index.html>`__,
-also articles in russian on habr.com: `Part 1 <https://habr.com/ru/company/ru_mts/blog/485980/>`__
+
+Articles in russian on habr.com: `Part 1 <https://habr.com/ru/company/ru_mts/blog/485980/>`__
 and `Part 2 <https://habr.com/ru/company/ru_mts/blog/485976/>`__.
 
 **Features**:
 
-* Comfortable and intuitive style of modelling like scikit-learn;
+* Сomfortable and intuitive scikit-learn-like API;
 
-* Applying any estimator adheres to scikit-learn conventions;
+* Applying any estimator compatible with scikit-learn (e.g. Xgboost, LightGBM, Catboost, etc.);
 
 * All approaches can be used in sklearn.pipeline (see example (`EN <https://nbviewer.jupyter.org/github/maks-sh/scikit-uplift/blob/master/notebooks/pipeline_usage_EN.ipynb>`__ |Open In Colab3|_, `RU <https://nbviewer.jupyter.org/github/maks-sh/scikit-uplift/blob/master/notebooks/pipeline_usage_RU.ipynb>`__ |Open In Colab4|_));
 
-* Almost all implemented approaches solve both the problem of classification and regression;
+* Almost all implemented approaches solve classification and regression problem;
 
-* A lot of metrics (Such as *Area Under Uplift Curve* or *Area Under Qini Curve*) are implemented to evaluate your uplift model;
+* More uplift metrics that 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;
 
-* Useful graphs for analyzing the built model.
+* Nice and useful viz for analyzing a performance model.
 
 Installation
 -------------
@@ -149,7 +158,7 @@ See the **RetailHero tutorial notebook** (`EN <https://nbviewer.jupyter.org/gith
     # import vizualisation tools
     from sklift.viz import plot_qini_curve
 
-    plot_qini_curve(y_true=y_val, uplift=uplift_preds, treatment=treat_val)
+    plot_qini_curve(y_true=y_val, uplift=uplift_preds, treatment=treat_val, negative_effect=True)
 
 .. image:: docs/_static/images/Readme_qini_curve.png
     :width: 514px
@@ -164,6 +173,8 @@ We welcome new contributors of all experience levels.
 - Please see our `Contributing Guide <https://scikit-uplift.readthedocs.io/en/latest/contributing.html>`_ for more details.
 - By participating in this project, you agree to abide by its `Code of Conduct <https://github.com/maks-sh/scikit-uplift/blob/master/.github/CODE_OF_CONDUCT.md>`__.
 
+If you have any questions, please contact us at [email protected]
+
 Contributing
 ~~~~~~~~~~~~~~~
 

docs/Readme.rst

@@ -1,9 +1,9 @@
-.. _scikit-uplift.readthedocs.io: https://scikit-uplift.readthedocs.io/en/latest/
+.. _uplift-modeling.com: https://www.uplift-modeling.com/en/latest/index.html
 
 Documentation
 ===============
 
-The full documentation is available at `scikit-uplift.readthedocs.io`_.
+The full documentation is available at `uplift-modeling.com`_.
 
 Or you can build the documentation locally using `Sphinx <http://sphinx-doc.org/>`_ 1.4 or later:
 

docs/_static/images/user_guide/ug_uplift_approaches.png

@@ -4,7 +4,10 @@ Hall of Fame
 
 Here are the links to the competitions, names of the winners and to their solutions, where scikit-uplift was used.
 
-`X5 RetailHero Uplift Modeling contest <https://retailhero.ai/c/uplift_modeling/overview>`_
-=============================================================================================
+`X5 Retail Hero: Uplift Modeling for Promotional Campaign <https://ods.ai/competitions/x5-retailhero-uplift-modeling>`_
+========================================================================================================================
+
+Predict how much the purchase probability could increase as a result of sending an advertising SMS.
+
 2. `Kirill Liksakov <https://github.com/kirrlix1994>`_
     `solution <https://github.com/kirrlix1994/Retail_hero>`_

docs/hall_of_fame.rst

@@ -8,28 +8,39 @@
 scikit-uplift
 **************
 
-**scikit-uplift (sklift)** is a Python module for basic approaches of uplift modeling built on top of scikit-learn.
+**scikit-uplift (sklift)** is an uplift modeling python package that provides fast sklearn-style models implementation, evaluation metrics and visualization tools.
 
-Uplift prediction aims to estimate the causal impact of a treatment at the individual level.
+The main idea is to provide easy-to-use and fast python package for uplift modeling. It delivers the model interface with the familiar scikit-learn API. One can use any popular estimator (for instance, from the Catboost library).
 
-Read more about uplift modeling problem in :ref:`User Guide <user_guide>`,
-also articles in russian on habr.com: `Part 1 <https://habr.com/ru/company/ru_mts/blog/485980/>`__
+*Uplift modeling* estimates a causal effect of treatment and uses it to effectively target customers that are most likely to respond to a marketing campaign.
+
+**Use cases for uplift modeling:**
+
+* 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).
+
+* Combine a churn model and an uplift model to offer some bonus to a group of customers who are likely to churn.
+
+* Select a tiny group of customers in the campaign where a price per customer is high.
+
+Read more about *uplift modeling* problem in `User Guide <https://scikit-uplift.readthedocs.io/en/latest/user_guide/index.html>`__,
+
+Articles in russian on habr.com: `Part 1 <https://habr.com/ru/company/ru_mts/blog/485980/>`__
 and `Part 2 <https://habr.com/ru/company/ru_mts/blog/485976/>`__.
 
 Features
 #########
 
-- Comfortable and intuitive style of modelling like scikit-learn;
+- Сomfortable and intuitive scikit-learn-like API;
 
-- Applying any estimator adheres to scikit-learn conventions;
+- Applying any estimator compatible with scikit-learn (e.g. Xgboost, LightGBM, Catboost, etc.);
 
-- All approaches can be used in sklearn.pipeline. See example of usage: |Open In Colab3|_;
+- All approaches can be used in `sklearn.pipeline`. See the example of usage: |Open In Colab3|_;
 
-- Almost all implemented approaches solve both the problem of classification and regression;
+- Almost all implemented approaches solve classification and regression problem;
 
-- A lot of metrics (Such as *Area Under Uplift Curve* or *Area Under Qini Curve*) are implemented to evaluate your uplift model;
+- More uplift metrics that 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;
 
-- Useful graphs for analyzing the built model.
+- Nice and useful viz for analyzing a performance model.
 
 
 **The package currently supports the following methods:**
@@ -50,18 +61,20 @@ Project info
 
 * GitHub repository: https://github.com/maks-sh/scikit-uplift
 * Github examples: https://github.com/maks-sh/scikit-uplift/tree/master/notebooks
-* Documentation: https://scikit-uplift.readthedocs.io/en/latest/
-* Contributing guide: https://scikit-uplift.readthedocs.io/en/latest/contributing.html
+* Documentation: https://www.uplift-modeling.com/en/latest/index.html
+* Contributing guide: https://www.uplift-modeling.com/en/latest/contributing.html
 * License: `MIT <https://github.com/maks-sh/scikit-uplift/blob/master/LICENSE>`__
 
 Community
 #############
 
-We welcome new contributors of all experience levels.
+Sklift is being actively maintained and welcomes new contributors of all experience levels.
 
-- Please see our `Contributing Guide <https://scikit-uplift.readthedocs.io/en/latest/contributing.html>`_ for more details.
+- Please see our `Contributing Guide <https://www.uplift-modeling.com/en/latest/contributing.html>`_ for more details.
 - By participating in this project, you agree to abide by its `Code of Conduct <https://github.com/maks-sh/scikit-uplift/blob/master/.github/CODE_OF_CONDUCT.md>`__.
 
+If you have any questions, please contact us at [email protected]
+
 .. image:: https://sourcerer.io/fame/maks-sh/maks-sh/scikit-uplift/images/0
    :target: https://sourcerer.io/fame/maks-sh/maks-sh/scikit-uplift/links/0
    :alt: Top contributor 1

docs/index.rst

@@ -13,7 +13,10 @@ Quick Start
 
 See the **RetailHero tutorial notebook** (`EN`_ |Open In Colab1|_, `RU`_ |Open In Colab2|_) for details.
 
-**Train and predict your uplift model**
+Train and predict your uplift model
+====================================
+
+Use the intuitive python API to train uplift models.
 
 .. code-block:: python
     :linenos:
@@ -38,7 +41,8 @@ See the **RetailHero tutorial notebook** (`EN`_ |Open In Colab1|_, `RU`_ |Open I
     # predict uplift
     uplift_preds = tm.predict(X_val)
 
-**Evaluate your uplift model**
+Evaluate your uplift model
+===========================
 
 .. code-block:: python
     :linenos:
@@ -66,14 +70,15 @@ See the **RetailHero tutorial notebook** (`EN`_ |Open In Colab1|_, `RU`_ |Open I
     tm_wau = weighted_average_uplift(y_true=y_val, uplift=uplift_preds,
                                      treatment=treat_val)
 
-**Vizualize the results**
+Vizualize the results
+======================
 
 .. code-block:: python
     :linenos:
 
     from sklift.viz import plot_qini_curve
 
-    plot_qini_curve(y_true=y_val, uplift=uplift_preds, treatment=treat_val)
+    plot_qini_curve(y_true=y_val, uplift=uplift_preds, treatment=treat_val, negative_effect=True)
 
 .. image:: _static/images/quick_start_qini.png
     :width: 514px

docs/quick_start.rst

@@ -7,7 +7,7 @@ User Guide
 .. image:: https://habrastorage.org/webt/hf/7i/nu/hf7inuu3agtnwl1yo0g--mznzno.jpeg
    :alt: Cover of User Guide for uplift modeling and causal inference
 
-Uplift modeling estimates the effect of communication action on some customer outcome and gives an opportunity to efficiently target customers which are most likely to respond to a marketing campaign.
+Uplift modeling estimates the effect of communication action on some customer outcomes and gives an opportunity to efficiently target customers which are most likely to respond to a marketing campaign.
 It is relatively easy to implement, but surprisingly poorly covered in the machine learning courses and literature.
 This guide is going to shed some light on the essentials of causal inference estimating and uplift modeling.
 
@@ -44,5 +44,5 @@ If you find this User Guide useful for your research, please consider citing:
       year = {2020},
       publisher = {GitHub},
       journal = {GitHub repository},
-      howpublished = {\url{https://scikit-uplift.readthedocs.io/en/latest/user_guide/index.html}}
+      howpublished = {\url{https://www.uplift-modeling.com/en/latest/user_guide/index.html}}
     }

docs/user_guide/index.rst

@@ -2,7 +2,7 @@
 Causal Inference: Basics
 ******************************************
 
-In a perfect world, we want to calculate a difference in a person's reaction received communication and the reaction without receiving any communication.
+In a perfect world, we want to calculate a difference in a person's reaction received communication, and the reaction without receiving any communication.
 But there is a problem: we can not make a communication (send an e-mail) and do not make a communication (no e-mail) at the same time.
 
 .. image:: https://habrastorage.org/webt/fl/fi/dz/flfidz416o7of5j0nmgdjqqkzfe.jpeg
@@ -29,8 +29,8 @@ But we can estimate CATE or *uplift* of an object:
 
 Where:
 
-- :math:`W_i \in {0, 1}` - a binary variable: 1 if person :math:`i` receives the treatment :guilabel:`treatment group`, and 0 if person :math:`i` receives no treatment :guilabel:`control group`;
-- :math:`Y_i` - person :math:`i`’s observed outcome, which is actually equal:
+- :math:`W_i \in {0, 1}` - a binary variable: 1 if person :math:`i` receives the :guilabel:`treatment group`, and 0 if person :math:`i` receives no treatment :guilabel:`control group`;
+- :math:`Y_i` - person :math:`i`’s observed outcome, which is equal:
 
 .. math::
     Y_i = W_i * Y_i^1 + (1 - W_i) * Y_i^0 = \
@@ -41,12 +41,12 @@ Where:
 
 This won’t identify the CATE unless one is willing to assume that :math:`W_i` is independent of :math:`Y_i^1` and :math:`Y_i^0` conditional on :math:`X_i`. This assumption is the so-called *Unconfoundedness Assumption* or the *Conditional Independence Assumption* (CIA) found in the social sciences and medical literature.
 This assumption holds true when treatment assignment is random conditional on :math:`X_i`.
-Briefly this can be written as:
+Briefly, this can be written as:
 
 .. math::
     CIA : \{Y_i^0, Y_i^1\} \perp \!\!\! \perp W_i \vert X_i
 
-Also introduce additional useful notation.
+Also, introduce additional useful notation.
 Let us define the :guilabel:`propensity score`, :math:`p(X_i) = P(W_i = 1| X_i)`, i.e. the probability of treatment given :math:`X_i`.
 
 References

docs/user_guide/introduction/cate.rst

@@ -2,18 +2,18 @@
 Types of customers
 ******************************************
 
-We can determine 4 types of customers based on a response to a treatment:
+We can determine 4 types of customers based on a response to treatment:
 
 .. image:: ../../_static/images/user_guide/ug_clients_types.jpg
    :alt: Classification of customers based on their response to a treatment
    :width: 268 px
    :height: 282 px
    :align: center
 
-- :guilabel:`Do-Not-Disturbs` *(a.k.a. Sleeping-dogs)* have a strong negative response to a marketing communication. They are going to purchase if *NOT* treated and will *NOT* purchase *IF* treated. It is not only a wasted marketing budget but also a negative impact. For instance, customers targeted could result in rejecting current products or services. In terms of math: :math:`W_i = 1, Y_i = 0` or :math:`W_i = 0, Y_i = 1`.
+- :guilabel:`Do-Not-Disturbs` *(a.k.a. Sleeping-dogs)* have a strong negative response to marketing communication. They are going to purchase if *NOT* treated and will *NOT* purchase *IF* treated. It is not only a wasted marketing budget but also a negative impact. For instance, customers targeted could result in rejecting current products or services. In terms of math: :math:`W_i = 1, Y_i = 0` or :math:`W_i = 0, Y_i = 1`.
 - :guilabel:`Lost Causes` will *NOT* purchase the product *NO MATTER* they are contacted or not. The marketing budget in this case is also wasted because it has no effect. In terms of math: :math:`W_i = 1, Y_i = 0` or :math:`W_i = 0, Y_i = 0`.
 - :guilabel:`Sure Things` will purchase *ANYWAY* no matter they are contacted or not. There is no motivation to spend the budget because it also has no effect. In terms of math: :math:`W_i = 1, Y_i = 1` or :math:`W_i = 0, Y_i = 1`.
-- :guilabel:`Persuadables` will always respond *POSITIVE* to the marketing communication. They is going to purchase *ONLY* if contacted (or sometimes they purchase *MORE* or *EARLIER* only if contacted). This customer's type should be the only target for the marketing campaign. In terms of math: :math:`W_i = 0, Y_i = 0` or :math:`W_i = 1, Y_i = 1`.
+- :guilabel:`Persuadables` will always respond *POSITIVE* to marketing communication. They are going to purchase *ONLY* if contacted (or sometimes they purchase *MORE* or *EARLIER* only if contacted). This customer's type should be the only target for the marketing campaign. In terms of math: :math:`W_i = 0, Y_i = 0` or :math:`W_i = 1, Y_i = 1`.
 
 Because we can't communicate and not communicate with the customer at the same time, we will never be able to observe exactly which type a particular customer belongs to.