****
CEML
****
--------------------------------------------------------
Counterfactuals for Explaining Machine Learning models
--------------------------------------------------------
CEML is a Python toolbox for computing counterfactuals. Counterfactuals can be used to explain the predictions of machine learing models.
It supports many common machine learning frameworks:
- scikit-learn (1.3.1)
- PyTorch (2.0.1)
- Keras & Tensorflow (2.13.1)
Furthermore, CEML is easy to use and can be extended very easily. See the following user guide for more information on how to use and extend CEML.
Installation
------------
**Note: Python 3.8 is required!**
PyPI
++++
.. code-block:: bash
pip install ceml
**Note**: The package hosted on PyPI uses the cpu only. If you want to use the gpu, you have to install CEML manually - see next section.
Git
+++
Download or clone the repository:
.. code:: bash
git clone https://github.com/andreArtelt/ceml.git
cd ceml
Install all requirements (listed in ``requirements.txt``):
.. code:: bash
pip install -r requirements.txt
**Note**: If you want to use a gpu/tpu, you have to install the gpu version of jax, tensorflow and pytorch manually. Do not use ``pip install -r requirements.txt``.
Install the toolbox itself:
.. code:: bash
pip install .
Quick example
-------------
.. code-block:: python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
from sklearn.tree import DecisionTreeClassifier
from ceml.sklearn import generate_counterfactual
if __name__ == "__main__":
# Load data
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.33, random_state=4242)
# Whitelist of features - list of features we can change/use when computing a counterfactual
features_whitelist = None # We can use all features
# Create and fit model
model = DecisionTreeClassifier(max_depth=3)
model.fit(X_train, y_train)
# Select data point for explaining its prediction
x = X_test[1,:]
print("Prediction on x: {0}".format(model.predict([x])))
# Compute counterfactual
print("\nCompute counterfactual ....")
print(generate_counterfactual(model, x, y_target=0, features_whitelist=features_whitelist))
Documentation
-------------
Documentation is available on readthedocs:`https://ceml.readthedocs.io/en/latest/ <https://ceml.readthedocs.io/en/latest/>`_
License
-------
MIT license - See `LICENSE <LICENSE>`_
How to cite?
------------
You can cite CEML by using the following BibTeX entry:
.. code-block::
@misc{ceml,
author = {André Artelt},
title = {CEML: Counterfactuals for Explaining Machine Learning models - A Python toolbox},
year = {2019 - 2023},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://www.github.com/andreArtelt/ceml}}
}
Third party components
----------------------
- `numpy <https://github.com/numpy/numpy>`_
- `scipy <https://github.com/scipy/scipy>`_
- `jax <https://github.com/google/jax>`_
- `cvxpy <https://github.com/cvxgrp/cvxpy>`_
- `scikit-learn <https://github.com/scikit-learn/scikit-learn>`_
- `sklearn-lvq <https://github.com/MrNuggelz/sklearn-lvq>`_
- `PyTorch <https://github.com/pytorch/pytorch>`_
- `tensorflow <https://github.com/tensorflow>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/andreArtelt/ceml",
"name": "ceml",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "machine learning counterfactual",
"author": "Andr\u00e9 Artelt",
"author_email": "aartelt@techfak.uni-bielefeld.de",
"download_url": "",
"platform": null,
"description": "****\nCEML\n****\n--------------------------------------------------------\nCounterfactuals for Explaining Machine Learning models\n--------------------------------------------------------\n\nCEML is a Python toolbox for computing counterfactuals. Counterfactuals can be used to explain the predictions of machine learing models.\n\nIt supports many common machine learning frameworks:\n\n - scikit-learn (1.3.1)\n - PyTorch (2.0.1)\n - Keras & Tensorflow (2.13.1)\n\nFurthermore, CEML is easy to use and can be extended very easily. See the following user guide for more information on how to use and extend CEML.\n\nInstallation\n------------\n\n**Note: Python 3.8 is required!**\n\nPyPI\n++++\n\n.. code-block:: bash\n\n pip install ceml\n\n**Note**: The package hosted on PyPI uses the cpu only. If you want to use the gpu, you have to install CEML manually - see next section.\n\nGit\n+++\nDownload or clone the repository:\n\n.. code:: bash\n\n git clone https://github.com/andreArtelt/ceml.git\n cd ceml\n\nInstall all requirements (listed in ``requirements.txt``):\n\n.. code:: bash\n\n pip install -r requirements.txt\n\n**Note**: If you want to use a gpu/tpu, you have to install the gpu version of jax, tensorflow and pytorch manually. Do not use ``pip install -r requirements.txt``.\n\nInstall the toolbox itself:\n\n.. code:: bash\n\n pip install .\n\n\nQuick example\n-------------\n\n.. code-block:: python\n\n #!/usr/bin/env python3\n # -*- coding: utf-8 -*-\n from sklearn.datasets import load_iris\n from sklearn.model_selection import train_test_split\n from sklearn.metrics import accuracy_score\n from sklearn.tree import DecisionTreeClassifier\n\n from ceml.sklearn import generate_counterfactual\n\n\n if __name__ == \"__main__\":\n # Load data\n X, y = load_iris(return_X_y=True)\n X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.33, random_state=4242)\n\n # Whitelist of features - list of features we can change/use when computing a counterfactual \n features_whitelist = None # We can use all features\n\n # Create and fit model\n model = DecisionTreeClassifier(max_depth=3)\n model.fit(X_train, y_train)\n\n # Select data point for explaining its prediction\n x = X_test[1,:]\n print(\"Prediction on x: {0}\".format(model.predict([x])))\n\n # Compute counterfactual\n print(\"\\nCompute counterfactual ....\")\n print(generate_counterfactual(model, x, y_target=0, features_whitelist=features_whitelist))\n\nDocumentation\n-------------\n\nDocumentation is available on readthedocs:`https://ceml.readthedocs.io/en/latest/ <https://ceml.readthedocs.io/en/latest/>`_\n\nLicense\n-------\n\nMIT license - See `LICENSE <LICENSE>`_\n\nHow to cite?\n------------\n You can cite CEML by using the following BibTeX entry:\n\n .. code-block::\n\n @misc{ceml,\n author = {Andr\u00e9 Artelt},\n title = {CEML: Counterfactuals for Explaining Machine Learning models - A Python toolbox},\n year = {2019 - 2023},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://www.github.com/andreArtelt/ceml}}\n }\n\n\nThird party components\n----------------------\n\n - `numpy <https://github.com/numpy/numpy>`_\n - `scipy <https://github.com/scipy/scipy>`_\n - `jax <https://github.com/google/jax>`_\n - `cvxpy <https://github.com/cvxgrp/cvxpy>`_\n - `scikit-learn <https://github.com/scikit-learn/scikit-learn>`_\n - `sklearn-lvq <https://github.com/MrNuggelz/sklearn-lvq>`_\n - `PyTorch <https://github.com/pytorch/pytorch>`_\n - `tensorflow <https://github.com/tensorflow>`_\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Counterfactuals for explaining machine learning models - A Python toolbox",
"version": "0.7",
"project_urls": {
"Homepage": "https://github.com/andreArtelt/ceml"
},
"split_keywords": [
"machine",
"learning",
"counterfactual"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04e71e0043884354ddd25c56a421b1b06972fffc0cdd9b03d783b85aeb8b1b2d",
"md5": "d2522d914055e3e0dd8348bf2a53a2e8",
"sha256": "94fb10bb367ce2d93c1e3976aaacec75e94bb3248eff77b7b1a8e36ee910a0c3"
},
"downloads": -1,
"filename": "ceml-0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2522d914055e3e0dd8348bf2a53a2e8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 91042,
"upload_time": "2023-10-30T08:15:13",
"upload_time_iso_8601": "2023-10-30T08:15:13.704586Z",
"url": "https://files.pythonhosted.org/packages/04/e7/1e0043884354ddd25c56a421b1b06972fffc0cdd9b03d783b85aeb8b1b2d/ceml-0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-30 08:15:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andreArtelt",
"github_project": "ceml",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "sklearn-lvq",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "tensorflow",
"specs": [
[
"==",
"2.13.1"
]
]
},
{
"name": "torch",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "cvxpy",
"specs": [
[
"==",
"1.3.2"
]
]
},
{
"name": "jax",
"specs": [
[
"==",
"0.4.13"
]
]
},
{
"name": "jaxlib",
"specs": [
[
"==",
"0.4.13"
]
]
}
],
"lcname": "ceml"
}
JSON
