Data

Tools

Indexes

Applications

Experiments

Open Source Science

https://github.com/andreartelt/ceml

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

https://github.com/andreartelt/ceml

Science Score: 23.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ○
    .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    1 of 3 committers (33.3%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (13.5%) to scientific vocabulary

Keywords

counterfactual-explanations explainable-ai machine-learning python xai

Keywords from Contributors

labels
Last synced: 6 months ago · JSON representation

Repository

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

Basic Info
  • Host: GitHub
  • Owner: andreArtelt
  • License: mit
  • Language: Python
  • Default Branch: master
  • Size: 265 KB
Statistics
  • Stars: 44
  • Watchers: 2
  • Forks: 11
  • Open Issues: 3
  • Releases: 11
Topics
counterfactual-explanations explainable-ai machine-learning python xai
Created over 6 years ago · Last pushed 9 months ago
Metadata Files
Readme License

README.rst 

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

Owner

  • Name: André Artelt
  • Login: andreArtelt
  • Kind: user
  • Location: Germany
  • Company: Bielefeld University

PhD student

GitHub Events

Total
  • Watch event: 2
  • Issue comment event: 1
  • Pull request event: 3
  • Create event: 2
Last Year
  • Watch event: 2
  • Issue comment event: 1
  • Pull request event: 3
  • Create event: 2

Committers

Last synced: almost 3 years ago

All Time
  • Total Commits: 131
  • Total Committers: 3
  • Avg Commits per committer: 43.667
  • Development Distribution Score (DDS): 0.069
Top Committers
Name Email Commits
André Artelt a****t@t****e 122
dependabot[bot] 4****]@u****m 7
André Artelt a****t@u****m 2
Committer Domains (Top 20 + Academic)
techfak.uni-bielefeld.de: 1

Issues and Pull Requests

Last synced: 8 months ago

All Time
  • Total issues: 7
  • Total pull requests: 17
  • Average time to close issues: 17 days
  • Average time to close pull requests: 2 months
  • Total issue authors: 6
  • Total pull request authors: 1
  • Average comments per issue: 1.29
  • Average comments per pull request: 0.41
  • Merged pull requests: 9
  • Bot issues: 0
  • Bot pull requests: 17
Past Year
  • Issues: 0
  • Pull requests: 3
  • Average time to close issues: N/A
  • Average time to close pull requests: 22 days
  • Issue authors: 0
  • Pull request authors: 1
  • Average comments per issue: 0
  • Average comments per pull request: 0.33
  • Merged pull requests: 1
  • Bot issues: 0
  • Bot pull requests: 3
View more stats
Top Authors
Issue Authors
  • whiletruelearn (2)
  • wangyongjie-ntu (1)
  • arsine1996 (1)
  • VinuraD (1)
  • Bharat-Kunj-Gupta (1)
  • nicholascannon (1)
Pull Request Authors
  • dependabot[bot] (21)
Top Labels
Issue Labels
enhancement (2) documentation (2) question (1)
Pull Request Labels
dependencies (21) python (4)

Packages

  • Total packages: 3
  • Total downloads:
    • pypi 87 last-month
  • Total dependent packages: 0
    (may contain duplicates)
  • Total dependent repositories: 1
    (may contain duplicates)
  • Total versions: 27
  • Total maintainers: 1
proxy.golang.org: github.com/andreartelt/ceml
  • Versions: 8
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.5%
Average: 5.7%
Dependent repos count: 5.8%
Last synced: 7 months ago
proxy.golang.org: github.com/andreArtelt/ceml
  • Versions: 8
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.5%
Average: 5.7%
Dependent repos count: 5.8%
Last synced: 7 months ago
pypi.org: ceml

Counterfactuals for explaining machine learning models - A Python toolbox

  • Versions: 11
  • Dependent Packages: 0
  • Dependent Repositories: 1
  • Downloads: 87 Last month
Rankings
Dependent packages count: 10.1%
Stargazers count: 11.0%
Forks count: 11.4%
Average: 15.8%
Dependent repos count: 21.6%
Downloads: 24.9%
Maintainers (1)
andreArtelt
Last synced: 7 months ago

Dependencies

docs/requirements.txt pypi
  • sphinx ==2.1.2
  • sphinx-rtd-theme ==0.4.3
requirements-dev.txt pypi
  • pytest ==5.0.1 development
  • sphinx ==2.1.2 development
  • sphinx-rtd-theme ==0.4.3 development
requirements.txt pypi
  • cvxpy ==1.1.0
  • jax ==0.2.17
  • jaxlib ==0.1.69
  • numpy ==1.19.5
  • scikit-learn ==0.24.2
  • scipy ==1.4.1
  • sklearn-lvq ==1.1.1
  • tensorflow ==2.5.2
  • torch ==1.7.1