Move LRP into RelevancePropagation.jl (#157)

Author: adrhill

Project.toml

@@ -4,38 +4,22 @@ authors = ["Adrian Hill <[email protected]>"]
 version = "1.0.0-DEV"
 
 [deps]
-ColorSchemes = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
-Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 ImageTransformations = "02fcd773-0e25-5acc-982a-7f6622650795"
-MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
-Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
-Tullio = "bc48ee85-29a4-5162-ae0b-a64e1601d4bc"
 XAIBase = "9b48221d-a747-4c1b-9860-46a1d8ba24a7"
 Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
-[weakdeps]
-Tullio = "bc48ee85-29a4-5162-ae0b-a64e1601d4bc"
-
-[extensions]
-TullioLRPRulesExt = "Tullio"
-
 [compat]
-ColorSchemes = "3.18"
 Distributions = "0.25"
-Flux = "0.13, 0.14"
 ImageCore = "0.9, 0.10"
 ImageTransformations = "0.9, 0.10"
-MacroTools = "0.5"
-Markdown = "1"
 Random = "1"
 Reexport = "1"
 Statistics = "1"
-Tullio = "0.3"
 XAIBase = "1.2"
 Zygote = "0.6"
 julia = "1.6"

docs/make.jl

@@ -34,18 +34,7 @@ makedocs(;
             "Heatmapping"          => "generated/heatmapping.md",
             "Input augmentations"  => "generated/augmentations.md",
         ],
-        "LRP" => Any[
-            "Basic usage"                   => "generated/lrp/basics.md",
-            "Assigning rules to layers"     => "generated/lrp/composites.md",
-            "Supporting new layer types"    => "generated/lrp/custom_layer.md",
-            "Custom LRP rules"              => "generated/lrp/custom_rules.md",
-            "Concept Relevance Propagation" => "generated/lrp/crp.md",
-            "Developer documentation"       => "lrp/developer.md"
-        ],
-        "API Reference" => Any[
-            "General" => "api.md",
-            "LRP"     => "lrp/api.md"
-        ],
+        "API Reference" => "api.md",
     ],
     #! format: on
     linkcheck=true,

docs/src/api.md

@@ -8,7 +8,6 @@ heatmap
 
 # Analyzers
 ```@docs
-LRP
 Gradient
 InputTimesGradient
 SmoothGrad
@@ -24,13 +23,6 @@ NoiseAugmentation
 InterpolationAugmentation
 ```
 
-# Model preparation
-```@docs
-strip_softmax
-canonize
-flatten_model
-```
-
 # Input preprocessing
 ```@docs
 preprocess_imagenet

docs/src/index.md

@@ -4,7 +4,7 @@ CurrentModule = ExplainableAI
 
 # ExplainableAI.jl
 
-Explainable AI in Julia using [Flux.jl](https://fluxml.ai).
+Explainable AI in Julia.
 
 ## Installation 
 To install this package and its dependencies, open the Julia REPL and run 
@@ -22,27 +22,9 @@ Pages = [
 ]
 Depth = 3
 ```
-### LRP
-```@contents
-Pages = [
-    "generated/lrp/basics.md",
-    "generated/lrp/composites.md",
-    "generated/lrp/custom_layer.md",
-    "generated/lrp/custom_rules.md",
-    "lrp/developer.md",
-]
-Depth = 3
-```
 
 ## API reference
-### General
 ```@contents
 Pages = ["api.md"]
 Depth = 2
 ```
-
-### LRP
-```@contents
-Pages = ["lrp/api.md"]
-Depth = 2
-```

docs/src/literate/augmentations.jl

@@ -56,9 +56,8 @@ heatmap(input, analyzer)
 
 # Is is also possible to define your own distributions or mixture distributions.
 #
-# `NoiseAugmentation` can be combined with any analyzer type, for example [`LRP`](@ref):
-analyzer = NoiseAugmentation(LRP(model), 50)
-heatmap(input, analyzer)
+# `NoiseAugmentation` can be combined with any analyzer type from the Julia-XAI ecosystem,
+# for example `LRP` from [RelevancePropagation.jl](https://github.com/Julia-XAI/RelevancePropagation.jl).
 
 # ## Integration augmentation
 # The [`InterpolationAugmentation`](@ref) wrapper computes explanations
@@ -80,7 +79,5 @@ analyzer = InterpolationAugmentation(Gradient(model), 50)
 expl = analyzer(input; input_ref=matrix_of_ones)
 heatmap(expl)
 
-# Once again, `InterpolationAugmentation` can be combined with any analyzer type,
-# for example [`LRP`](@ref):
-analyzer = InterpolationAugmentation(LRP(model), 50)
-heatmap(input, analyzer)
+# Once again, `InterpolationAugmentation` can be combined with any analyzer type from the Julia-XAI ecosystem,
+# for example `LRP` from [RelevancePropagation.jl](https://github.com/Julia-XAI/RelevancePropagation.jl).

docs/src/literate/example.jl

@@ -11,13 +11,6 @@ model
 #md # !!! note "Supported models"
 #md #
 #md #     ExplainableAI.jl can be used on any differentiable classifier.
-#md #
-#md #     Only LRP requires models from Flux.jl.
-
-# ## Preparing the model
-# For models with softmax activations on the output,
-# it is necessary to call [`strip_softmax`](@ref) before analyzing.
-model = strip_softmax(model);
 
 # ## Preparing the input data
 # We use MLDatasets to load a single image from the MNIST dataset:
@@ -44,7 +37,7 @@ input = reshape(x, 28, 28, 1, :);
 # ## Explanations
 # We can now select an analyzer of our choice and call [`analyze`](@ref)
 # to get an [`Explanation`](@ref):
-analyzer = LRP(model)
+analyzer = InputTimesGradient(model)
 expl = analyze(input, analyzer);
 
 # The return value `expl` is of type [`Explanation`](@ref) and bundles the following data:
@@ -57,13 +50,12 @@ expl = analyze(input, analyzer);
 # * `expl.extras`: optional named tuple that can be used by analyzers
 #     to return additional information.
 #
-# We used an LRP analyzer, so `expl.analyzer` is `:LRP`.
+# We used `InputTimesGradient`, so `expl.analyzer` is `:InputTimesGradient`.
 expl.analyzer
 
 # By default, the explanation is computed for the maximally activated output neuron.
 # Since our digit is a 9 and Julia's indexing is 1-based,
 # the output neuron at index `10` of our trained model is maximally activated.
-expl.output_selection
 
 # Finally, we obtain the result of the analyzer in form of an array.
 expl.val
@@ -81,29 +73,6 @@ heatmap(input, analyzer)
 # refer to the [heatmapping section](@ref docs-heatmapping).
 
 # ## [List of analyzers](@id docs-analyzers-list)
-# Currently, the following analyzers are implemented:
-# - [`Gradient`](@ref)
-# - [`InputTimesGradient`](@ref)
-# - [`SmoothGrad`](@ref)
-# - [`IntegratedGradients`](@ref)
-# - [`LRP`](@ref)
-#   - Rules
-#       - [`ZeroRule`](@ref)
-#       - [`EpsilonRule`](@ref)
-#       - [`GammaRule`](@ref)
-#       - [`GeneralizedGammaRule`](@ref)
-#       - [`WSquareRule`](@ref)
-#       - [`FlatRule`](@ref)
-#       - [`ZBoxRule`](@ref)
-#       - [`ZPlusRule`](@ref)
-#       - [`AlphaBetaRule`](@ref)
-#       - [`PassRule`](@ref)
-#   - [`Composite`](@ref)
-#       - [`EpsilonGammaBox`](@ref)
-#       - [`EpsilonPlus`](@ref)
-#       - [`EpsilonPlusFlat`](@ref)
-#       - [`EpsilonAlpha2Beta1`](@ref)
-#       - [`EpsilonAlpha2Beta1Flat`](@ref)
 
 # ## Neuron selection
 # By passing an additional index to our call to [`analyze`](@ref),
@@ -135,36 +104,3 @@ heatmap(expl)
 
 # For more information on heatmapping batches,
 # refer to the [heatmapping documentation](@ref docs-heatmapping-batches).
-
-# ## [GPU support](@id gpu-docs)
-# All analyzers support GPU backends,
-# building on top of [Flux.jl's GPU support](https://fluxml.ai/Flux.jl/stable/gpu/).
-# Using a GPU only requires moving the input array and model weights to the GPU.
-#
-# For example, using [CUDA.jl](https://github.com/JuliaGPU/CUDA.jl):
-
-# ```julia
-# using CUDA, cuDNN
-# using Flux
-# using ExplainableAI
-#
-# # move input array and model weights to GPU
-# input = input |> gpu # or gpu(input)
-# model = model |> gpu # or gpu(model)
-#
-# # analyzers don't require calling `gpu`
-# analyzer = LRP(model)
-#
-# # explanations are computed on the GPU
-# expl = analyze(input, analyzer)
-# ```
-
-# Some operations, like saving, require moving explanations back to the CPU.
-# This can be done using Flux's `cpu` function:
-
-# ```julia
-# val = expl.val |> cpu # or cpu(expl.val)
-#
-# using BSON
-# BSON.@save "explanation.bson" val
-# ```

docs/src/literate/heatmapping.jl

@@ -24,8 +24,9 @@ convert2image(MNIST, x)
 # ## Automatic heatmap presets
 # The function [`heatmap`](@ref) automatically applies common presets for each method.
 #
-# Since [`InputTimesGradient`](@ref) and [`LRP`](@ref) both compute attributions,
-# their presets are similar. Gradient methods however are typically shown in grayscale:
+# Since [`InputTimesGradient`](@ref) computes attributions,
+# heatmaps are shown in a blue-white-red color scheme.
+# Gradient methods however are typically shown in grayscale:
 analyzer = Gradient(model)
 heatmap(input, analyzer)
 #-
@@ -35,7 +36,7 @@ heatmap(input, analyzer)
 # ## Custom heatmap settings
 # ### Color schemes
 # We can partially or fully override presets by passing keyword arguments to [`heatmap`](@ref).
-# For example, we can use a custom color scheme from ColorSchemes.jl using the keyword argument `cs`:
+# For example, we can use a custom color scheme from ColorSchemes.jl using the keyword argument `colorscheme`:
 using ColorSchemes
 
 expl = analyze(input, analyzer)