https://github.com/andreArtelt/ceml

CEML - Counterfactuals for Explaining Machine Learning models - A Python toolbox
https://github.com/andreArtelt/ceml

counterfactual-explanations explainable-ai machine-learning python xai

Last synced: 3 months ago
JSON representation

CEML - Counterfactuals for Explaining Machine Learning models - A Python toolbox

• Host: GitHub
• URL: https://github.com/andreArtelt/ceml
• Owner: andreArtelt
• License: mit
• Created: 2019-07-11T13:53:35.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2024-07-27T17:45:24.000Z (6 months ago)
• Last Synced: 2024-10-03T16:50:54.510Z (4 months ago)
• Topics: counterfactual-explanations, explainable-ai, machine-learning, python, xai
• Language: Python
• Size: 263 KB
• Stars: 42
• Watchers: 3
• Forks: 11
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

• awesome-counterfactual-explanations - andreArtelt/ceml

README

        
****

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.5.0)

    - 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.

.. image:: docs/_static/cf_illustration.png

Installation

------------

**Note: Python 3.8 is required!**

Tested on Ubuntu -- note that some people reported problems with some dependencies on Windows!

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/ `_

License

-------

MIT license - See `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 `_

    - `scipy `_

    - `jax `_

    - `cvxpy `_

    - `scikit-learn `_

    - `sklearn-lvq `_

    - `PyTorch `_

    - `tensorflow `_