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.

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

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
Actionable Recourse X X
CCHVAE X
CEM X
CLUE X
CRUDS X
DiCE X X
FACE 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 DataCatalog, MLModelCatalog
from carla.recourse_methods import GrowingSpheres

# load a catalog dataset
data_name = "adult"
dataset = DataCatalog(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}
}

GitHub

https://github.com/carla-recourse/CARLA