Skip to main content

Counterfactuals for explaining machine learning models - A Python toolbox

Project description

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

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:

git clone https://github.com/andreArtelt/ceml.git
cd ceml

Install all requirements (listed in requirements.txt):

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:

pip install .

Quick example

#!/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:

@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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

ceml-0.7-py3-none-any.whl (91.0 kB view details)

Uploaded Python 3

File details

Details for the file ceml-0.7-py3-none-any.whl.

File metadata

  • Download URL: ceml-0.7-py3-none-any.whl
  • Upload date:
  • Size: 91.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.8.18

File hashes

Hashes for ceml-0.7-py3-none-any.whl
Algorithm Hash digest
SHA256 94fb10bb367ce2d93c1e3976aaacec75e94bb3248eff77b7b1a8e36ee910a0c3
MD5 d2522d914055e3e0dd8348bf2a53a2e8
BLAKE2b-256 04e71e0043884354ddd25c56a421b1b06972fffc0cdd9b03d783b85aeb8b1b2d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page