Export output selectors and improve docs (#15)

* Export output selectors

* Improve output selector doc strings

* Improve feature selector doc strings

* Update API reference

docs/src/api.md

@@ -1,4 +1,8 @@
 # API Reference
+```@docs
+AbstractXAIMethod
+```
+
 ## Computing explanations
 Most methods in the Julia-XAI ecosystem work by calling `analyze` on an input and an analyzer:
 ```@docs
@@ -18,15 +22,16 @@ heatmap
 
 ## Feature selection
 ```@docs
+AbstractFeatureSelector
 IndexedFeatures
 TopNFeatures
 ```
 
-## Internals
-### Output selection
+## Output selection
 ```@docs
-XAIBase.MaxActivationSelector
-XAIBase.IndexSelector
+AbstractOutputSelector
+MaxActivationSelector
+IndexSelector
 ```
 
 ## Index

docs/src/examples.md

@@ -89,7 +89,7 @@ heatmap(expl)
 ```
 
 ```@example implementations
-heatmap(expl, reduce=:norm, colorscheme=:twilight)
+heatmap(expl, colorscheme=:twilight, reduce=:norm, rangescale=:centered)
 ```
 
 and make use of all the features provided by the Julia-XAI ecosystem.

docs/src/index.md

@@ -1,7 +1,7 @@
 ## [Interface description](@id docs-interface)
 
 XAIBase.jl is a light-weight dependency that defines the interface of XAI methods 
-in the [Julia-XAI ecosystem](https://julia-xai.github.io/XAIDocs).
+in the [Julia-XAI ecosystem](https://julia-xai.github.io/XAIDocs/).
 
 Building on top of XAIBase 
 (or providing an interface via [package extensions](https://pkgdocs.julialang.org/v1/creating-packages/#Conditional-loading-of-code-in-packages-(Extensions)))
@@ -23,8 +23,8 @@ This only requires you to fulfill the following two requirements:
   which contains the batched output in the `val` field.
 * `AbstractOutputSelector`s are predefined callable structs 
   that select a single scalar value from a model's output, 
-  e.g. the maximally activated output of a classifier using [`XAIBase.MaxActivationSelector`](@ref)
-  or a specific output using [`XAIBase.IndexSelector`](@ref).
+  e.g. the maximally activated output of a classifier using [`MaxActivationSelector`](@ref)
+  or a specific output using [`IndexSelector`](@ref).
 
 Refer to the [`Explanation`](@ref) documentation for a description of the expected fields.
 For more information, take a look at [`src/XAIBase.jl`](https://github.com/Julia-XAI/XAIBase.jl/blob/main/src/XAIBase.jl).

src/XAIBase.jl

@@ -41,9 +41,9 @@ include("feature_selection.jl")
 include("deprecated.jl")
 
 export AbstractXAIMethod
-export AbstractOutputSelector
 export Explanation
 export analyze
 export heatmap
-export IndexedFeatures, TopNFeatures
+export AbstractOutputSelector, MaxActivationSelector, IndexSelector
+export AbstractFeatureSelector, IndexedFeatures, TopNFeatures
 end #module

src/feature_selection.jl

@@ -1,7 +1,22 @@
+const NOTE_FEATURE_SELECTOR = """## Note
+The XAIBase interface currently assumes that features have either 2 or 4 dimensions
+(`(features, batchsize)` or `(width, height, features, batchsize)`).
+
+It also assumes that the batch dimension is the last dimension of the feature.
+"""
+
+"""
+Abstract super type of all feature selectors in XAIBase.
+
+Feature selectors are expected to be callable and to return a vector of `CartesianIndices`
+for each selected feature.
+
+$NOTE_FEATURE_SELECTOR
+"""
 abstract type AbstractFeatureSelector end
 
 # Expected interfaces:
-# - Calls to feature selector that return a list of lists of CartesianIndices
+# - Calls to feature selector that return a list of lists of `CartesianIndices`
 #   - (c::FeatureSelector)(R::AbstractArray{T,N}) where {T,2}
 #   - (c::FeatureSelector)(R::AbstractArray{T,N}) where {T,4}
 # - number_of_features(c::FeatureSelector)
@@ -14,6 +29,27 @@ Select features by indices.
 For outputs of convolutional layers, the index refers to a feature dimension.
 
 See also See also [`TopNFeatures`](@ref).
+
+$NOTE_FEATURE_SELECTOR
+
+## Example
+```julia-repl
+julia> feature_selector = IndexedFeatures(2, 3)
+ IndexedFeatures(2, 3)
+
+julia> feature = rand(3, 3, 3, 2);
+
+julia> feature_selector(feature)
+2-element Vector{Vector{CartesianIndices{4, NTuple{4, UnitRange{Int64}}}}}:
+ [CartesianIndices((1:3, 1:3, 2:2, 1:1)), CartesianIndices((1:3, 1:3, 2:2, 2:2))]
+ [CartesianIndices((1:3, 1:3, 3:3, 1:1)), CartesianIndices((1:3, 1:3, 3:3, 2:2))]
+
+julia> feature = rand(3, 2);
+
+julia> feature_selector(feature)
+ 1-element Vector{Vector{CartesianIndices{2, Tuple{UnitRange{Int64}, UnitRange{Int64}}}}}:
+  [CartesianIndices((2:2, 1:1)), CartesianIndices((2:2, 2:2))]
+```
 """
 struct IndexedFeatures{N} <: AbstractFeatureSelector
     inds::NTuple{N,Int}
@@ -53,6 +89,32 @@ For outputs of convolutional layers, the relevance is summed across height and w
 channels for each feature.
 
 See also [`IndexedFeatures`](@ref).
+
+$NOTE_FEATURE_SELECTOR
+
+## Example
+```julia-repl
+julia> feature_selector = TopNFeatures(2)
+ TopNFeatures(2)
+
+julia> feature = rand(3, 2)
+3×2 Matrix{Float64}:
+ 0.265312  0.953689
+ 0.674377  0.172154
+ 0.649722  0.570809
+
+julia> feature_selector(feature)
+2-element Vector{Vector{CartesianIndices{2, Tuple{UnitRange{Int64}, UnitRange{Int64}}}}}:
+ [CartesianIndices((2:2, 1:1)), CartesianIndices((1:1, 2:2))]
+ [CartesianIndices((3:3, 1:1)), CartesianIndices((3:3, 2:2))]
+
+julia> feature = rand(3, 3, 3, 2);
+
+julia> feature_selector(feature)
+2-element Vector{Vector{CartesianIndices{4, NTuple{4, UnitRange{Int64}}}}}:
+ [CartesianIndices((1:3, 1:3, 2:2, 1:1)), CartesianIndices((1:3, 1:3, 1:1, 2:2))]
+ [CartesianIndices((1:3, 1:3, 1:1, 1:1)), CartesianIndices((1:3, 1:3, 3:3, 2:2))]
+```
 """
 struct TopNFeatures <: AbstractFeatureSelector
     n::Int

src/output_selection.jl

@@ -1,9 +1,42 @@
+const NOTE_OUTPUT_SELECTOR = """## Note
+XAIBase assumes that the batch dimension is the last dimension of the output.
+"""
+
+"""
+Abstract super type of all output selectors in XAIBase.
+
+Output selectors are expected to be callable and to return a vector of `CartesianIndex`
+of the selected outputs.
+
+$NOTE_OUTPUT_SELECTOR
+"""
 abstract type AbstractOutputSelector end
 
 """
     MaxActivationSelector()
 
 Output selector that picks the output with the highest activation.
+
+$NOTE_OUTPUT_SELECTOR
+
+## Example
+```julia-repl
+julia> output = rand(3, 3)
+3×3 Matrix{Float64}:
+ 0.411871  0.313366  0.13402
+ 0.885562  0.136938  0.465622
+ 0.498235  0.627209  0.298911
+
+julia> output_selector = MaxActivationSelector()
+ MaxActivationSelector()
+
+julia> output_selector(output)
+ 3-element Vector{CartesianIndex{2}}:
+  CartesianIndex(2, 1)
+  CartesianIndex(3, 2)
+  CartesianIndex(2, 3)
+```
+
 """
 struct MaxActivationSelector <: AbstractOutputSelector end
 function (::MaxActivationSelector)(out::AbstractArray{T,N}) where {T,N}
@@ -15,6 +48,26 @@ end
     IndexSelector(index)
 
 Output selector that picks the output at the given index.
+
+$NOTE_OUTPUT_SELECTOR
+
+## Example
+```julia-repl
+julia> output = rand(3, 3)
+3×3 Matrix{Float64}:
+ 0.411871  0.313366  0.13402
+ 0.885562  0.136938  0.465622
+ 0.498235  0.627209  0.298911
+
+julia> output_selector = IndexSelector(1)
+ IndexSelector{Int64}(1)
+
+julia> output_selector(output)
+ 3-element Vector{CartesianIndex{2}}:
+  CartesianIndex(1, 1)
+  CartesianIndex(1, 2)
+  CartesianIndex(1, 3)
+```
 """
 struct IndexSelector{I} <: AbstractOutputSelector
     index::I