keras_explainable.methods package

Submodules

keras_explainable.methods.cams module

Implementation of various CAM-based AI explaining methods and techniques.

cam(model, inputs, indices=None, indices_axis=-1, indices_batch_dims=-1, spatial_axis=(-3, -2), logits_layer=None)[source]

Computes the CAM Visualization Method.

This method expects inputs to be a batch of positional signals of shape BHW...C, and will return a tensor of shape BH'W'...L, where (H', W', ...) are the sizes of the visual receptive field in the explained activation layer and L is the number of labels represented within the model’s output logits.

If indices is passed, the specific logits indexed by elements in this tensor are selected before the gradients are computed, effectively reducing the columns in the jacobian, and the size of the output explaining map.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)
model = ke.inspection.expose(model)

scores, cams = ke.methods.cams.cam(model, x, y)

References

  • Zhou, B., Khosla, A., Lapedriza, A., Oliva, A., & Torralba, A. (2016). Learning deep features for discriminative localization. In Proceedings of the IEEE conference on computer vision and pattern recognition (pp. 2921-2929). Available at: arxiv/1512.04150.

Parameters:

  • model (tf.keras.Model) – the model being explained

  • inputs (tf.Tensor) – the input data

  • indices (Optional[tf.Tensor], optional) – indices that should be gathered from outputs. Defaults to None.

  • indices_axis (int, optional) – the axis containing the indices to gather. Defaults to KERNEL_AXIS.

  • indices_batch_dims (int, optional) – the number of dimensions to broadcast in the tf.gather operation. Defaults to -1.

  • spatial_axis (Tuple[int], optional) – the dimensions containing positional information. Defaults to SPATIAL_AXIS.

  • logits_layer (Callable, optional) – filter before channel combining. Defaults to tf.abs.

Returns:

the logits and Class Activation Maps (CAMs).

Return type:

Tuple[tf.Tensor, tf.Tensor]

gradcam(model, inputs, indices=None, indices_axis=-1, indices_batch_dims=-1, spatial_axis=(-3, -2))[source]

Computes the Grad-CAM Visualization Method.

This method expects inputs to be a batch of positional signals of shape BHW...C, and will return a tensor of shape BH'W'...L, where (H', W', ...) are the sizes of the visual receptive field in the explained activation layer and L is the number of labels represented within the model’s output logits.

If indices is passed, the specific logits indexed by elements in this tensor are selected before the gradients are computed, effectively reducing the columns in the jacobian, and the size of the output explaining map.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)
model = ke.inspection.expose(model)

scores, cams = ke.methods.cams.gradcam(model, x, y)

References

  • Selvaraju, R. R., Cogswell, M., Das, A., Vedantam, R., Parikh, D., & Batra, D. (2017). Grad-CAM: Visual explanations from deep networks via gradient-based localization. In Proceedings of the IEEE international conference on computer vision (pp. 618-626). Available at: arxiv/1610.02391.

Parameters:

  • model (tf.keras.Model) – the model being explained

  • inputs (tf.Tensor) – the input data

  • indices (Optional[tf.Tensor], optional) – indices that should be gathered from outputs. Defaults to None.

  • indices_axis (int, optional) – the axis containing the indices to gather. Defaults to KERNEL_AXIS.

  • indices_batch_dims (int, optional) – the number of dimensions to broadcast in the tf.gather operation. Defaults to -1.

  • spatial_axis (Tuple[int], optional) – the dimensions containing positional information. Defaults to SPATIAL_AXIS.

Returns:

the logits and Class Activation Maps (CAMs).

Return type:

Tuple[tf.Tensor, tf.Tensor]

gradcampp(model, inputs, indices=None, indices_axis=-1, indices_batch_dims=-1, spatial_axis=(-3, -2))[source]

Computes the Grad-CAM++ Visualization Method.

This method expects inputs to be a batch of positional signals of shape BHW...C, and will return a tensor of shape BH'W'...L, where (H', W', ...) are the sizes of the visual receptive field in the explained activation layer and L is the number of labels represented within the model’s output logits.

If indices is passed, the specific logits indexed by elements in this tensor are selected before the gradients are computed, effectively reducing the columns in the jacobian, and the size of the output explaining map.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)
model = ke.inspection.expose(model)

scores, cams = ke.methods.cams.gradcampp(model, x, y)

References

  • Chattopadhay, A., Sarkar, A., Howlader, P., & Balasubramanian, V. N. (2018, March). Grad-cam++: Generalized gradient-based visual explanations for deep convolutional networks. In 2018 IEEE winter conference on applications of computer vision (WACV) (pp. 839-847). IEEE.

  • Grad-CAM++’s official implementation. Github. Available at: adityac94/Grad-CAM++

Parameters:

  • model (tf.keras.Model) – the model being explained

  • inputs (tf.Tensor) – the input data

  • indices (Optional[tf.Tensor], optional) – indices that should be gathered from outputs. Defaults to None.

  • indices_axis (int, optional) – the axis containing the indices to gather. Defaults to KERNEL_AXIS.

  • indices_batch_dims (int, optional) – the number of dimensions to broadcast in the tf.gather operation. Defaults to -1.

  • spatial_axis (Tuple[int], optional) – the dimensions containing positional information. Defaults to SPATIAL_AXIS.

Returns:

the logits and Class Activation Maps (CAMs).

Return type:

Tuple[tf.Tensor, tf.Tensor]

scorecam(model, inputs, indices=None, indices_axis=-1, indices_batch_dims=-1, spatial_axis=(-3, -2))[source]

Computes the Score-CAM Visualization Method.

This method expects inputs to be a batch of positional signals of shape BHW...C, and will return a tensor of shape BH'W'...L, where (H', W', ...) are the sizes of the visual receptive field in the explained activation layer and L is the number of labels represented within the model’s output logits.

If indices is passed, the specific logits indexed by elements in this tensor are selected before the gradients are computed, effectively reducing the columns in the jacobian, and the size of the output explaining map.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)
model = ke.inspection.expose(model)

scores, cams = ke.methods.cams.scorecam(model, x, y)

References

  • Score-CAM: Score-Weighted Visual Explanations for Convolutional Neural Networks. Available at: arxiv/1910.01279

Parameters:

  • model (tf.keras.Model) – the model being explained

  • inputs (tf.Tensor) – the input data

  • indices (Optional[tf.Tensor], optional) – indices that should be gathered from outputs. Defaults to None.

  • indices_axis (int, optional) – the axis containing the indices to gather. Defaults to KERNEL_AXIS.

  • indices_batch_dims (int, optional) – the number of dimensions to broadcast in the tf.gather operation. Defaults to -1.

  • spatial_axis (Tuple[int], optional) – the dimensions containing positional information. Defaults to SPATIAL_AXIS.

Returns:

the logits and Class Activation Maps (CAMs).

Return type:

Tuple[tf.Tensor, tf.Tensor]

keras_explainable.methods.gradient module

Implementation of various Gradient-based AI explaining methods and techniques.

full_gradients(model, inputs, indices=None, indices_axis=-1, indices_batch_dims=-1, spatial_axis=(-3, -2), psi=<function absolute_normalize>, biases=None)[source]

Computes the Full-Grad Visualization Method.

This technique adds the individual contributions of each bias factor in the model to the extracted gradient, forming the “full gradient” representation, and it can be summarized by the following equation:

\[f(x) = ψ(∇_xf(x)\odot x) +∑_{l\in L}∑_{c\in c_l} ψ(f^b(x)_c)\]

This method expects inputs to be a batch of positional signals of shape BHW...C, and will return a tensor of shape BH'W'...L, where (H', W', ...) are the sizes of the visual receptive field in the explained activation layer and L is the number of labels represented within the model’s output logits.

If indices is passed, the specific logits indexed by elements in this tensor are selected before the gradients are computed, effectively reducing the columns in the jacobian, and the size of the output explaining map.

Furthermore, the cached list of biases can be passed as a parameter for this method. If none is passed, it will be inferred at runtime, implying on a marginal increase in execution overhead during tracing.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)

logits = ke.inspection.get_logits_layer(model)
inters, biases = ke.inspection.layers_with_biases(model, exclude=[logits])
model = ke.inspection.expose(model, inters, logits)

scores, cams = ke.methods.gradient.full_gradients(model, x, y, biases=biases)

References

  • Srinivas S, Fleuret F. Full-gradient representation for neural network visualization. arxiv.org/1905.00780, 2019.

Parameters:

  • model (tf.keras.Model) – the model being explained

  • inputs (tf.Tensor) – the input data

  • indices (Optional[tf.Tensor], optional) – indices that should be gathered from outputs. Defaults to None.

  • indices_axis (int, optional) – the axis containing the indices to gather. Defaults to KERNEL_AXIS.

  • indices_batch_dims (int, optional) – the number of dimensions to broadcast in the tf.gather operation. Defaults to -1.

  • spatial_axis (Tuple[int], optional) – the dimensions containing positional information. Defaults to SPATIAL_AXIS.

  • psi (Callable, optional) – filter operation before combining the intermediate signals. Defaults to filters.absolute_normalize.

  • biases (Optional[List[Tensor]]) – (List[tf.Tensor], optional): list of biases associated with each intermediate signal exposed by the model. If none is passed, it will be inferred from the endpoints (nodes) outputed by the model.

Returns:

the logits and saliency maps.

Return type:

Tuple[tf.Tensor, tf.Tensor]

gradients(model, inputs, indices=None, indices_axis=-1, indices_batch_dims=-1, spatial_axis=(-3, -2), gradient_filter=<function abs>)[source]

Computes the Gradient Back-propagation Visualization Method.

This technique computes the gradient of the output activation unit being explained with respect to each unit in the input signal. Features (channels) in each pixel of the input sinal are absolutely averaged, following the original implementation:

\[f(x) = ψ(∇_xf(x))\]

This method expects inputs to be a batch of positional signals of shape BHW...C, and will return a tensor of shape BH'W'...L, where (H', W', ...) are the sizes of the visual receptive field in the explained activation layer and L is the number of labels represented within the model’s output logits.

If indices is passed, the specific logits indexed by elements in this tensor are selected before the gradients are computed, effectively reducing the columns in the jacobian, and the size of the output explaining map.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)
scores, cams = ke.methods.gradient.gradients(model, x, y)

References

  • Simonyan, K., Vedaldi, A., & Zisserman, A. (2013). Deep inside convolutional networks: Visualising image classification models and saliency maps. arXiv preprint arXiv:1312.6034.

Parameters:

  • model (tf.keras.Model) – the model being explained

  • inputs (tf.Tensor) – the input data

  • indices (Optional[tf.Tensor], optional) – indices that should be gathered from outputs. Defaults to None.

  • indices_axis (int, optional) – the axis containing the indices to gather. Defaults to KERNEL_AXIS.

  • indices_batch_dims (int, optional) – the number of dimensions to broadcast in the tf.gather operation. Defaults to -1.

  • spatial_axis (Tuple[int], optional) – the dimensions containing positional information. Defaults to SPATIAL_AXIS.

  • gradient_filter (Callable, optional) – filter before channel combining. Defaults to tf.abs.

Returns:

the logits and saliency maps.

Return type:

Tuple[tf.Tensor, tf.Tensor]

keras_explainable.methods.meta module

Implementation of various Meta techniques.

These can be used conjointly with CAM and Gradient-based methods, providing cleaner and more robust results.

smooth(method, repetitions=20, noise=0.1)[source]

Smooth Meta Explaining Method.

This technique consists of repeatedly applying an AI explaining method, considering small variations of the input signal each time (tempered with gaussian noise).

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)

smoothgrad = ke.methods.meta.smooth(
    ke.methods.gradient.gradients,
    repetitions=20,
    noise=0.1,
)

scores, maps = smoothgrad(model, x, y)

References

  • Smilkov, D., Thorat, N., Kim, B., Viégas, F., & Wattenberg, M. (2017). SmoothGrad: removing noise by adding noise. arXiv preprint arXiv:1706.03825. Available at: [arxiv/1706.03825](https://arxiv.org/abs/1706.03825)

Parameters:

  • method (Callable) – the explaining method to be smoothed

  • repetitions (int, optional) – number of repetitions. Defaults to 20.

  • noise (int, optional) – standard deviation of the gaussian noise added to the input signal. Defaults to 0.1.

Returns:

the logits and explaining maps.

Return type:

Tuple[tf.Tensor, tf.Tensor]

tta(method, scales=[0.5, 1.5, 2.0], hflip=True, resize_method='bilinear')[source]

Computes the TTA version of a visualization method.

Usage:

x = np.random.normal((1, 224, 224, 3))
y = np.asarray([[16, 32]])

model = tf.keras.applications.ResNet50V2(classifier_activation=None)

scores, maps = ke.explain(
    methods.gradient.gradients,
    rn50,
    inputs,
    explaining_units,
    postprocessing=filters.absolute_normalize,
)
Parameters:

  • method (Callable) – the explaining method to be augmented

  • scales (List[float], optional) – a list of coefs to scale the inputs by. Defaults to [0.5, 1.5, 2.0].

  • hflip (bool, optional) – wether or not to flip horizontally the inputs. Defaults to True.

  • resize_method (str, optional) – the resizing method used. Defaults to “bilinear”.

Returns:

the logits and explaining maps.

Return type:

Tuple[tf.Tensor, tf.Tensor]

Module contents

View page source