Metadata-Version: 2.1
Name: lrp_pf_auc
Version: 0.1.2
Summary: Explain Neural Networks using Layer-wise Relevance Propagation and evaluate the explanations using Pixel-Flipping and Area Under the Curve.
Home-page: https://github.com/rodrigobdz/lrp
Author: rodrigobdz
Author-email: r.bermudezschettino@campus.tu-berlin.de
Maintainer: rodrigobdz
Maintainer-email: r.bermudezschettino@campus.tu-berlin.de
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: GPU
Classifier: Framework :: IPython
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: license

# LRP

[![DOI](https://zenodo.org/badge/432443018.svg)](https://zenodo.org/badge/latestdoi/432443018)
[![PyPI Version](https://img.shields.io/pypi/v/lrp-pf-auc)](https://pypi.org/project/lrp-pf-auc/)
[![License](https://img.shields.io/badge/license-MIT-blue)](license)

Implementation of Layer-wise Relevance Propagation (LRP) algorithm together with quantitative evaluation metrics to compare heatmap explanations objectively.

## Features

Explainability:

- Layer-wise Relevance Propagation (LRP)

Quantitative Evaluation:

- Pixel Flipping (PF), also known as Region Perturbation (RP)
  - Perturbation modes:
    - inpainting
    - random
  - Sort objectives:
    - most relevant first (MoRF), also known as activation curve
    - least relevant first (LRF), also known as pruning curve
    - random
- AUC (Area Under the Curve), also known as AUAC (Area Under the Activation Curve) or AU-MSE (Area Under the Mean Squared Error Curve) depending on the sort objective

### Showcase

**LRP** ([lrp-tutorial](https://git.tu-berlin.de/gmontavon/lrp-tutorial) composite) and **PF** with **inpainting** perturbation mode and sort objective **MoRF**.

<p align="center" width="100%">
    <img width="65%" src="https://github.com/rodrigobdz/lrp/blob/main/docs/images/castle-lrp-pf-auc-inpainting.png?raw=true">
</p>

Classification scores of castle image with **inpainting** perturbation mode

<p align="center" width="100%">
    <img width="65%" src="https://github.com/rodrigobdz/lrp/blob/main/docs/images/castle-pf-auc-inpainting.png?raw=true">
</p>

Number of simultaneous flips per perturbation step during Pixel-Flipping.

<p align="center" width="100%">
    <img width="65%" src="https://github.com/rodrigobdz/lrp/blob/main/docs/images/castle-pf-perturbation-steps.png?raw=true">
</p>

---

<details>
<summary>PF perturbation mode random</summary>
<p>

**LRP** ([lrp-tutorial](https://git.tu-berlin.de/gmontavon/lrp-tutorial) composite) and **PF** with **random** perturbation mode and sort objective **MoRF**.

<p align="center" width="100%">
    <img width="65%" src="https://github.com/rodrigobdz/lrp/blob/main/docs/images/castle-lrp-pf-auc-random.png?raw=true">
</p>

Classification scores of castle image with random perturbation mode

<p align="center" width="100%">
    <img width="65%" src="https://github.com/rodrigobdz/lrp/blob/main/docs/images/castle-pf-auc-random.png?raw=true">
</p>

</p>
</details>

## Requirements

- `python3` >= 3.9

## Installation

```sh
python3 -m pip install lrp-pf-auc
```

The PyPI distribution `lrp-pf-auc` provides the following two packages: `lrp` and `pf`.

The package name refers to Layer-wise Relevance Propagation (LRP), Pixel Flipping (PF), and Area Under the Curve (AUC) respectively.

## Usage

Refer to [demo.ipynb](demo.ipynb) for an example of Layer-wise Relevance Propagation (LRP), Pixel-Flipping (PF) and Area under the Curve (AUC).

## Related Projects

- Sequential LRP implementation: [gmontavon/lrp-tutorial](https://git.tu-berlin.de/gmontavon/lrp-tutorial)
  > Tutorial on how to implement LRP
- Updated version of `gmontavon/lrp-tutorial`: [rodrigobdz/lrp-tutorial](https://git.tu-berlin.de/rodrigobdz/lrp-tutorial)
- Forward-hook LRP implementation: [chr5tphr/zennit](https://github.com/chr5tphr/zennit)
  > Implementation of LRP-based methods in PyTorch
- [`innvestigate`](https://github.com/albermax/innvestigate)-based LRP implementation: [moboehle/Pytorch-LRP](https://github.com/moboehle/Pytorch-LRP)
- Caffe-based LRP implementation: [`lrp_toolbox`](https://github.com/sebastian-lapuschkin/lrp_toolbox)
- Pixel-Flipping and Region Perturbation implementation: [understandable-machine-intelligence-lab/Quantus](https://github.com/understandable-machine-intelligence-lab/Quantus)

## Citation

Cite as:

- Plaintext:

  > Rodrigo Bermúdez Schettino. (2022). rodrigobdz/lrp: v0.1.2 (v0.1.2). Zenodo. https://doi.org/10.5281/zenodo.6814117

- BibTeX:

  ```text
  @software{rodrigo_bermudez_schettino_2022_6814117,
    author       = {Rodrigo Bermúdez Schettino},
    title        = {rodrigobdz/lrp: v0.1.2},
    month        = jul,
    year         = 2022,
    publisher    = {Zenodo},
    version      = {v0.1.2},
    doi          = {10.5281/zenodo.6814117},
    url          = {https://doi.org/10.5281/zenodo.6814117}
  }
  ```

## Credits

- The structure of this readme is based on [minimal-readme](https://github.com/rodrigobdz/minimal-readme)

This implementation is based on insights from:

- LRP overview paper

  > G. Montavon, A. Binder, S. Lapuschkin, W. Samek, K.-R. Müller
  > [Layer-wise Relevance Propagation: An Overview](https://doi.org/10.1007/978-3-030-28954-6_10)
  > in Explainable AI: Interpreting, Explaining and Visualizing Deep Learning, Springer LNCS, vol. 11700, 2019

- Original LRP paper

  > S. Bach, A. Binder, G. Montavon, F. Klauschen, K.-R. Müller, W. Samek
  > [On pixel-wise explanations for non-linear classifier decisions by layer-wise relevance propagation](https://doi.org/10.1371/journal.pone.0130140)
  > PloS ONE 10 (7), e0130140, 2015

- [ECML/PKDD 2020 Tutorial: Explainable AI for Deep Networks: Basics and Extensions (Part 3)](http://heatmapping.org/slides/2020_ECML_3.pdf)

## License

[MIT](LICENSE) © [rodrigobdz](https://github.com/rodrigobdz/)
