Metadata-Version: 2.2
Name: RoCELib
Version: 0.2.3
Summary: RoCELib is an open-source Python library designed for benchmarking the robustness of counterfactual explanation (CE) methods.
Author-email: Ivan Artiukhov <ivan.artiukhov22@imperial.ac.uk>, Lorenzo Evans <lorenzo.evans22@imperial.ac.uk>, Shlok Shah <shlok.shah22@imperial.ac.uk>, Ayush Patel <ayush.patel22@imperial.ac.uk>, James Stadler <james.stadler22@imperial.ac.uk>, Seth Mack <seth.mack22@imperial.ac.uk>, Junqi Jiang <junqi.jiang20@imperial.ac.uk>, Luca Marzari <luca.marzari@univr.it>, Aaryan Purohit <aaryan.purohit22@imperial.ac.uk>, Francesco Leofante <f.leofante@imperial.ac.uk>
License: MIT License
        
        Copyright (c) 2024 Aaryan Purohit, Seth Mack, Lorenzo Evans, James Stadler, Shlok Shah, Ayush Patel and Ivan Artiukhov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/JStadl/RoCELib
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch==2.4.1
Requires-Dist: notebook
Requires-Dist: scikit-learn
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: tabulate
Requires-Dist: streamlit
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: clingo>=5.6.2
Requires-Dist: tensorflow==2.16.2
Requires-Dist: keras==3.0.5
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: gurobi
Requires-Dist: gurobipy==11.0.1; extra == "gurobi"

# RoCELib

The increasing use of machine learning models to aid decision-making in high-stakes industries like finance and
healthcare demands explainability to build trust. Counterfactual Explanations (CEs) provide valuable insights into model
predictions by showing how slight changes in input data could lead to different outcomes. A key aspect of CEs is their
robustness, which ensures that the desired outcomes remain stable even with minor alterations to the input. Robustness
is important since produced CEs should hold up in the future should the original model be altered or replaced.Despite
the importance of robustness, there has been a lack of standardised tools to comprehensively evaluate and compare robust
CE generation methods. To address this, **RoCELib** was developed as an open-source Python library aimed at benchmarking
the robustness of various CE methods. RoCELib provides a systematic framework for generating, evaluating, and comparing
CEs with a focus on robustness, enabling fair and effective benchmarking. The library is highly extensible, allowing for
custom models, datasets, and tools to be integrated, making it an essential tool for enhancing the reliability and
interpretability of machine learning models in critical applications.

## Features

- Standardises the evaluation and benchmarking of robust CEs.
- Supports multiple ML frameworks, including PyTorch, Keras, and scikit-learn.
- Extensible to incorporate custom models, datasets, CE methods, and evaluation metrics.
- Includes several robust CE generation algorithms (e.g., TRexNN, RNCE) and non-robust baselines (e.g., MCE, BLS).

## Setup

To set up do:

(1) Create a virtual environment in the root

```bash
python -m venv venv
```

(2) Activate it. (You may have to use a different command depending on your platform)

```bash
source venv/bin/activate
```

(3) Install the package from PyPi:

```bash
pip install rocelib
```

## Generating Docs

The documentation for RoCELib is automatically generated and hosted online. You can access the latest version here:

🔗 [RoCELib Documentation](https://jstadl.github.io/RoCELib/rocelib.html)

There is no need to manually build the documentation unless making local modifications. However, if you need to generate docs locally, navigate to `docs/source` and run:

```bash
make html
```

If that does not work, try:

```bash
sphinx-build -b html . _build/html
```

## Examples

Python notebooks demonstrating the usage of RoCELib are
available:
   - [An overview of all features](https://colab.research.google.com/github/JStadl/RoCELib/blob/main/examples/Tasks.ipynb).
   - [Showing how to use the example datasets include](https://colab.research.google.com/github/JStadl/RoCELib/blob/main/examples/ExampleDatasets.ipynb)
   - [Showing how to use your own datasets](https://colab.research.google.com/github/JStadl/RoCELib/blob/main/examples/CustomDatasets.ipynb)


## Release Process

For detailed instructions on publishing a new version of RoCELib to PyPI, refer to the [RELEASE.md](RELEASE.md) file in the repository. This file contains step-by-step guidance on versioning, tagging, and triggering the GitHub Action workflow for automated publishing.

## License

RoCELib is licensed under the MIT License. For more details, please refer to the `LICENSE` file in this repository.
