README.md

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

• Plotting (notebook): Source

Available Datasets

• Adult Data Set: Source
• COMPAS: Source
• Give Me Some Credit (GMC): Source

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.