Document CRP (#148)

* Document use of CRP

* Document `heatmap` kwarg `process_batch`

* Define `show` on `IndexedConcepts`

Author: adrhill

docs/make.jl

@@ -35,11 +35,12 @@ makedocs(;
             "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",
-            "Developer documentation"    => "lrp/developer.md"
+            "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",
@@ -48,7 +49,10 @@ makedocs(;
     ],
     #! format: on
     linkcheck=true,
-    linkcheck_ignore=[r"https://link.springer.com/chapter/10.1007/978-3-030-28954-6_10"],
+    linkcheck_ignore=[
+        r"https://link.springer.com/chapter/10.1007/978-3-030-28954-6_10",
+        r"https://www.nature.com/articles/s42256-023-00711-8",
+    ],
     checkdocs=:exports, # only check docstrings in API reference if they are exported
 )
 

docs/src/literate/heatmapping.jl

@@ -64,8 +64,8 @@ heatmap(expl; reduce=:norm)
 #-
 heatmap(expl; reduce=:maxabs)
 
-# Since MNIST only has a single color channel, there is no need for reduction
-# and heatmaps look identical.
+# In this example, the heatmaps look identical.
+# Since MNIST only has a single color channel, there is no need for color channel reduction.
 
 # ### [Mapping explanations onto the color scheme](@id docs-heatmap-rangescale)
 # To map a [color-channel-reduced](@ref docs-heatmap-reduce) explanation onto a color scheme,
@@ -103,6 +103,20 @@ heatmaps = heatmap(batch, analyzer)
 # Image.jl's `mosaic` function can used to display them in a grid:
 mosaic(heatmaps; nrow=10)
 
+# When heatmapping batches, the mapping to the color scheme is applied per sample.
+# For example, `rangescale=:extrema` will normalize each heatmap
+# to the minimum and maximum value of each sample in the batch.
+# This ensures that heatmaps don't depend on other samples in the batch.
+#
+# If this bevahior is not desired,
+# `heatmap` can be called with the keyword-argument `process_batch=true`:
+heatmaps = heatmap(batch, analyzer; process_batch=true)
+mosaic(heatmaps; nrow=10)
+
+# This can be useful when comparing heatmaps for fixed output neurons:
+heatmaps = heatmap(batch, analyzer, 7; process_batch=true) # heatmaps for digit "6"
+mosaic(heatmaps; nrow=10)
+
 #md # !!! note "Output type consistency"
 #md #
 #md #     To obtain a singleton `Vector` containing a single heatmap for non-batched inputs,

docs/src/literate/lrp/crp.jl

@@ -0,0 +1,57 @@
+# # [Concept relevance propagation](@id docs-crp)
+# In [*From attribution maps to human-understandable explanations through Concept Relevance Propagation*](https://www.nature.com/articles/s42256-023-00711-8) (CRP),
+# Achtibat et al. propose the conditioning of LRP relevances on individual features of a model.
+#
+# This example builds on the basics shown in the [*Getting started*](@ref docs-getting-started) section.
+# We start out by loading the same pre-trained LeNet5 model and MNIST input data:
+using ExplainableAI
+using Flux
+
+using BSON # hide
+model = BSON.load("../../model.bson", @__MODULE__)[:model] # hide
+model
+#-
+using MLDatasets
+using ImageCore, ImageIO, ImageShow
+
+index = 10
+x, y = MNIST(Float32, :test)[10]
+input = reshape(x, 28, 28, 1, :)
+
+convert2image(MNIST, x)
+
+# ## Step 1: Create LRP analyzer
+# To create a CRP analyzer, first define an LRP analyzer with your desired rules:
+composite = EpsilonPlusFlat()
+lrp_analyzer = LRP(model, composite)
+
+# ## Step 2: Define concepts
+# Then, specify the index of the layer on the outputs of which you want to condition the explanation.
+# In this example, we are interested in the outputs of the last convolutional layer, layer 3:
+concept_layer = 3    # index of relevant layer in model
+model[concept_layer] # show layer
+
+# Then, specify the concepts you are interested in.
+# To automatically select the $n$ most relevant concepts, use [`TopNConcepts`](@ref).
+#
+# Note that for convolutional layers,
+# a feature corresponds to an entire output channel of the layer.
+concepts = TopNConcepts(5)
+
+# To manually specify features, use [`IndexedConcepts`](@ref).
+concepts = IndexedConcepts(1, 2, 10)
+
+# ## Step 3: Use CRP analyzer
+# We can now create a [`CRP`](@ref) analyzer
+# and use it like any other analyzer from ExplainableAI.jl:
+analyzer = CRP(lrp_analyzer, concept_layer, concepts)
+heatmap(input, analyzer)
+
+# ## Using CRP on input batches
+# Note that `CRP` uses the batch dimension to return explanations.
+# When using CRP on batches, the explanations are first sorted by concepts, then inputs,
+# e.g. `[c1_i1, c1_i2, c2_i1, c2_i2, c3_i1, c3_i2]` in the following example:
+x, y = MNIST(Float32, :test)[10:11]
+batch = reshape(x, 28, 28, 1, :)
+
+heatmap(batch, analyzer)

src/lrp/crp.jl

@@ -130,6 +130,9 @@ IndexedConcepts(args...) = IndexedConcepts(tuple(args...))
 
 number_of_concepts(c::IndexedConcepts) = length(c.inds)
 
+# Pretty printing
+Base.show(io::IO, c::IndexedConcepts) = print(io, "IndexedConcepts$(c.inds)")
+
 # Index concepts on 2D arrays, e.g. Dense layers with batch dimension
 function (c::IndexedConcepts)(A::AbstractMatrix)
     batchsize = size(A, 2)