{"id":21922686,"url":"https://github.com/carla-recourse/carla","last_synced_at":"2025-04-05T03:11:05.148Z","repository":{"id":37785109,"uuid":"320088616","full_name":"carla-recourse/CARLA","owner":"carla-recourse","description":"CARLA: A Python Library to Benchmark Algorithmic Recourse and Counterfactual Explanation Algorithms","archived":false,"fork":false,"pushed_at":"2023-10-02T12:09:17.000Z","size":1980,"stargazers_count":263,"open_issues_count":19,"forks_count":60,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-04-26T03:02:45.510Z","etag":null,"topics":["artificial-intelligence","benchmark","benchmarking","counterfactual","counterfactual-explanations","counterfactuals","explainability","explainable-ai","explainable-ml","machine-learning","python","pytorch","recourse","tensorflow","tensorflow2"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carla-recourse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-12-09T21:52:38.000Z","updated_at":"2024-03-25T23:37:17.000Z","dependencies_parsed_at":"2023-02-09T12:45:40.070Z","dependency_job_id":"be41bf39-824a-4e3d-b6a0-95ce250d7142","html_url":"https://github.com/carla-recourse/CARLA","commit_stats":{"total_commits":121,"total_committers":7,"mean_commits":"17.285714285714285","dds":0.5950413223140496,"last_synced_commit":"24db00aa8616eb2faedea0d6edf6e307cee9d192"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carla-recourse%2FCARLA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carla-recourse%2FCARLA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carla-recourse%2FCARLA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carla-recourse%2FCARLA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carla-recourse","download_url":"https://codeload.github.com/carla-recourse/CARLA/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","benchmark","benchmarking","counterfactual","counterfactual-explanations","counterfactuals","explainability","explainable-ai","explainable-ml","machine-learning","python","pytorch","recourse","tensorflow","tensorflow2"],"created_at":"2024-11-28T21:06:06.410Z","updated_at":"2025-04-05T03:11:05.122Z","avatar_url":"https://github.com/carla-recourse.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/carla-recourse?style=for-the-badge)](https://pypi.org/project/carla-recourse/) ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/carla-recourse/CARLA/CI?style=for-the-badge) [![Read the Docs](https://img.shields.io/readthedocs/carla-counterfactual-and-recourse-library?style=for-the-badge)](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/?badge=latest) ![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge)\n\n# CARLA - Counterfactual And Recourse Library\n\n\u003cimg align=\"right\" width=\"240\" height=\"200\" src=\"https://github.com/carla-recourse/CARLA/blob/main/images/carla_logo_square.png?raw=true\"\u003e\n\nCARLA 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](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/)! Our arXiv paper can be found [here](https://arxiv.org/pdf/2108.00783.pdf).\n\n**What is algorithmic recourse?** As machine learning (ML) models are increasingly being deployed in high-stakes applications, there has been growing interest in providing recourse to individuals adversely impacted by model predictions (e.g., below we depict the canonical recourse example for an applicant whose loan has been denied). This library provides a starting point for researchers and practitioners alike, who wish to understand the inner workings of various counterfactual explanation and recourse methods and their underlying assumptions that went into the design of these methods.\n\n\n\n![motivating example](https://github.com/carla-recourse/CARLA/blob/main/images/motivating_cartoon.png?raw=true)\n\n\n\n### Notebooks / Examples\n\n- Getting Started (notebook): [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/notebooks/how_to_use_carla.html)\n- Causal Recourse (notebook): [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/notebooks/how_to_use_carla_causal.html)\n- Plotting (notebook): [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/feature-plotting/notebooks/plotting_example.html)\n- Benchmarking (notebook): [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/notebooks/benchmark_example.html)\n- Adding your own Data: [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/examples.html#data)\n- Adding your own ML-Model: [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/examples.html#black-box-model)\n- Adding your own Recourse Method: [Source](https://carla-counterfactual-and-recourse-library.readthedocs.io/en/latest/examples.html#recourse-method)\n\n\n### Available Datasets\n\n| Name                | Source                                                                                       |\n|---------------------|----------------------------------------------------------------------------------------------|\n| Adult               | [Source](https://archive.ics.uci.edu/ml/datasets/adult)                                      |\n| COMPAS              | [Source](https://www.kaggle.com/danofer/compass)                                             |\n| Give Me Some Credit | [Source](https://www.kaggle.com/c/GiveMeSomeCredit/data)                                     |\n| HELOC               | [Source](https://community.fico.com/s/explainable-machine-learning-challenge?tabset-158d9=2) |\n\n### Provided Machine Learning Models\n\n| Model        |                                 Description                                  | Tensorflow | Pytorch | Sklearn | XGBoost |\n|--------------|:----------------------------------------------------------------------------:|:----------:|:-------:|:-------:|:-------:|\n| ANN          | Artificial Neural Network with 2 hidden layers and ReLU activation function. |     X      |    X    |         |         |\n| LR           |        Linear Model with no hidden layer and no activation function.         |     X      |    X    |         |         |\n| RandomForest |                             Tree Ensemble Model.                             |            |         |    X    |         |\n| XGBoost      |                              Gradient boosting.                              |            |         |         |    X    |\n\n### Implemented Counterfactual methods\nThe framework a counterfactual method currently works with is dependent on its underlying implementation.\nIt is planned to make all recourse methods available for all ML frameworks . The latest state can be found here:\n\n| Recourse Method                                            | Paper                                                            | Tensorflow | Pytorch | SKlearn | XGBoost |\n|------------------------------------------------------------|:-----------------------------------------------------------------|:----------:|:-------:|:-------:|:-------:|\n| Actionable Recourse (AR)                                   | [Source](https://arxiv.org/pdf/1809.06514.pdf)                   |     X      |    X    |         |         |\n| Causal Recourse                                            | [Source](https://arxiv.org/abs/2002.06278.pdf)                   |     X      |    X    |         |         |\n| CCHVAE                                                     | [Source](https://arxiv.org/pdf/1910.09398.pdf)                   |            |    X    |         |         |\n| Contrastive Explanations Method (CEM)                      | [Source](https://arxiv.org/pdf/1802.07623.pdf)                   |     X      |         |         |         |\n| Counterfactual Latent Uncertainty Explanations (CLUE)      | [Source](https://arxiv.org/pdf/2006.06848.pdf)                   |            |    X    |         |         |\n| CRUDS                                                      | [Source](https://finale.seas.harvard.edu/files/finale/files/cruds-_counterfactual_recourse_using_disentangled_subspaces.pdf)                                                       |            |    X    |         |         |\n| Diverse Counterfactual Explanations (DiCE)                 | [Source](https://arxiv.org/pdf/1905.07697.pdf)                   |     X      |    X    |         |         |\n| Feasible and Actionable Counterfactual Explanations (FACE) | [Source](https://arxiv.org/pdf/1909.09369.pdf)                   |     X      |    X    |         |         |\n| FeatureTweak                                               | [Source](https://arxiv.org/pdf/1706.06691.pdf)                   |            |         |    X    |    X    |\n| FOCUS                                                      | [Source](https://arxiv.org/pdf/1911.12199.pdf)                   |            |         |    X    |    X    |\n| Growing Spheres (GS)                                       | [Source](https://arxiv.org/pdf/1712.08443.pdf)                   |     X      |    X    |         |         |\n| Revise                                                     | [Source](https://arxiv.org/pdf/1907.09615.pdf)                   |            |    X    |         |         |\n| Wachter                                                    | [Source](https://arxiv.org/ftp/arxiv/papers/1711/1711.00399.pdf) |            |    X    |         |         |\n\n## Installation\n\n### Requirements\n\n- `python3.7`\n- `pip`\n\n### Install via pip\n\n```sh\npip install carla-recourse\n```\n\n## Quickstart\n\n\n```python\nfrom carla import OnlineCatalog, MLModelCatalog\nfrom carla.recourse_methods import GrowingSpheres\n\n# load a catalog dataset\ndata_name = \"adult\"\ndataset = OnlineCatalog(data_name)\n\n# load artificial neural network from catalog\nmodel = MLModelCatalog(dataset, \"ann\")\n\n# get factuals from the data to generate counterfactual examples\nfactuals = dataset.raw.iloc[:10]\n\n# load a recourse model and pass black box model\ngs = GrowingSpheres(model)\n\n# generate counterfactual examples\ncounterfactuals = gs.get_counterfactuals(factuals)\n```\n\n\n## Contributing\n\n### Requirements\n\n- `python3.7-venv` (when not already shipped with python3.7)\n- Recommended: [GNU Make](https://www.gnu.org/software/make/)\n\n### Installation\n\nUsing make:\n\n```sh\nmake requirements\n```\n\nUsing python directly or within activated virtual environment:\n\n```sh\npip install -U pip setuptools wheel\npip install -e .\n```\n\n### Testing\n\nUsing make:\n\n```sh\nmake test\n```\n\nUsing python directly or within activated virtual environment:\n\n```sh\npip install -r requirements-dev.txt\npython -m pytest test/*\n```\n\n### Linting and Styling\n\nWe use pre-commit hooks within our build pipelines to enforce:\n\n- Python linting with [flake8](https://flake8.pycqa.org/en/latest/).\n- Python styling with [black](https://github.com/psf/black).\n\nInstall pre-commit with:\n\n```sh\nmake install-dev\n```\n\nUsing python directly or within activated virtual environment:\n\n```sh\npip install -r requirements-dev.txt\npre-commit install\n```\n\n## Licence\n\ncarla is under the MIT Licence. See the [LICENCE](github.com/indyfree/carla/blob/master/LICENSE) for more details.\n\n## Citation\n\nThis project was recently accepted to NeurIPS 2021 (Benchmark \u0026 Data Sets Track).\nIf you use this codebase, please cite:\n\n```sh\n@misc{pawelczyk2021carla,\n      title={CARLA: A Python Library to Benchmark Algorithmic Recourse and Counterfactual Explanation Algorithms},\n      author={Martin Pawelczyk and Sascha Bielawski and Johannes van den Heuvel and Tobias Richter and Gjergji Kasneci},\n      year={2021},\n      eprint={2108.00783},\n      archivePrefix={arXiv},\n      primaryClass={cs.LG}\n}\n```\n\nPlease also cite the original authors' work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarla-recourse%2Fcarla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarla-recourse%2Fcarla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarla-recourse%2Fcarla/lists"}