Merge branch 'release/v0.5.1'

Author: maks-sh

Readme.rst

@@ -32,6 +32,9 @@
     :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
 ===============
@@ -199,6 +202,10 @@ We welcome new contributors of all experience levels.
 - 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>`__.
 
+Thanks to all our contributors!
+
+|Contribs|
+
 If you have any questions, please contact us at [email protected]
 
 Important links

docs/api/models/ClassTransformationReg.rst

@@ -0,0 +1,6 @@
+********************************************
+`sklift.models <./>`_.ClassTransformationReg
+********************************************
+
+.. autoclass:: sklift.models.models.ClassTransformationReg
+    :members:

docs/api/models/index.rst

@@ -9,4 +9,5 @@ See :ref:`Models <models>` section of the User Guide for further details.
 
    ./SoloModel
    ./ClassTransformation
+   ./ClassTransformationReg
    ./TwoModels

docs/changelog.md

@@ -8,11 +8,26 @@
 * 🔨 something that previously didn’t work as documented – or according to reasonable expectations – should now work.
 * ❗️ you will need to change your code to have the same effect in the future; or a feature will be removed in the future.
 
+## Version 0.5.1
+
+### [sklift.models](https://www.uplift-modeling.com/en/v0.5.1/api/models/index.html)
+
+* 📝 Add docs page for [ClassTransformationReg](https://www.uplift-modeling.com/en/v0.5.1/api/models/ClassTransformationReg.html) model. 
+
+### [sklift.datasets](https://www.uplift-modeling.com/en/v0.5.1/api/datasets/index.html)
+
+* 🔨 Fix bug in [fetch_x5](https://www.uplift-modeling.com/en/v0.5.1/api/datasets/fetch_x5.html) func.
+
+### [User Guide](https://www.uplift-modeling.com/en/v0.5.1/user_guide/index.html)
+
+* 📝 Add page for [Transformed Outcome](https://www.uplift-modeling.com/en/v0.5.1/user_guide/models/transformed_outcome.html) approach. 
+
+
 ## Version 0.5.0
 
 ### [sklift.models](https://www.uplift-modeling.com/en/v0.5.0/api/models/index.html)
 
-* 🔥 Add [ClassTransformationReg](https://www.uplift-modeling.com/en/v0.5.0/api/models.html#sklift.models.models.TwoModels) model by [@mcullan](https://github.com/mcullan) and [@ElisovaIra](https://github.com/ElisovaIra).
+* 🔥 Add ClassTransformationReg model by [@mcullan](https://github.com/mcullan) and [@ElisovaIra](https://github.com/ElisovaIra).
 * 🔨 Add the ability to process a series with different indexes in the [TwoModels](https://www.uplift-modeling.com/en/v0.5.0/api/models.html#sklift.models.models.TwoModels) by [@flashlight101](https://github.com/flashlight101).
 
 ### [sklift.metrics](https://www.uplift-modeling.com/en/v0.5.0/api/index/metrics.html)
@@ -21,11 +36,11 @@
 
 ### [sklift.datasets](https://www.uplift-modeling.com/en/v0.5.0/api/datasets/index.html)
 
-* 💥 Add cheker based on hash for all datasets by [@flashlight101](https://github.com/flashlight101)
+* 💥 Add checker based on hash for all datasets by [@flashlight101](https://github.com/flashlight101)
 * 📝 Add [scheme](https://www.uplift-modeling.com/en/v0.5.0/api/datasets/fetch_x5.html) of x5 dataframes.
 
 ### Miscellaneous
-* 📝 Improve Chinise tags by [@00helloworld](https://github.com/00helloworld)
+* 📝 Improve Chinese tags by [@00helloworld](https://github.com/00helloworld)
 
 ## Version 0.4.1
 

docs/index.rst

@@ -4,6 +4,10 @@
 .. |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/uplift_model_selection_tutorial.ipynb
 
+.. |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
 **************
@@ -76,6 +80,10 @@ Sklift is being actively maintained and welcomes new contributors of all experie
 - 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>`__.
 
+Thanks to all our contributors!
+
+|Contribs|
+
 If you have any questions, please contact us at [email protected]
 
 .. toctree::

docs/user_guide/models/index.rst

@@ -16,4 +16,5 @@ Models
    ./classification
    ./solo_model
    ./revert_label
+   ./transformed_outcome
    ./two_models

docs/user_guide/models/transformed_outcome.rst

@@ -0,0 +1,43 @@
+.. _ClassTransformationReg:
+
+********************
+Transformed Outcome
+********************
+
+Let's redefine target variable, which indicates that treatment make some impact on target or
+did target is negative without treatment:
+
+.. math::
+    Z = Y * \frac{(W - p)}{(p * (1 - p))}
+
+* :math:`Y` - target vector,
+* :math:`W` - vector of binary communication flags, and
+* :math:`p` is a *propensity score* (the probabilty that each :math:`y_i` is assigned to the treatment group.).
+
+It is important to note here that it is possible to estimate :math:`p` as the proportion of objects with :math:`W = 1`
+in the sample. Or use the method from [2], in which it is proposed to evaluate math:`p` as a function of :math:`X` by
+training the classifier on the available data :math:`X = x`, and taking the communication flag vector math:`W` as
+the target variable.
+
+.. image:: https://habrastorage.org/r/w1560/webt/35/d2/z_/35d2z_-3yhyqhwtw-mt-npws6xk.png
+    :align: center
+    :alt: Transformation of the target in Transformed Outcome approach
+
+After applying the formula, we get a new target variable :math:`Z_i` and can train a regression model with the error
+functional :math:`MSE= \frac{1}{n}\sum_{i=0}^{n} (Z_i - \hat{Z_i})^2`. Since it is precisely when using MSE that the
+predictions of the model are the conditional mathematical expectation of the target variable.
+
+It can be proved that the conditional expectation of the transformed target :math:`Z_i` is the desired causal effect:
+
+.. math::
+    E[Z_i| X_i = x] = Y_i^1 - Y_i^0 = \tau_i
+
+.. hint::
+    In sklift this approach corresponds to the :class:`.ClassTransformationReg` class.
+
+References
+==========
+
+1️⃣  Susan Athey and Guido W Imbens. Machine learning methods for estimating heterogeneouscausal effects. stat, 1050:5, 2015.
+
+2️⃣  P. Richard Hahn, Jared S. Murray, and Carlos Carvalho. Bayesian regression tree models for causal inference: regularization, confounding, and heterogeneous effects. 2019.

sklift/__init__.py

@@ -1 +1 @@
-__version__ = '0.5.0'
+__version__ = '0.5.1'