Skip to main content

A library for counterfactual recourse

Project description

PyPI - Python Version GitHub Workflow Status Read the Docs Code style: black

CARLA - Counterfactual And Recourse Library

CARLA is a python library to benchmark counterfactual explanation and recourse models. It comes out-of-the box with commonly used datasets and various machine learning models. Designed with extensibility in mind: Easily include your own counterfactual methods, new machine learning models or other datasets.

Find extensive documentation here! Our arXiv paper can be found here.

Notebooks / Examples

Available Datasets

Implemented Counterfactual Methods

  • Actionable Recourse (AR): Paper
  • CCHVAE: Paper
  • Contrastive Explanations Method (CEM): Paper
  • Counterfactual Latent Uncertainty Explanations (CLUE): Paper
  • CRUDS: Paper
  • Diverse Counterfactual Explanations (DiCE): Paper
  • Feasible and Actionable Counterfactual Explanations (FACE): Paper
  • Growing Sphere (GS): Paper
  • Revise: Paper
  • Wachter: Paper
  • FOCUS: Paper
  • FeatureTweak: Paper

Provided Machine Learning Models

  • ANN: Artificial Neural Network with 2 hidden layers and ReLU activation function
  • LR: Linear Model with no hidden layer and no activation function

Which Recourse Methods work with which ML framework?

The framework a counterfactual method currently works with is dependent on its underlying implementation. It is planned to make all recourse methods available for all ML frameworks . The latest state can be found here:

Recourse Method Tensorflow Pytorch SKlearn XGBoost
Actionable Recourse X X
Causal X X
CCHVAE X
CEM X
CLUE X
CRUDS X
DiCE X X
FACE X X
FeatureTweak X X
FOCUS X X
Growing Spheres X X
Revise X
Wachter X

Installation

Requirements

  • python3.7
  • pip

Install via pip

pip install carla-recourse

Usage Example

from carla import OnlineCatalog, MLModelCatalog
from carla.recourse_methods import GrowingSpheres

# load a catalog dataset
data_name = "adult"
dataset = OnlineCatalog(data_name)

# load artificial neural network from catalog
model = MLModelCatalog(dataset, "ann")

# get factuals from the data to generate counterfactual examples
factuals = dataset.raw.iloc[:10]

# load a recourse model and pass black box model
gs = GrowingSpheres(model)

# generate counterfactual examples
counterfactuals = gs.get_counterfactuals(factuals)

Contributing

Requirements

  • python3.7-venv (when not already shipped with python3.7)
  • Recommended: GNU Make

Installation

Using make:

make requirements

Using python directly or within activated virtual environment:

pip install -U pip setuptools wheel
pip install -e .

Testing

Using make:

make test

Using python directly or within activated virtual environment:

pip install -r requirements-dev.txt
python -m pytest test/*

Linting and Styling

We use pre-commit hooks within our build pipelines to enforce:

  • Python linting with flake8.
  • Python styling with black.

Install pre-commit with:

make install-dev

Using python directly or within activated virtual environment:

pip install -r requirements-dev.txt
pre-commit install

Licence

carla is under the MIT Licence. See the LICENCE for more details.

Citation

This project was recently accepted to NeurIPS 2021 (Benchmark & Data Sets Track). If you use this codebase, please cite:

@misc{pawelczyk2021carla,
      title={CARLA: A Python Library to Benchmark Algorithmic Recourse and Counterfactual Explanation Algorithms},
      author={Martin Pawelczyk and Sascha Bielawski and Johannes van den Heuvel and Tobias Richter and Gjergji Kasneci},
      year={2021},
      eprint={2108.00783},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

Please also cite the original authors' work.

Project details


Download files

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

Source Distribution

carla-recourse-0.0.5.tar.gz (102.7 kB view details)

Uploaded Source

Built Distribution

carla_recourse-0.0.5-py3-none-any.whl (138.4 kB view details)

Uploaded Python 3

File details

Details for the file carla-recourse-0.0.5.tar.gz.

File metadata

  • Download URL: carla-recourse-0.0.5.tar.gz
  • Upload date:
  • Size: 102.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.0 CPython/3.9.12

File hashes

Hashes for carla-recourse-0.0.5.tar.gz
Algorithm Hash digest
SHA256 9f4d4cccae60308354326fd0aac06999beb25924e9d069a446f49a159459992b
MD5 b26a5c65ef86ca0e73a652b51df98dbc
BLAKE2b-256 e69c955901a866220648d3363061f93004e63b38dbd0fbfcd15d7894943bc7ae

See more details on using hashes here.

File details

Details for the file carla_recourse-0.0.5-py3-none-any.whl.

File metadata

File hashes

Hashes for carla_recourse-0.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 bb5af5f1a2b87c9a61f92ad73156f78842282f5cdc1ba3670613bb7aa3956e94
MD5 290b8d0729c3e5da2d373c7f9eeb8c17
BLAKE2b-256 95dfe0f8f7ccb5f7527f48210be3f52ed1b69ac5e6f04eac5169dc0f368f918f

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