{
    "info": {
        "author": "Max Halford, Vincent Lefoulon",
        "author_email": "maxhalford25@gmail.com, vincent.lefoulon@free.fr",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: BSD License",
            "Programming Language :: Python",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: Implementation :: CPython",
            "Programming Language :: Python :: Implementation :: PyPy"
        ],
        "description": "<div align=\"center\">\n  <h1>ethik</h1>\n</div>\n\n<div align=\"center\">\n  <!-- Travis -->\n  <a href=\"https://travis-ci.org/MaxHalford/ethik\">\n    <img src=\"https://img.shields.io/travis/MaxHalford/ethik/master.svg?style=for-the-badge\" alt=\"travis\" />\n  </a>\n  <!-- PyPI -->\n  <a href=\"https://pypi.org/project/ethik\">\n    <img src=\"https://img.shields.io/pypi/v/ethik.svg?style=for-the-badge\" alt=\"pypi\" />\n  </a>\n  <!-- License -->\n  <a href=\"https://www.gnu.org/licenses/gpl-3.0.en.html\">\n    <img src=\"https://img.shields.io/badge/License-GPL%20v3-blue.svg?style=for-the-badge\" alt=\"gpl_3_license\"/>\n  </a>\n</div>\n\n## Table of contents\n\n* [Introduction](#introduction)\n* [Installation](#installation)\n* [User guide](#user-guide)\n    * [Measuring model bias](#measuring-model-bias)\n    * [Evaluating model reliability](#evaluating-model-reliability)\n    * [Support for image classification](#support-for-image-classification)\n* [Authors](#authors)\n* [License](#license)\n\n**The documentation can be found [here](https://maxhalford.github.io/ethik/)**.\n\n## Introduction\n\n`ethik` is a Python package for performing [fair](https://perso.math.univ-toulouse.fr/loubes/fairness-robustness-in-machine-learning/) and [explainable](https://www.wikiwand.com/en/Explainable_artificial_intelligence) machine learning. At it's core, the approach of `ethik` is to build *counterfactual distributions* that permit answering \"what if?\" scenarios. The idea is that we are able to stress one or more variables and observe how a machine learning model reacts to the stress. The stress is based on a statistical re-weighting scheme called *entropic variable projection*. The main benefit of our method is that it will only consider realistic scenarios, and will not build fake examples. You may find more information by reading [this paper](https://arxiv.org/abs/1810.07924) as well as the [\"How It Works\" notebook](notebooks/How%20It%20Works.ipynb).\n\n<div align=\"center\">\n  <img src=\"docs/figures/overview.svg\" width=\"660px\" alt=\"overview\"/>\n</div>\n\nCurrently, `ethik` can be used for:\n\n1. Detecting model bias with respect to one or more (protected) attributes.\n2. Identifying causes for why a model performs poorly on certain inputs.\n3. Visualizing regions of an image that influence a model's predictions.\n\nWe have more plans for the future.\n\n## Installation\n\n:warning: Python 3.6 or above is required :snake:\n\n**Via [PyPI](https://pypi.org/project/ethik/)**\n\n```shell\n>>> pip install ethik\n```\n\n**Via GitHub for the latest development version**\n\n```shell\n>>> pip install git+https://github.com/MaxHalford/ethik\n>>> #\u00a0Or through SSH:\n>>> pip install git+ssh://git@github.com/MaxHalford/ethik.git\n```\n\n**Development installation**\n\n```shell\n>>> git clone https://github.com/MaxHalford/ethik\n>>> cd ethik\n>>> python setup.py develop\n>>> pip install -r requirements-dev.txt\n>>> pre-commit install #\u00a0For black\n```\n\n## User guide\n\n:point_up: Please check out [this notebook](notebooks/Binary%20classification.ipynb) for more detailed code.\n\nIn the following example we'll be using the [\"Adult\" dataset](https://archive.ics.uci.edu/ml/datasets/adult). This dataset contains a binary label indicating if a person's annual income is larger than $50k. `ethik` can diagnose a model by looking at the predictions the model makes on a test set. Consequently, you first have to split your dataset in two (train and test).\n\n```python\nfrom sklearn import model_selection\n\nX_train, X_test, y_train, y_test = model_selection.train_test_split(X, y, shuffle=True, random_state=42)\n```\n\nYou then want to train your model on the training set and make predictions on the test set. In this example we'll train a gradient boosting classifier from the [LightGBM library](https://lightgbm.readthedocs.io/en/latest/). We'll use a variable named `y_pred` to store the predicted probabilities associated with the `True` label.\n\n```python\nimport lightgbm as lgb\n\nmodel = lgb.LGBMClassifier(random_state=42).fit(X_train, y_train)\n\n# We use a named pandas series to make plot labels more explicit\ny_pred = model.predict_proba(X_test)[:, 1]\ny_pred = pd.Series(y_pred, name='>$50k')\n```\n\nWe can now initialize an `ClassificationExplainer` using the default parameters.\n\n```python\nimport ethik\n\nexplainer = ethik.ClassificationExplainer()\n```\n\n### Measuring model bias\n\n`ethik` can be used to understand how the model predictions vary as a function of one or more features. For example we can look at how the model behaves with respect to the `age` feature.\n\n```python\nexplainer.plot_bias(X_test=X_test['age'], y_pred=y_pred)\n```\n\n<div align=\"center\">\n  <img src=\"docs/figures/age_bias.svg\" alt=\"Age bias\" />\n</div>\n\nRecall that the target indicates if a person's annual salary is above $50k. **We can see that the model predicts higher probabilities for older people**. This isn't a surprising result, and could have just as well been observed by looking at the data. However, we can see that the predictions plateau at around 50 years old. Indeed, although salary is correlated with age, some people may retire early or lose their job. Furthermore we can see that the model understands the fact that salaries shrink once people get in age of retiring. This up-and-down relationship is in nature non-linear, and isn't picked up by summary statistics such as correlation coefficients, [odds ratios](https://www.wikiwand.com/en/Odds_ratio), and feature importances in general. Although the observations we made are quite obvious and rather intuitive, it's always good to confirm what the model is thinking. The point is that the curves produced by `plot_predictions` represent the relationship between a variable and the target according to the model, rather than the data.\n\nWe can also plot the distribution of predictions for more than one variable. However, because different variables have different scales we have to use a common measure to display them together. For this purpose we plot the \u03c4 (\"tau\") values. These values are contained between -1 and 1 and simply reflect by how much the variable is shifted from it's mean towards it's lower and upper quantiles. In the following figure a tau value of -1 corresponds to just under 20 years old whereas a tau value of 1 refers to being slightly over 60 years old.\n\n```python\nexplainer.plot_bias(X_test=X_test[['age', 'education-num']], y_pred=y_pred)\n```\n\n<div align=\"center\">\n  <img src=\"docs/figures/age_education_bias.svg\" alt=\"Age and education bias\" />\n</div>\n\nWe can observe that the model assigns higher probabilities to people with higher degrees, which makes perfect sense. Again, this conveys much more of a story than summary statistics.\n\n### Evaluating model reliability\n\nOur methodology can also be used to evaluate the reliability of a model under different scenarios. Evaluation metrics that are commonly used in machine learning only tell you part of the story. Indeed they tell you the performance of a model *on average*. A more interesting approach is to visualize how accurate the model is with respect to the distribution of a variable.\n\n```python\nexplainer.plot_performance(\n    X_test=X_test['age'],\n    y_test=y_test,\n    y_pred=y_pred > 0.5,  # metrics.accuracy_score requires y_pred to be binary\n    metric=metrics.accuracy_score\n)\n```\n\n<div align=\"center\">\n  <img src=\"docs/figures/age_accuracy.svg\" alt=\"Age accuracy\" />\n</div>\n\nIn the above figure **we can see that the model is more reliable for younger people than for older ones**. Having a fine-grained understanding of the accuracy of a model can be of extreme help in real-life scenarios. Indeed this can help you understand where the error of the model is coming from and guide your data science process.\n\nSimilarly to the `plot_predictions` method, we can display the performance of the model for multiple variables.\n\n```python\nexplainer.plot_performance(\n    X_test=X_test[['age', 'education-num']],\n    y_test=y_test,\n    y_pred=y_pred > 0.5,\n    metric=metrics.accuracy_score\n)\n```\n\n<div align=\"center\">\n  <img src=\"docs/figures/age_education_accuracy.svg\" alt=\"Age and education accuracy\" />\n</div>\n\n### Support for image classification\n\nA special class named `ImageClassificationExplainer` can be used to analyze image classification models. It has the same API as `ClassificationExplainer`, but expects to be provided with an array of images. For instance, we can analyze a CNN run on the MNIST dataset [from the Keras documendation](https://keras.io/examples/mnist_cnn/). The model achieves an accuracy of around 99% on the test set. For the sake of brevity we will the skip the exact details of the model training.\n\n```python\n(x_train, y_train), (x_test, y_test) = mnist.load_data()\n\ncnn.fit(x_train, y_train)\ny_pred = cnn.predict_proba(x_test)\n```\n\n`x_test` is a set of images of shape `(10000, 28, 28)` whilst `y_pred` is a set of probabilities predicted for digit by the CNN, and is thus of shape `(10000, 10)`. We can use the `plot_bias` method to display the importance of each pixel for the classifier with respect to each label.\n\n```python\nimport ethik\n\nexplainer = ethik.ImageClassificationExplainer()\nexplainer.plot_bias(x_test, y_pred)\n```\n\n<div align=\"center\">\n  <img width=\"75%\" src=\"docs/figures/mnist_bias_explanation.svg\" alt=\"Image bias explanation\" />\n</div>\n\nThis takes around 15 seconds to run on a mid-tier laptop. The previous plot highlights the regions of importance for identifying each digit. More precisely, the intensity of each pixel corresponds to the probability increase of saturating or not the pixel. A value of 0.28 means that saturating the pixel increases the probability predicted by the model by 0.28. Note that we do not saturate and desaturate the pixels independently. Instead, our method understands which pixels are linked together and saturates them in a realistic manner. The previous images show that the CNN seems to be using the same visual cues as a human. However, we can see that is uses very specific regions on images to identify particular digits. For instance, the top-right region of an image seems to trigger the \"5\" digit, whereas the bottom parts of the images seem to be linked with the \"7\" digit. Meanwhile, the colder areas correspond to regions that lower the predicted probabilities when the corresponding pixels are \"turned on\", which is why the center of the \"0\" digit figure is blue.\n\n## Authors\n\nThis work is led by members of the [Toulouse Institute of Mathematics](https://www.math.univ-toulouse.fr/?lang=en), namely:\n\n- [Fran\u00e7ois Bachoc](https://www.math.univ-toulouse.fr/~fbachoc/)\n- [Fabrice Gamboa](https://www.math.univ-toulouse.fr/~gamboa/newwab/Pages_Fabrice_Gamboa/Main_Page.html)\n- [Max Halford](https://maxhalford.github.io/)\n- [Vincent Lefoulon](https://vayel.github.io/)\n- [Jean-Michel Loubes](https://perso.math.univ-toulouse.fr/loubes/)\n- [Laurent Risser](http://laurent.risser.free.fr/menuEng.html)\n\nYou can contact us at [jm.loubes@gmail.com](mailto:jm.loubes@gmail.com) and/or [maxhalford25@gmail.com](mailto:maxhalford25@gmail.com).\n\nThis work is supported by the [Centre National de la Recherche Scientifique (CNRS)](http://www.cnrs.fr/) and is done in the context of the [Artificial and Natural Intelligence Toulouse Institute (ANITI)](https://en.univ-toulouse.fr/aniti) project.\n\n## License\n\nThis software is released under the [GPL license](LICENSE).",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/MaxHalford/ethik",
        "keywords": "",
        "license": "BSD-3",
        "maintainer": "",
        "maintainer_email": "",
        "name": "ethik",
        "package_url": "https://pypi.org/project/ethik/",
        "platform": "",
        "project_url": "https://pypi.org/project/ethik/",
        "project_urls": {
            "Homepage": "https://github.com/MaxHalford/ethik"
        },
        "release_url": "https://pypi.org/project/ethik/0.0.2/",
        "requires_dist": null,
        "requires_python": ">=3.6.0",
        "summary": "A toolbox for fair and explainable machine learning",
        "version": "0.0.2"
    },
    "last_serial": 5918613,
    "releases": {
        "0.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "6bc2bcf9e678a6da3f06f4733bd7f59b",
                    "sha256": "b9b70c8f299c2f1486edc6758a46b2bef92e57e6d1bc960625b4a1e98b912693"
                },
                "downloads": -1,
                "filename": "ethik-0.0.1-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "6bc2bcf9e678a6da3f06f4733bd7f59b",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": ">=3.6.0",
                "size": 35096,
                "upload_time": "2019-10-01T13:00:55",
                "url": "https://files.pythonhosted.org/packages/11/14/cbf0d2179c31df085230b22175d0c9535b43660977842d03acfb1c83354e/ethik-0.0.1-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "8f5e96d6451fa1256449af66777d8a81",
                    "sha256": "bacdd478feb5cb2a508b2a5c3201ca49a644f025f5fb1a3b9584bed3b21fd35f"
                },
                "downloads": -1,
                "filename": "ethik-0.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "8f5e96d6451fa1256449af66777d8a81",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6.0",
                "size": 24743,
                "upload_time": "2019-10-01T13:01:07",
                "url": "https://files.pythonhosted.org/packages/81/21/d20709eabb648e2daab9e30d8172ab71d7c0a6be205452afb9a819a2db2d/ethik-0.0.1.tar.gz"
            }
        ],
        "0.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "94b9fd48efe36bca43ce47fb0d567509",
                    "sha256": "f6a4e39f194ad3a63e6493726f623509781e4dfe752a7dc0dc628d91bae575eb"
                },
                "downloads": -1,
                "filename": "ethik-0.0.2-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "94b9fd48efe36bca43ce47fb0d567509",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": ">=3.6.0",
                "size": 278756,
                "upload_time": "2019-10-02T15:51:02",
                "url": "https://files.pythonhosted.org/packages/1c/ed/d5993f53761b39014ff489877cd869d10e796047e6028776ad487652a5ea/ethik-0.0.2-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "0c638a67746112e489d2df256ba1705d",
                    "sha256": "05edbc5151c14d63104f2dc6545111717d9193fe87c29cd31e12b69782010820"
                },
                "downloads": -1,
                "filename": "ethik-0.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "0c638a67746112e489d2df256ba1705d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": ">=3.6.0",
                "size": 25839,
                "upload_time": "2019-10-02T13:52:30",
                "url": "https://files.pythonhosted.org/packages/75/80/ce33bca42b5fa811553f9ee67ea436e854018fa7049086e84ad54bbd5f03/ethik-0.0.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "94b9fd48efe36bca43ce47fb0d567509",
                "sha256": "f6a4e39f194ad3a63e6493726f623509781e4dfe752a7dc0dc628d91bae575eb"
            },
            "downloads": -1,
            "filename": "ethik-0.0.2-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "94b9fd48efe36bca43ce47fb0d567509",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">=3.6.0",
            "size": 278756,
            "upload_time": "2019-10-02T15:51:02",
            "url": "https://files.pythonhosted.org/packages/1c/ed/d5993f53761b39014ff489877cd869d10e796047e6028776ad487652a5ea/ethik-0.0.2-py2.py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "0c638a67746112e489d2df256ba1705d",
                "sha256": "05edbc5151c14d63104f2dc6545111717d9193fe87c29cd31e12b69782010820"
            },
            "downloads": -1,
            "filename": "ethik-0.0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "0c638a67746112e489d2df256ba1705d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6.0",
            "size": 25839,
            "upload_time": "2019-10-02T13:52:30",
            "url": "https://files.pythonhosted.org/packages/75/80/ce33bca42b5fa811553f9ee67ea436e854018fa7049086e84ad54bbd5f03/ethik-0.0.2.tar.gz"
        }
    ]
}