keras_explainable package

Subpackages

Submodules

keras_explainable.filters module

Shortcuts for commonly used signal filters used in literature.

These filters can be used as post or mid processing for explaining methods and techniques.

absolute_normalize(x, axis=(-3, -2))[source]

Absolute values of the input signal and normalize it between 0 and 1.

Parameters:

  • x (tf.Tensor) – the input signal.

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

Returns:

the filtered signal.

Return type:

tf.Tensor

negative(x, axis=(-3, -2))[source]

Retain only negative values of the input signal.

Usage:

x = np.asarray([0, -1, 2, -3])
y = ke.filters.negative(x).numpy()
print(f"{x} -> {y}")

[ 0 -1  2 -3] -> [0 0 2 0]
Parameters:

  • x (tf.Tensor) – the input

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

Returns:

the filtered signal.

Return type:

tf.Tensor

negative_normalize(x, axis=(-3, -2))[source]

Retain only negative values of the input signal and normalize it between 0 and 1.

Parameters:

  • x (tf.Tensor) – the input signal.

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

Returns:

the filtered signal.

Return type:

tf.Tensor

normalize(x, axis=(-3, -2))[source]

Normalize the signal into the interval [0, 1].

Usage:

x = 5 * np.random.normal(size=(4, 16, 16, 3)).round(1)
y = ke.filters.absolute_normalize(x).numpy()
print(f"[{x.min()}, {x.max()}] -> [{y.min()}, {y.max()}]")

[-15.0, 18.5] -> [0.0, 1.0]
Parameters:

  • x (tf.Tensor) – the input signal to be normalized.

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

Returns:

the normalized signal.

Return type:

tf.Tensor

positive(x, axis=(-3, -2))[source]

Retain only positive values of the input signal.

Usage:

x = np.asarray([0, -1, 2, -3])
y = ke.filters.positive(x).numpy()
print(f"{x} -> {y}")

[ 0 -1  2 -3] -> [0 0 2 0]
Parameters:

  • x (tf.Tensor) – the input signal.

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

Returns:

the filtered signal.

Return type:

tf.Tensor

positive_normalize(x, axis=(-3, -2))[source]

Retain only positive values of the input signal and normalize it between 0 and 1.

Parameters:

  • x (tf.Tensor) – the input signal.

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

Returns:

the filtered signal.

Return type:

tf.Tensor

keras_explainable.inspection module

Inspection utils for models and layers.

biases(layers)[source]

Recursively retrieve the biases from layers.

Layers containing implicit bias are unrolled before returned. For instance, the Batch Normalization layer, whose equation is defined by \(y(x) = \frac{x - \mu}{\sigma} w + b\), will have bias equals to:

\[\frac{-\mu w}{s} + b\]
Parameters:

layers (List[Layer]) – a list of layers from which biases should be extracted.

Returns:

a list of all biases retrieved.

Return type:

List[tf.Tensor]

endpoints(model, endpoints)[source]

Collect intermediate endpoints in a model based on structured descriptors.

Parameters:

  • model (Model) – the model containing the endpoints to be collected.

  • endpoints (List[E]) – descriptors of endpoints that should be collected.

Raises:

ValueError – raised whenever one of the endpoint descriptors is invalid or it does not describe a nested layer in the model.

Returns:

a list containing the endpoints of interest.

Return type:

List[KerasTensor]

expose(model, arguments=None, outputs=None)[source]

Creates a new model that exposes all endpoints described by arguments and outputs.

Parameters:

  • model (Model) – The model being explained.

  • arguments (Optional[E], optional) – Name of the argument layer/tensor in the model. The jacobian of the output explaining units will be computed with respect to the input signal of this layer. This argument can also be an integer, a dictionary representing the intermediate signal or the pooling layer itself. If None is passed, the penultimate layer is assumed to be a GAP layer. Defaults to None.

  • outputs (Optional[E], optional) – Name of the output layer in the model. The jacobian will be computed for the activation signal of units in this layer. This argument can also be an integer, a dictionary representing the output signal and the logits layer itself. If None is passed, the last layer is assumed to be the logits layer. Defaults to None.

Returns:

the exposed model, whose outputs contain the intermediate and output tensors.

Return type:

Model

find_layer_with(model, name=None, properties=None, klass=None, search_reversed=True)[source]

Find a layer within a model that satisfies all required properties.

Parameters:

  • model (Model) – the container model.

  • name (Optional[str], optional) – the name of the layer, if known. Defaults to None.

  • properties (Optional[Tuple[str]], optional) – a list of properties that should be visible from the searched layer. Defaults to None.

  • klass (Optional[Tuple[Type[Layer]]], optional) – a collection of classes allowed for the searched layer. Defaults to None.

  • search_reversed (bool, optional) – wether to search from last-to-first. Defaults to True.

Raises:

  • ValueError – if no search parameters are passed.

  • ValueError – if no valid layer can be found with the specified search parameters.

Returns:

the layer satisfying all search parameters.

Return type:

Layer

gather_units(tensor, indices, axis=-1, batch_dims=-1)[source]

Gather units (in the last axis) from a tensor.

Parameters:

  • tensor (tf.Tensor) – the input tensor.

  • indices (tf.Tensor, optional) – the indices that should be gathered.

  • axis (int, optional) – the axis from which indices should be taken, used to fine control gathering. Defaults to -1.

  • batch_dims (int, optional) – the number of batch dimensions, used to fine control gathering. Defaults to -1.

Returns:

the gathered units

Return type:

tf.Tensor

get_global_pooling_layer(model, name=None)[source]

Retrieve the last global pooling layer.

Parameters:

  • model (Model) – the model containing the pooling layer.

  • name (str, optional) – the name of the layer, if known. Defaults to None.

Raises:

ValueError – if a pooling layer cannot be found

Returns:

the retrieved pooling layer

Return type:

Layer

get_logits_layer(model, name=None)[source]

Retrieve the “logits” layer.

Parameters:

  • model (Model) – the model containing the logits layer.

  • name (str, optional) – the name of the layer, if known. Defaults to None.

Raises:

ValueError – if a logits layer cannot be found

Returns:

the retrieved logits layer

Return type:

Layer

get_nested_layer(model, name)[source]

Retrieve a nested layer in the model.

Parameters:

  • model (Model) – the model containing the nested layer.

  • name (Union[str, List[str]]) – a string (or list of string) containing the name of the layer (or a list of names, each of which references a recursively nested module up to the layer of interest).

Example:

model = tf.keras.Sequential([
    tf.keras.applications.ResNet101V2(include_top=False, pooling='avg'),
    tf.keras.layers.Dense(10, activation='softmax', name='predictions')
])

pooling_layer = get_nested_layer(model, ('resnet101v2', 'avg_pool'))
Raises:

ValueError – if name is not a nested member of model.

Returns:

the retrieved layer.

Return type:

tf.keras.layer.Layer

layers_with_biases(model, exclude=(), return_biases=True)[source]

Extract layers containing biases from a model.

Parameters:

  • model (Model) – the model inspected.

  • exclude (Tuple[Layer], optional) – a list of layers to ignore. Defaults to ().

  • return_biases (bool, optional) – wether or not to return the biases as well. Defaults to True.

Returns:

a list of layers. List[Layer], List[tf.Tensor]: a list of layers and biases.

Return type:

List[Layer]

keras_explainable.utils module

get_dims(image)[source]
tolist(item)[source]
visualize(images, titles=None, overlays=None, overlay_alpha=0.75, rows=None, cols=None, figsize=None, cmap=None, overlay_cmap=None, to_file=None, to_buffer=None, subplots_ws=0.0, subplots_hs=0.0)[source]

Module contents

Keras Explainable Library.

Efficient explaining AI algorithms for Keras models.

cam(*args, **params)

Shortcut for methods.cams.cam(), filtering positively contributing regions.

explain(method, model, x, y=None, batch_size=None, verbose='auto', steps=None, callbacks=None, max_queue_size=10, workers=1, use_multiprocessing=False, force=True, **method_params)[source]

Explain the outputs of model with respect to the inputs or an intermediate signal, using an AI explaining 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(
    ke.methods.gradient.gradients,
    model, x, y,
    postprocessing=filters.absolute_normalize,
)
Parameters:

  • method (Callable) – An AI explaining function, as the ones contained in methods module.

  • model (tf.keras.Model) – The model whose predictions should be explained.

  • x (Union[np.ndarray, tf.Tensor, tf.data.Dataset]) – the input data for the model.

  • y (Optional[Union[np.ndarray, tf.Tensor]], optional) – the indices in the output tensor that should be explained. If none, an activation map is computed for each unit. Defaults to None.

  • batch_size (Optional[int], optional) – the batch size used by method. Defaults to 32.

  • verbose (Union[str, int], optional) – wether to show a progress bar during the calculation of the explaining maps. Defaults to “auto”.

  • steps (Optional[int], optional) – the number of steps, if x is a tf.data.Dataset of unknown cardinallity. Defaults to None.

  • callbacks (List[Callback], optional) – list of callbacks called during the explaining procedure. Defaults to None.

  • max_queue_size (int, optional) – the queue size when retrieving inputs. Used if x is a generator. Defaults to 10.

  • workers (int, optional) – the number of workers used when retrieving inputs. Defaults to 1.

  • use_multiprocessing (bool, optional) – wether to employ multi-process or multi-threading when retrieving inputs, when x is a generator. Defaults to False.

  • force (bool, optional) – to force the creation of the explaining function. Can be set to False if the same function is always applied to a model, avoiding retracing. Defaults to True.

Besides the parameters described above, any named parameters passed to this function will be collected into methods_params and passed onto the explain_step() and method functions. The most common ones are:

  • indices_batch_dims (int): The dimensions marked as batch when gathering units described by y. Ignore if y is None.

  • indices_axis (int): The axes from which to gather units described by y. Ignore if y is None.

  • spatial_axis (Tuple[int]): The axes containing the positional visual info. We assume inputs to contain 2D images or videos in the shape (B1, B2, …, BN, H, W, 3). For 3D image data, set spatial_axis to (1, 2, 3) or (-4, -3, -2).

  • postprocessing (Callable): A function to process the activation maps before normalization (most commonly adopted being maximum(x, 0) and abs).

Raises:

ValueError – the explaining method produced in an unexpected.

Returns:

logits and explaining maps tensors.

Return type:

Tuple[np.ndarray, np.ndarray]

full_gradients(*args, **params)

Shortcut for methods.gradient.full_gradients(), filtering absolutely contributing regions.

gradcam(*args, **params)

Shortcut for methods.cams.gradcam(), filtering positively contributing regions.

gradcampp(*args, **params)

Shortcut for methods.cams.gradcampp(), filtering positively contributing regions.

gradients(*args, **params)

Shortcut for methods.gradient.gradients(), filtering absolutely contributing regions.

scorecam(*args, **params)

Shortcut for methods.cams.scorecam(), filtering positively contributing regions.

View page source