A library for counterfactual recourse
Project description
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
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:
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9f4d4cccae60308354326fd0aac06999beb25924e9d069a446f49a159459992b |
|
MD5 | b26a5c65ef86ca0e73a652b51df98dbc |
|
BLAKE2b-256 | e69c955901a866220648d3363061f93004e63b38dbd0fbfcd15d7894943bc7ae |
File details
Details for the file carla_recourse-0.0.5-py3-none-any.whl
.
File metadata
- Download URL: carla_recourse-0.0.5-py3-none-any.whl
- Upload date:
- Size: 138.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.0 CPython/3.9.12
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | bb5af5f1a2b87c9a61f92ad73156f78842282f5cdc1ba3670613bb7aa3956e94 |
|
MD5 | 290b8d0729c3e5da2d373c7f9eeb8c17 |
|
BLAKE2b-256 | 95dfe0f8f7ccb5f7527f48210be3f52ed1b69ac5e6f04eac5169dc0f368f918f |