Metadata-Version: 2.4
Name: VCNet
Version: 0.1.3
Summary: Counterfactual generation
Author-email: Thomas Guyet <thomas.guyet@inria.fr>, Victor Guyomard <victor.guyomard@inria.fr>
Maintainer-email: Thomas Guyet <thomas.guyet@inria.fr>
License-Expression: LGPL-3.0-only
Project-URL: Homepage, https://gitlab.inria.fr/tguyet/vcnet/
Project-URL: Repository, https://gitlab.inria.fr/tguyet/vcnet.git
Project-URL: Issues, https://gitlab.inria.fr/tguyet/vcnet/-/issues
Project-URL: Documentation, https://tguyet.gitlabpages.inria.fr/vcnet
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: torch
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: lightning
Requires-Dist: xgboost
Dynamic: license-file

# VCNet: Variational Counter Net

This repository is contains an implementation of VCNet, a counterfactual generator for tabular datasets.
Counterfactual generation is an explainable artificial intelligence technique that helps users understand the decisions of predictive models.

VCNet handles both categorical and numerical variables and can also manage immutable variables (i.e., variables that cannot be changed while generating counterfactuals). Currently, it is implemented for binary classification only. VCNet is based on conditional variational encoders. Compared to its competitors (see for instance [jax-relax](https://github.com/BirkhoffG/jax-relax)), VCNet offers an easy and fast training architecture that generates realistic counterfactuals (i.e., counterfactuals that likely exist in the data distribution).

This library provides two versions of VCNet:
* **Joint-learning architecture:** This version includes both the classification model and the counterfactual generator.
* **Post-hoc architecture:** This version includes only the counterfactual generator, which can be fitted on any prediction model (Torch module).

Once the VCNet model is fitted, it can be used to generate efficiently valid counterfactuals of examples.


### Authors

This implementation is derived from the original work by V. Guyomard ([CARLA CROCO VCNet](https://github.com/Orange-OpenSource/carla_croco_vcnet)). It is implemented as a PyTorch Lightning module for easy integration into your own architecture.

* Victor Guyomard, Orange Labs
* Thomas Guyet, Inria, [AIstroSight](https://team.inria.fr/aistrosight/)


### How to install

The `pyproject.toml` is the project configuration file which enables to create and set up a virtual environment suitable to run `VCNet`.

1. Download the code from gitlab
```bash
git clone https://gitlab.inria.fr/tguyet/vcnet.git
cd vcnet
```

2. Install the dependencies

```bash
pip install -r requirements.txt
```

or, to install the package:
```bash
pip install -e .
```

3. Test VCNet on Adult dataset

```bash
python tests/test_data.py
```


For more details, look at the [documentation pages](https://tguyet.gitlabpages.inria.fr/vcnet).


### How to cite

```bibtex
@inproceedings{guyomard2022vcnet,
  title={VCNet: A self-explaining model for realistic counterfactual generation},
  author={Guyomard, Victor and Fessant, Fran{\c{c}}oise and Guyet, Thomas and Bouadi, Tassadit and Termier, Alexandre},
  booktitle={Joint European Conference on Machine Learning and Knowledge Discovery in Databases},
  pages={437--453},
  year={2022},
  organization={Springer}
}
```
