Skip to content

Commit 5ce2f95

Browse files
adrhilladrhill
authored
Update README
Closes #158.
1 parent e1614a5 commit 5ce2f95

File tree

1 file changed

+31
-49
lines changed

1 file changed

+31
-49
lines changed

‎README.md‎

Lines changed: 31 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,13 @@ ___
77

88
Explainable AI in Julia.
99

10-
This package implements interpretability methods for black box models,
11-
with a focus on local explanations and attribution maps in input space.
10+
This package implements interpretability methods for black-box classifiers,
11+
with an emphasis on local explanations and attribution maps in input space.
12+
The only requirement for the model is that it is differentiable[^1].
1213
It is similar to [Captum][captum-repo] and [Zennit][zennit-repo] for PyTorch
1314
and [iNNvestigate][innvestigate-repo] for Keras models.
1415

15-
Most of the implemented methods only require the model to be differentiable with [Zygote](https://github.com/FluxML/Zygote.jl).
16-
Layerwise Relevance Propagation (LRP) is implemented for use with [Flux.jl](https://fluxml.ai) models.
16+
[^1]: More specifically, models currently have to be differentiable with [Zygote.jl](https://github.com/FluxML/Zygote.jl).
1717

1818
## Installation
1919
This package supports Julia ≥1.6. To install it, open the Julia REPL and run
@@ -22,30 +22,20 @@ julia> ]add ExplainableAI
2222
```
2323

2424
## Example
25-
Let's use LRP to explain why an image of a castle gets classified as such
26-
using a pre-trained VGG16 model from [Metalhead.jl](https://github.com/FluxML/Metalhead.jl):
25+
Let's explain why an image of a castle gets classified as such by a vision model:
2726

2827
![][castle]
2928

3029
```julia
3130
using ExplainableAI
32-
using Flux
33-
using Metalhead # pre-trained vision models
34-
using HTTP, FileIO, ImageMagick # load image from URL
35-
using ImageInTerminal # show heatmap in terminal
3631

37-
# Load model
38-
model = VGG(16, pretrain=true).layers
39-
model = strip_softmax(model)
40-
model = canonize(model)
41-
42-
# Load input
43-
input = ... # input in WHCN format
32+
# Load model and input
33+
model = ... # load classifier model
34+
input = ... # input in batch-dimension-last format
4435

4536
# Run XAI method
46-
composite = EpsilonPlusFlat()
47-
analyzer = LRP(model, composite)
48-
expl = analyze(input, analyzer) # or: expl = analyzer(input)
37+
analyzer = SmoothGrad(model)
38+
expl = analyze(input, analyzer) # or: analyzer(input)
4939

5040
# Show heatmap
5141
heatmap(expl)
@@ -68,19 +58,27 @@ whereas regions in blue are of negative relevance.
6858

6959
| **Analyzer** | **Heatmap for class "castle"** |**Heatmap for class "street sign"** |
7060
|:--------------------------------------------- |:------------------------------:|:----------------------------------:|
71-
| `LRP` with `EpsilonPlus` composite | ![][castle-comp-ep] | ![][streetsign-comp-ep] |
72-
| `LRP` with `EpsilonPlusFlat` composite | ![][castle-comp-epf] | ![][streetsign-comp-epf] |
73-
| `LRP` with `EpsilonAlpha2Beta1` composite | ![][castle-comp-eab] | ![][streetsign-comp-eab] |
74-
| `LRP` with `EpsilonAlpha2Beta1Flat` composite | ![][castle-comp-eabf] | ![][streetsign-comp-eabf] |
75-
| `LRP` with `EpsilonGammaBox` composite | ![][castle-comp-egb] | ![][streetsign-comp-egb] |
76-
| `LRP` | ![][castle-lrp] | ![][streetsign-lrp] |
7761
| `InputTimesGradient` | ![][castle-ixg] | ![][streetsign-ixg] |
7862
| `Gradient` | ![][castle-grad] | ![][streetsign-grad] |
7963
| `SmoothGrad` | ![][castle-smoothgrad] | ![][streetsign-smoothgrad] |
8064
| `IntegratedGradients` | ![][castle-intgrad] | ![][streetsign-intgrad] |
8165

8266
The code used to generate these heatmaps can be found [here][asset-code].
8367

68+
> [!WARNING]
69+
> ExplainableAI.jl used to contain Layer-wise Relevance Propagation (LRP).
70+
> Since version `v0.7.0`, LRP is now available as part of a separate package in the Julia-XAI ecosystem,
71+
> called [RelevancePropagation.jl](https://github.com/Julia-XAI/RelevancePropagation.jl).
72+
>
73+
> | **Analyzer** | **Heatmap for class "castle"** |**Heatmap for class "street sign"** |
74+
> |:--------------------------------------------- |:------------------------------:|:----------------------------------:|
75+
> | `LRP` with `EpsilonPlus` composite | ![][castle-comp-ep] | ![][streetsign-comp-ep] |
76+
> | `LRP` with `EpsilonPlusFlat` composite | ![][castle-comp-epf] | ![][streetsign-comp-epf] |
77+
> | `LRP` with `EpsilonAlpha2Beta1` composite | ![][castle-comp-eab] | ![][streetsign-comp-eab] |
78+
> | `LRP` with `EpsilonAlpha2Beta1Flat` composite | ![][castle-comp-eabf] | ![][streetsign-comp-eabf] |
79+
> | `LRP` with `EpsilonGammaBox` composite | ![][castle-comp-egb] | ![][streetsign-comp-egb] |
80+
> | `LRP` | ![][castle-lrp] | ![][streetsign-lrp] |
81+
8482
## Video demonstration
8583
Check out our talk at JuliaCon 2022 for a demonstration of the package.
8684

@@ -93,29 +91,10 @@ Currently, the following analyzers are implemented:
9391
* `InputTimesGradient`
9492
* `SmoothGrad`
9593
* `IntegratedGradients`
96-
* `LRP`
97-
* Rules
98-
* `ZeroRule`
99-
* `EpsilonRule`
100-
* `GammaRule`
101-
* `GeneralizedGammaRule`
102-
* `WSquareRule`
103-
* `FlatRule`
104-
* `ZBoxRule`
105-
* `ZPlusRule`
106-
* `AlphaBetaRule`
107-
* `PassRule`
108-
* Composites
109-
* `EpsilonGammaBox`
110-
* `EpsilonPlus`
111-
* `EpsilonPlusFlat`
112-
* `EpsilonAlpha2Beta1`
113-
* `EpsilonAlpha2Beta1Flat`
114-
* `CRP`
115-
116-
One of the design goals of ExplainableAI.jl is extensibility.
117-
Custom [composites][docs-composites] are easily defined
118-
and the package is easily extended by [custom rules][docs-custom-rules].
94+
95+
One of the design goals of the [Julia-XAI ecosystem][juliaxai-docs] is extensibility.
96+
To implement an XAI method, take a look at the [common interface
97+
defined in XAIBase.jl][xaibase-docs].
11998

12099
## Roadmap
121100
In the future, we would like to include:
@@ -131,6 +110,9 @@ Contributions are welcome!
131110
> for the Berlin Institute for the Foundations of Learning and Data (BIFOLD) (01IS18037A).
132111
133112
[banner-img]: https://raw.githubusercontent.com/Julia-XAI/ExplainableAI.jl/gh-pages/assets/banner.png
113+
[juliaxai-docs]: https://julia-xai.github.io/XAIDocs/
114+
[xaibase-docs]: https://julia-xai.github.io/XAIDocs/XAIBase/
115+
134116

135117
[asset-code]: https://github.com/Julia-XAI/ExplainableAI.jl/blob/gh-pages/assets/heatmaps/generate_assets.jl
136118
[castle]: https://raw.githubusercontent.com/Julia-XAI/ExplainableAI.jl/gh-pages/assets/heatmaps/castle.jpg

0 commit comments

Comments
 (0)