Package: carla-recourse
CARLA - Counterfactual And Recourse LibraryCARLA 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 documentationhere!
Our arXiv paper can be foundhere.Notebooks / ExamplesPlotting (notebook):SourceAvailable DatasetsAdult Data Set:SourceCOMPAS:SourceGive Me Some Credit (GMC):SourceImplemented Counterfactual MethodsActionable Recourse (AR):PaperCCHVAE:PaperContrastive Explanations Method (CEM):PaperCounterfactual Latent Uncertainty Explanations (CLUE):PaperCRUDS:PaperDiverse Counterfactual Explanations (DiCE):PaperFeasible and Actionable Counterfactual Explanations (FACE):PaperGrowing Sphere (GS):PaperRevise:PaperWachter:PaperFOCUS:PaperFeatureTweak:PaperProvided Machine Learning ModelsANN: Artificial Neural Network with 2 hidden layers and ReLU activation functionLR: Linear Model with no hidden layer and no activation functionWhich 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 MethodTensorflowPytorchSKlearnXGBoostActionable RecourseXXCausalXXCCHVAEXCEMXCLUEXCRUDSXDiCEXXFACEXXFeatureTweakXXFOCUSXXGrowing SpheresXXReviseXWachterXInstallationRequirementspython3.7pipInstall via pippipinstallcarla-recourseUsage ExamplefromcarlaimportOnlineCatalog,MLModelCatalogfromcarla.recourse_methodsimportGrowingSpheres# load a catalog datasetdata_name="adult"dataset=OnlineCatalog(data_name)# load artificial neural network from catalogmodel=MLModelCatalog(dataset,"ann")# get factuals from the data to generate counterfactual examplesfactuals=dataset.raw.iloc[:10]# load a recourse model and pass black box modelgs=GrowingSpheres(model)# generate counterfactual examplescounterfactuals=gs.get_counterfactuals(factuals)ContributingRequirementspython3.7-venv(when not already shipped with python3.7)Recommended:GNU MakeInstallationUsing make:makerequirementsUsing python directly or within activated virtual environment:pipinstall-Upipsetuptoolswheel
pipinstall-e.TestingUsing make:maketestUsing python directly or within activated virtual environment:pipinstall-rrequirements-dev.txt
python-mpytesttest/*Linting and StylingWe use pre-commit hooks within our build pipelines to enforce:Python linting withflake8.Python styling withblack.Install pre-commit with:makeinstall-devUsing python directly or within activated virtual environment:pipinstall-rrequirements-dev.txt
pre-commitinstallLicencecarla is under the MIT Licence. See theLICENCEfor more details.CitationThis project was recently accepted to NeurIPS 2021 (Benchmark & Data Sets Track).
If you use this codebase, please cite:@misc{pawelczyk2021carla,title={CARLA:APythonLibrarytoBenchmarkAlgorithmicRecourseandCounterfactualExplanationAlgorithms},author={MartinPawelczykandSaschaBielawskiandJohannesvandenHeuvelandTobiasRichterandGjergjiKasneci},year={2021},eprint={2108.00783},archivePrefix={arXiv},primaryClass={cs.LG}}Please also cite the original authors' work.