Visualization Methods¶
trulens.visualizations
¶
One clear use case for measuring attributions is for human consumption. In order to be fully leveraged by humans, explanations need to be interpretable — a large vector of numbers doesnβt in general make us more confident we understand what a network is doing. We therefore view an explanation as comprised of both an attribution measurement and an interpretation of what the attribution values represent.
One obvious way to interpret attributions, particularly in the image domain, is via visualization. This module provides several visualization methods for interpreting attributions as images.
Classes¶
Tiler
¶
Bases: object
Used to tile batched images or attributions.
Functions¶
tile
¶
Tiles the given array into a grid that is as square as possible.
PARAMETER | DESCRIPTION |
---|---|
a |
An array of 4D batched image data.
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
ndarray
|
A tiled array of the images from |
ndarray
|
3 for color images, and 2 for grayscale images (the batch dimension |
ndarray
|
is removed, as well as the channel dimension for grayscale images). |
ndarray
|
The resulting array has its color channel dimension ordered last to |
ndarray
|
fit the requirements of the |
Visualizer
¶
Bases: object
Visualizes attributions directly as a color image. Intended particularly for use with input-attributions.
This can also be used for viewing images (rather than attributions).
Functions¶
__init__
¶
__init__(
combine_channels: bool = False,
normalization_type: str = None,
blur: float = 0.0,
cmap: Colormap = None,
)
Configures the default parameters for the __call__
method (these can
be overridden by passing in values to __call__
).
PARAMETER | DESCRIPTION |
---|---|
combine_channels |
If
TYPE:
|
normalization_type |
Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
If
TYPE:
|
blur |
Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
TYPE:
|
cmap |
matplotlib.colors.Colormap | str, optional
Colormap or name of a Colormap to use for the visualization. If
TYPE:
|
__call__
¶
__call__(
attributions,
output_file=None,
imshow=True,
fig=None,
return_tiled=False,
combine_channels=None,
normalization_type=None,
blur=None,
cmap=None,
) -> ndarray
Visualizes the given attributions.
PARAMETER | DESCRIPTION |
---|---|
attributions |
A
|
output_file |
File name to save the visualization image to. If
DEFAULT:
|
imshow |
If true, a the visualization will be displayed. Otherwise the figure will not be displayed, but the figure can still be saved.
DEFAULT:
|
fig |
The
DEFAULT:
|
return_tiled |
If true, the returned array will be in the same shape as the
visualization, with no batch dimension and the samples in the
batch tiled along the width and height dimensions. If false, the
returned array will be reshaped to match
DEFAULT:
|
combine_channels |
If
DEFAULT:
|
normalization_type |
Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
If
DEFAULT:
|
blur |
Gives the radius of a Gaussian blur to be applied to the
attributions before visualizing. This can be used to help focus
on salient regions rather than specific salient pixels. If
DEFAULT:
|
cmap |
matplotlib.colors.Colormap | str, optional
Colormap or name of a Colormap to use for the visualization. If
DEFAULT:
|
RETURNS | DESCRIPTION |
---|---|
ndarray
|
A |
ndarray
|
attributions as modified for the visualization. This includes |
ndarray
|
normalization, blurring, etc. |
HeatmapVisualizer
¶
Bases: Visualizer
Visualizes attributions by overlaying an attribution heatmap over the original image, similar to how GradCAM visualizes attributions.
Functions¶
__init__
¶
__init__(
overlay_opacity=0.5,
normalization_type=None,
blur=10.0,
cmap="jet",
)
Configures the default parameters for the __call__
method (these can
be overridden by passing in values to __call__
).
PARAMETER | DESCRIPTION |
---|---|
overlay_opacity |
float Value in the range [0, 1] specifying the opacity for the heatmap overlay.
DEFAULT:
|
normalization_type |
Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
If
DEFAULT:
|
blur |
Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
DEFAULT:
|
cmap |
matplotlib.colors.Colormap | str, optional
Colormap or name of a Colormap to use for the visualization. If
DEFAULT:
|
__call__
¶
__call__(
attributions,
x,
output_file=None,
imshow=True,
fig=None,
return_tiled=False,
overlay_opacity=None,
normalization_type=None,
blur=None,
cmap=None,
) -> ndarray
Visualizes the given attributions by overlaying an attribution heatmap over the given image.
PARAMETER | DESCRIPTION |
---|---|
attributions |
A
|
x |
A
|
output_file |
File name to save the visualization image to. If
DEFAULT:
|
imshow |
If true, a the visualization will be displayed. Otherwise the figure will not be displayed, but the figure can still be saved.
DEFAULT:
|
fig |
The
DEFAULT:
|
return_tiled |
If true, the returned array will be in the same shape as the
visualization, with no batch dimension and the samples in the
batch tiled along the width and height dimensions. If false, the
returned array will be reshaped to match
DEFAULT:
|
overlay_opacity |
float
Value in the range [0, 1] specifying the opacity for the heatmap
overlay. If
DEFAULT:
|
normalization_type |
Specifies one of the following configurations for normalizing the attributions (each item is normalized separately):
If
DEFAULT:
|
blur |
Gives the radius of a Gaussian blur to be applied to the
attributions before visualizing. This can be used to help focus
on salient regions rather than specific salient pixels. If
DEFAULT:
|
cmap |
matplotlib.colors.Colormap | str, optional
Colormap or name of a Colormap to use for the visualization. If
DEFAULT:
|
RETURNS | DESCRIPTION |
---|---|
ndarray
|
A |
ndarray
|
attributions as modified for the visualization. This includes |
ndarray
|
normalization, blurring, etc. |
MaskVisualizer
¶
Bases: object
Visualizes attributions by masking the original image to highlight the regions with influence above a given threshold percentile. Intended particularly for use with input-attributions.
Functions¶
__init__
¶
__init__(
blur=5.0,
threshold=0.5,
masked_opacity=0.2,
combine_channels=True,
use_attr_as_opacity=False,
positive_only=True,
)
Configures the default parameters for the __call__
method (these can
be overridden by passing in values to __call__
).
PARAMETER | DESCRIPTION |
---|---|
blur |
Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
DEFAULT:
|
threshold |
Value in the range [0, 1]. Attribution values at or below the
percentile given by
DEFAULT:
|
masked_opacity |
Value in the range [0, 1] specifying the opacity for the parts of the image that are masked.
DEFAULT:
|
combine_channels |
If
DEFAULT:
|
use_attr_as_opacity |
If
DEFAULT:
|
positive_only |
If
DEFAULT:
|
ChannelMaskVisualizer
¶
Bases: object
Uses internal influence to visualize the pixels that are most salient towards a particular internal channel or neuron.
Functions¶
__init__
¶
__init__(
model,
layer,
channel,
channel_axis=None,
agg_fn=None,
doi=None,
blur=None,
threshold=0.5,
masked_opacity=0.2,
combine_channels: bool = True,
use_attr_as_opacity=None,
positive_only=None,
)
Configures the default parameters for the __call__
method (these can
be overridden by passing in values to __call__
).
PARAMETER | DESCRIPTION |
---|---|
model |
The wrapped model whose channel we're visualizing.
|
layer |
The identifier (either index or name) of the layer in which the channel we're visualizing resides.
|
channel |
Index of the channel (for convolutional layers) or internal neuron (for fully-connected layers) that we'd like to visualize.
|
channel_axis |
If different from the channel axis specified by the backend, the
supplied
DEFAULT:
|
agg_fn |
Function with which to aggregate the remaining dimensions
(except the batch dimension) in order to get a single scalar
value for each channel; If
DEFAULT:
|
doi |
The distribution of interest to use when computing the input
attributions towards the specified channel. If
DEFAULT:
|
blur |
Gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels.
DEFAULT:
|
threshold |
Value in the range [0, 1]. Attribution values at or below the
percentile given by
DEFAULT:
|
masked_opacity |
Value in the range [0, 1] specifying the opacity for the parts of the image that are masked.
DEFAULT:
|
combine_channels |
If
TYPE:
|
use_attr_as_opacity |
If
DEFAULT:
|
positive_only |
If
DEFAULT:
|
__call__
¶
__call__(
x,
x_preprocessed=None,
output_file=None,
blur=None,
threshold=None,
masked_opacity=None,
combine_channels=None,
)
Visualizes the given attributions by overlaying an attribution heatmap over the given image.
Parameters¶
attributions : numpy.ndarray The attributions to visualize. Expected to be in 4-D image format.
numpy.ndarray
The original image(s) over which the attributions are calculated. Must be the same shape as expected by the model used with this visualizer.
numpy.ndarray, optional
If the model requires a preprocessed input (e.g., with the mean
subtracted) that is different from how the image should be
visualized, x_preprocessed
should be specified. In this case
x
will be used for visualization, and x_preprocessed
will be
passed to the model when calculating attributions. Must be the same
shape as x
.
str, optional
If specified, the resulting visualization will be saved to a file
with the name given by output_file
.
float, optional
If specified, gives the radius of a Gaussian blur to be applied to the attributions before visualizing. This can be used to help focus on salient regions rather than specific salient pixels. If None, defaults to the value supplied to the constructor. Default None.
float
Value in the range [0, 1]. Attribution values at or below the
percentile given by threshold
will be masked. If None, defaults
to the value supplied to the constructor. Default None.
float
Value in the range [0, 1] specifying the opacity for the parts of the image that are masked. Default 0.2. If None, defaults to the value supplied to the constructor. Default None.
bool
If True, the attributions will be averaged across the channel dimension, resulting in a 1-channel attribution map. If None, defaults to the value supplied to the constructor. Default None.
NLP
¶
Bases: object
NLP Visualization tools.
Functions¶
__init__
¶
__init__(
wrapper: ModelWrapper,
output: Optional[Output] = None,
labels: Optional[Iterable[str]] = None,
tokenize: Optional[
Callable[[TextBatch], ModelInputs]
] = None,
decode: Optional[Callable[[Tensor], str]] = None,
input_accessor: Optional[
Callable[[ModelInputs], Iterable[Tensor]]
] = None,
output_accessor: Optional[
Callable[[ModelOutput], Iterable[Tensor]]
] = None,
attr_aggregate: Optional[
Callable[[Tensor], Tensor]
] = None,
hidden_tokens: Optional[Set[int]] = set(),
)
Initializate NLP visualization tools for a given environment.
PARAMETER | DESCRIPTION |
---|---|
wrapper |
ModelWrapper The wrapped model whose channel we're visualizing.
TYPE:
|
output |
Output, optional Visualization output format. Defaults to PlainText unless ipython is detected and in which case defaults to IPython format. |
labels |
Iterable[str], optional Names of prediction classes for classification models. |
tokenize |
Callable[[TextBatch], ModelInput], optional Method to tokenize an instance.
TYPE:
|
decode |
Callable[[Tensor], str], optional Method to invert/decode the tokenization. |
input_accessor |
Callable[[ModelInputs], Iterable[Tensor]], optional Method to extract input/token ids from model inputs (tokenize output) if needed.
TYPE:
|
output_accessor |
Callable[[ModelOutput], Iterable[Tensor]], optional Method to extract outout logits from output structures if needed.
TYPE:
|
attr_aggregate |
Callable[[Tensor], Tensor], optional Method to aggregate attribution for embedding into a single value. Defaults to sum. |
hidden_tokens |
Set[int], optional For token-based visualizations, which tokens to hide. |
token_attribution
¶
token_attribution(
texts: Iterable[str], attr: AttributionMethod
)
Visualize a token-based input attribution on given texts
inputs via the attribution method attr
.
PARAMETER | DESCRIPTION |
---|---|
texts |
Iterable[str] The input texts to visualize. |
attr |
AttributionMethod The attribution method to generate the token importances with.
TYPE:
|
ANY | DESCRIPTION |
---|---|
The visualization in the format specified by this class's |