VisionHeatmaps.jl

heatmap(attr::Attribution)
heatmap(attr::Attribution, pipeline)
heatmap(attr::Attribution, image)
heatmap(attr::Attribution, image, pipeline)

Visualize Attribution from XAIBase as a vision heatmap. Assumes WHCN convention (width, height, channels, batch dimension) for attr.val. Unless a pipeline is passed, this will use the default heatmapping pipeline for the attribution pooling function attr.pooling, see default_pipeline.

heatmap(input::AbstractArray, analyzer::AbstractXAIMethod)
heatmap(input::AbstractArray, analyzer::AbstractXAIMethod, image)

Compute an Attribution for a given input using the XAI method analyzer and visualize it as a vision heatmap. This will use the default heatmapping pipeline for the attribution pooling function attr.pooling.

default_pipeline(attr::Attribution)
default_pipeline(pooling::AbstractPooling)

Return the default heatmapping pipeline for an Attribution from XAIBase.jl, chosen based on its attribution pooling function attr.pooling. The pooling picks the normalization, which in turn picks the colormap:

• UnsignedPooling (e.g. NormPooling) uses ExtremaNormalization and the sequential :batlow
• SignedPooling (e.g. SumPooling) uses CenteredNormalization and the diverging :berlin

Batch(A; dims = ndims(A))

Wrap an array A to mark it as a batch of samples along the batch dimension dims, which defaults to the last dimension of A. Unwrapped arrays are treated as single samples.

Downstream packages use Batch to distinguish transforms that are applied to each sample individually (the default, see XAIBase.mapsamples) from batch-aware transforms like BatchedNormalization.

eachsample(batch)

Iterate over the samples in a XAIBase.Batch, which are views into the wrapped array.

mapsamples(f, batch)
mapsamples(f, batch, batches...)

Apply f to each sample in a XAIBase.Batch and stack the results into a new Batch. When called with several batches, f is called on corresponding samples, like map.

All results of f need to have the same size. If f changes the number of dimensions of the samples, a batch dimension that was the last dimension of batch remains the last dimension. Otherwise, the batch dimension keeps its index.

Pipeline(transforms...)

Sequentially apply transforms of type AbstractTransform. Pipelines are usually created by composing transforms using |>:

pipeline = NormPooling() |> ExtremaNormalization()

AbstractTransform

Abstract super type of all transforms of attributions, e.g. feature-attribution pooling functions (AbstractPooling) and normalization functions (AbstractNormalization).

Transforms can be composed into a Pipeline using |>. XAIBase only defines the composition of transforms: how transforms are applied is defined by downstream packages, e.g. VisionHeatmaps.jl and TextHeatmaps.jl.

apply(t::AbstractTransform, x)
apply(t::AbstractTransform, x, img)

Apply a transform t of type AbstractTransform to the input x. Can optionally take an input image.

Custom heatmapping transforms subtype AbstractTransform and must implement an apply(t, x::AbstractArray) method for single samples. Batches of type XAIBase.Batch are transformed sample by sample by default. Batch-aware transforms can implement apply(t, xs::Batch).

NormPooling()

$\ell^2$-norm pooling $\sqrt{\sum_i a_i^2}$ over the feature dimension. Returns non-negative values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

SumPooling()

Sum-pooling $\sum_i a_i$ over the feature dimension. Returns signed values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

MaxPooling()

Max-pooling $\max_i a_i$ over the feature dimension. Returns signed values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

SumAbsPooling()

Sum-of-absolute-values pooling $\sum_i |a_i|$ ($\ell^1$-norm) over the feature dimension. Returns non-negative values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

AbsSumPooling()

Absolute-value-of-sum pooling $\left| \sum_i a_i \right|$ over the feature dimension. Returns non-negative values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

MaxAbsPooling()

Maximum-absolute-value pooling $\max_i |a_i|$ ($\ell^\infty$-norm) over the feature dimension. Returns non-negative values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

SquaredNormPooling()

Squared $\ell^2$-norm pooling $\sum_i a_i^2$ over the feature dimension. Returns non-negative values.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

SignedNoPooling()

Identity pooling that leaves values unchanged and only drops the feature dimension dims, which has to be a singleton.

Use SignedNoPooling for attributions that are already reduced along the feature dimension and therefore require no pooling. SignedNoPooling subtypes SignedPooling and is therefore visualized using a diverging colormap.

For attributions that are guaranteed to be non-negative, use UnsignedNoPooling.

UnsignedNoPooling()

Identity pooling that leaves values unchanged and only drops the feature dimension dims, which has to be a singleton.

Use UnsignedNoPooling for attributions that are already reduced along the feature dimension and guaranteed to be non-negative. UnsignedNoPooling subtypes UnsignedPooling and is therefore visualized using a sequential colormap.

For attributions of unknown sign, use SignedNoPooling.

Abstract super type of all attribution pooling functions in XAIBase.

Pooling functions are fieldless structs that reduce an array over a feature dimension via pool. They are subtypes of either UnsignedPooling or SignedPooling, depending on whether their output is non-negative or signed.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

Abstract super type of attribution pooling functions with unsigned output, e.g. SumAbsPooling, AbsSumPooling, MaxAbsPooling, NormPooling and SquaredNormPooling.

Unsigned attributions are best visualized using a sequential colormap.

Abstract super type of attribution pooling functions with signed output, e.g. SumPooling and MaxPooling.

Signed attributions are best visualized using a diverging colormap.

pool(pooling, A, dims)

Reduce array A over the feature dimension dims using the attribution pooling function pooling, an AbstractPooling.

For convenience, pooling(A, dims) is equivalent to pool(pooling, A, dims).

A can also be a XAIBase.Batch, whose batch dimension is updated to account for the dropped dimension. The batch dimension itself can't be pooled.

Custom pooling functions implement pool(pooling, A::AbstractArray, dims), which has to drop the pooled dimension.

Note

Attribution pooling projects a high-dimensional attribution (e.g. RGB values per pixel) onto a lower-dimensional, human-interpretable space (e.g. a single value per pixel) by reducing over a feature dimension dims (typically the color-channel dimension 3 of a (width, height, channels, batch) array).

The pooled dimension is dropped, e.g. an array of size (W, H, C, N) is reduced to size (W, H, N).

Pooling functions are documented by their action on a single slice $a = (a_1, \ldots, a_n)$ along the pooled dimension dims.

ExtremaNormalization()

Normalization that linearly maps the value range (minimum(A), maximum(A)) onto the unit interval [0, 1].

ExtremaNormalization is a suitable normalization for unsigned attributions (UnsignedPooling), which are visualized with a sequential colormap.

Note

Normalization is the step between feature-attribution pooling and colormapping: it linearly rescales pooled attribution values onto the unit interval [0, 1], which colormaps expect as input.

The appropriate normalization depends on the sign of the pooled values and is therefore determined by the pooling function's supertype (see default_normalization).

CenteredNormalization()

Normalization that linearly maps the symmetric value range (-maximum(abs, A), maximum(abs, A)) onto the unit interval [0, 1], mapping the value zero onto the midpoint 0.5.

CenteredNormalization is the natural normalization for signed attributions (SignedPooling), which are visualized with a diverging colormap whose neutral midpoint then corresponds to zero attribution.

Note

Normalization is the step between feature-attribution pooling and colormapping: it linearly rescales pooled attribution values onto the unit interval [0, 1], which colormaps expect as input.

The appropriate normalization depends on the sign of the pooled values and is therefore determined by the pooling function's supertype (see default_normalization).

BatchedNormalization(normalization)

Normalize a whole XAIBase.Batch at once, computing a shared value range over all samples via normalization_bounds. This makes heatmaps comparable across the samples in a batch.

By default, normalization functions normalize each sample in a batch separately. On single samples, BatchedNormalization(normalization) behaves like normalization.

Note

Normalization is the step between feature-attribution pooling and colormapping: it linearly rescales pooled attribution values onto the unit interval [0, 1], which colormaps expect as input.

The appropriate normalization depends on the sign of the pooled values and is therefore determined by the pooling function's supertype (see default_normalization).

Abstract super type of all normalization functions in XAIBase.

Normalization functions are fieldless structs that linearly rescale arrays of pooled attribution values onto the unit interval [0, 1] via XAIBase.normalize. The value range that is mapped onto [0, 1] is computed by normalization_bounds.

Note

Normalization is the step between feature-attribution pooling and colormapping: it linearly rescales pooled attribution values onto the unit interval [0, 1], which colormaps expect as input.

The appropriate normalization depends on the sign of the pooled values and is therefore determined by the pooling function's supertype (see default_normalization).

normalize(normalization, A)
normalize(normalization, A, bounds)

Rescale the values of array A linearly onto the unit interval [0, 1] using the normalization function normalization, an AbstractNormalization. The value range bounds = (lo, hi) is mapped onto [0, 1] and values outside of it are clamped. If bounds is not provided, it is computed from A via normalization_bounds.

For convenience, normalization(A) is equivalent to normalize(normalization, A).

Passing precomputed bounds normalizes A to a shared value range, e.g. to make heatmaps comparable across all samples in a batch:

bounds = normalization_bounds(normalization, batch)
slices = [normalize(normalization, x, bounds) for x in eachslice(batch; dims = 4)]

Note

Normalization is the step between feature-attribution pooling and colormapping: it linearly rescales pooled attribution values onto the unit interval [0, 1], which colormaps expect as input.

The appropriate normalization depends on the sign of the pooled values and is therefore determined by the pooling function's supertype (see default_normalization).

normalization_bounds(normalization, A)

Compute the value range (lo, hi) of A that XAIBase.normalize maps onto the unit interval [0, 1].

A can be an array or any iterator of real values. This allows bounds to be computed across a whole batch of arrays, e.g. via Iterators.flatten, for normalization to a shared value range.

Note

Normalization is the step between feature-attribution pooling and colormapping: it linearly rescales pooled attribution values onto the unit interval [0, 1], which colormaps expect as input.

The appropriate normalization depends on the sign of the pooled values and is therefore determined by the pooling function's supertype (see default_normalization).

default_normalization(pooling)

Return the natural AbstractNormalization for the given feature-attribution pooling function, determined by the sign of the pooling's output:

• UnsignedPooling → ExtremaNormalization (sequential colormap)
• SignedPooling → CenteredNormalization (diverging colormap)

FlipImage()

Permutes the width and height dimensions of an array. Assumes width and height are the leading directions in the array.

heatmap already applies this flip by default, turning WHCN values into display-oriented images, so it does not need to be part of a pipeline. It remains available for pipelines that operate on pre-oriented arrays.

PermuteDims(dims...)

Permutes arrays according to the specified dimensions.

DropDims(dims...)

Drops specified singleton array dimensions.

PercentileClip()
PercentileClip(lower, upper)

Clip values outside of the specified percentiles of values. Bounds default to 0.001 and 0.999 (99.9% percentiles).

Colormap()
Colormap(name::Symbol)
Colormap(name::Symbol, colormap)

Apply a colormap from ColorSchemes.jl, turning an array of values into an image. Defaults to :batlow.

Values are expected to be normalized to the unit interval [0, 1], e.g. by ExtremaNormalization() or CenteredNormalization() from XAIBase.jl. Values outside of this interval are clamped.

Normalizations are meant to be paired with a kind of colormap: ExtremaNormalization with sequential colormaps (e.g. :batlow), CenteredNormalization with diverging colormaps (e.g. :berlin). Composing a normalization with a colormap that ColorSchemes.jl describes as the other kind emits a warning.

ResizeToImage()
ResizeToImage(method)

Resize the heatmap to match the image dimensions. In some cases, this is needed for overlays. Defaults to Lanczos(1) from Interpolations.jl.

AlphaOverlay()
AlphaOverlay(alpha)

Overlays a heatmap on top of an image. The opacity alpha of the heatmap defaults to 0.6.