innvestigate.utils

innvestigate.utils.model_wo_softmax(*args, **kwargs)
innvestigate.utils.to_list(l)

If not list, wraps parameter into a list.

class innvestigate.utils.BatchSequence(Xs, batch_size=32)

Batch sequence generator.

Take a (list of) input tensors and a batch size and creates a generators that creates a sequence of batches.

Parameters:
  • Xs – One or a list of tensors. First axis needs to have same length.
  • batch_size – Batch size. Default 32.
class innvestigate.utils.TargetAugmentedSequence(sequence, augment_f)

Augments a sequence with a target on the fly.

Takes a sequence/generator and a function that creates on the fly for each batch a target. The generator takes a batch from that sequence, computes the target and returns both.

Parameters:
  • sequence – A sequence or generator.
  • augment_f – Takes a batch and returns a target.
innvestigate.utils.preprocess_images(images, color_coding=None)

Image preprocessing

Takes a batch of images and: * Adjust the color axis to the Keras format. * Fixes the color coding.

Parameters:
  • images – Batch of images with 4 axes.
  • color_coding – Determines the color coding. Can be None, ‘RGBtoBGR’ or ‘BGRtoRGB’.
Returns:

The preprocessed batch.
innvestigate.utils.postprocess_images(images, color_coding=None, channels_first=None)

Image postprocessing

Takes a batch of images and reverts the preprocessing.

Parameters:
  • images – A batch of images with 4 axes.
  • color_coding – The initial color coding, see preprocess_images().
  • channels_first – The output channel format.
Returns:

The postprocessed images.

Visualizations

innvestigate.utils.visualizations.project(X, output_range=(0, 1), absmax=None, input_is_positive_only=False)

Projects a tensor into a value range.

Projects the tensor values into the specified range.

Parameters:
  • X – A tensor.
  • output_range – The output value range.
  • absmax – A tensor specifying the absmax used for normalizing. Default the absmax along the first axis.
  • input_is_positive_only – Is the input value range only positive.
Returns:

The tensor with the values project into output range.
innvestigate.utils.visualizations.heatmap(X, cmap_type='seismic', reduce_op='sum', reduce_axis=-1, alpha_cmap=False, **kwargs)

Creates a heatmap/color map.

Create a heatmap or colormap out of the input tensor.

Parameters:
  • X – A image tensor with 4 axes.
  • cmap_type – The color map to use. Default ‘seismic’.
  • reduce_op – Operation to reduce the color axis. Either ‘sum’ or ‘absmax’.
  • reduce_axis – Axis to reduce.
  • alpha_cmap – Should the alpha component of the cmap be included.
  • kwargs – Arguments passed on to project()
Returns:

The tensor as color-map.
innvestigate.utils.visualizations.graymap(X, **kwargs)

Same as heatmap() but uses a gray colormap.

innvestigate.utils.visualizations.gamma(X, gamma=0.5, minamp=0, maxamp=None)

Apply gamma correction to an input array X while maintaining the relative order of entries, also for negative vs positive values in X. the fxn firstly determines the max amplitude in both positive and negative direction and then applies gamma scaling to the positive and negative values of the array separately, according to the common amplitude.

Parameters:
  • gamma – the gamma parameter for gamma scaling
  • minamp – the smallest absolute value to consider. if not given assumed to be zero (neutral value for relevance, min value for saliency, …). values above and below minamp are treated separately.
  • maxamp – the largest absolute value to consider relative to the neutral value minamp if not given determined from the given data.
innvestigate.utils.visualizations.clip_quantile(X, quantile=1)

Clip the values of X into the given quantile.

Keras-Utils

innvestigate.utils.keras.graph.copy_layer(layer, keep_bias=True, name_template=None, weights=None, reuse_symbolic_tensors=True, **kwargs)

Copy a Keras layer

Copies a Keras layer.

Parameters:
  • layer – A layer that should be copied.
  • keep_bias – Keep a potential bias.
  • weights – Weights to set in the new layer. Options: np tensors, symbolic tensors, or None, in which case the weights from old_layers are used.
  • reuse_symbolic_tensors – If the weights of the old_layer are used copy the symbolic ones or copy the Numpy weights.
Returns:

The new layer instance.
innvestigate.utils.keras.graph.model_wo_softmax(model)

Creates a new model w/o the final softmax activation.

innvestigate.utils.keras.graph.get_model_execution_graph(model, keep_input_layers=False)

Returns a dictionary representing the execution graph. Each key is the node’s id as it is used by the reverse_model method.

Each associated value contains a dictionary with the following items:

  • nid: the node id.
  • layer: the layer creating this node.
  • Xs: the input tensors (only valid if not in a nested container).
  • Ys: the output tensors (only valid if not in a nested container).
  • Xs_nids: the ids of the nodes creating the Xs.
  • Ys_nids: the ids of nodes using the according output tensor.
  • Xs_layers: the layer that created the accodring input tensor.
  • Ys_layers: the layers using the according output tensor.
Parameters:
  • model – A kera model.
  • keep_input_layers – Keep input layers.
innvestigate.utils.keras.graph.reverse_model(model, reverse_mappings, default_reverse_mapping=None, head_mapping=None, stop_mapping_at_tensors=[], verbose=False, return_all_reversed_tensors=False, clip_all_reversed_tensors=False, project_bottleneck_tensors=False, execution_trace=None, reapply_on_copied_layers=False)

Reverses a Keras model based on the given reverse functions. It returns the reverted tensors for the according model inputs.

Parameters:
  • model – A Keras model.
  • reverse_mappings –

    Either a callable that matches layers to mappings or a dictionary with layers as keys and mappings as values. Allowed as mapping forms are:

    • A function of form (A) f(Xs, Ys, reversed_Ys, reverse_state).
    • A function of form f(B) f(layer, reverse_state) that returns a function of form (A).
    • A ReverseMappingBase subclass.
  • default_reverse_mapping – A function that reverses layers for which no mapping was given by param “reverse_mappings”.
  • head_mapping – Map output tensors to new values before passing them into the reverted network.
  • stop_mapping_at_tensors – Tensors at which to stop the mapping. Similar to stop_gradient parameters for gradient computation.
  • verbose – Print what’s going on.
  • return_all_reversed_tensors – Return all reverted tensors in addition to reverted model input tensors.
  • clip_all_reversed_tensors – Clip each reverted tensor. False or tuple with min/max value.
  • project_bottleneck_tensors – Project bottleneck layers in the reverting process into a given value range. False, True or (a, b) for projection range.
  • reapply_on_copied_layers – When a model execution needs to linearized and copy layers before reapplying them. See trace_model_execution().