igc.IntGradCorr#

class igc.IntGradCorr(module, dataset, dtld_kwargs=None, forward_method_name=None, forward_method_kwargs=None, n_embedding_categories=None, dtype=torch.float32, dtype_cat=torch.int32)[source]#

Bases: IntegratedGradients

Integrated Gradient Correlation (IGC).

See the original paper [LelievreC24] for more information.

Parameters:

  • module (torch.nn.Module) – PyTorch module defining the model under scrutiny.

  • dataset (torch.utils.data.Dataset) – PyTorch dataset providing inputs/outputs for any given index. See PyTorch documentation for more information. In addition, inputs must be organized in a specific manner, see warning below.

  • dtld_kwargs (dict) – Additional keyword arguments to the dataloaders (torch.utils.data.DataLoader) constructed around the dataset, except: dataset, batch_size, shuffle, sampler, batch_sampler, and generator.

  • forward_method_name (str) – Name of the forward method of the module. If None, the default forward is used.

  • forward_method_kwargs (dict) – Additional keyword arguments to the forward method of the module.

  • n_embedding_categories (None | int | tuple(int)) – Enable the computation of attributions for categorical inputs associated with torch.nn.Embedding layers, by providing the number of embedding categories.

  • dtype (torch.dtype) – Default data type of all intermediary tensors. It also defines the NumPy data type of the attribution results.

  • dtype_cat (torch.dtype) – Default data type of the categorical input tensors.

Notes

Warning

When computing attributions on models using multiple inputs, e.g., x_1, x_2, and x_cat, with x_cat a categorical input, the dataset must return all inputs packed in a tuple, such as: (x_1, x_2, x_cat), y. Note that categorical inputs must be placed at the end of the tuple.

Note

Using categorical inputs with torch.nn.Embedding layers modifies the output shapes of attributions associated with these categorical inputs. The number of embedding categories is appended to original shapes.

add_final_linear_layer(final_linear_layer)[source]#

Add a final linear layer, separated from the forward method.

It accelerates the computation of Integrated Gradients (IG) when the output dimensionality of y is large compared to the size of the latent variable z employed before this final linear layer.

Warning

The effect of this layer must be excluded from the forward method defined by forward_method_name at initialization.

Parameters:

final_linear_layer (torch.nn.Linear | str) – Final linear layer of the module. It can also be defined by its name.

Return type:

self

add_ig_post_function(ig_post_func)[source]#

Add a function to postprocess individual IG attributions.

It may be useful to summarize attributions associated with highly-dimensional inputs at an early stage to spare memory and computing resources. This reduction can be safely conducted by addition over input dimensions using the completeness property of IG.

Warning

IG postprocessing functions must have the following signature:

def ig_post(ig_):
    ig_modified = func(ig_)  # Do something on IG data
    return ig_modified

with ig_ and ig_modified being numpy.ndarray.

Parameters:

ig_post_func (None | function | tuple(None | function)) – Function to postprocess individual IG attributions. When computing attributions on models using multiple inputs, a sequence of IG postprocessing functions is expected. If no IG postprocessing is necessary for a specific input, None can be used to bypass this step.

Return type:

self

compute(x_0=None, y_idx=None, n_steps=64, batch_size=None, x_seed=None, x_0_seed=100, n_x=None, check_error=True)[source]#

Compute Integrated Gradient Correlation (IGC).

Parameters:

  • x_0 (None | int | float | ArrayLike | tuple(ArrayLike)) –

    • None : Zero baseline x_0.

    • int : Number of x_0 baselines sampled from the dataset.

    • float : Constant baseline x_0.

    • ArrayLike | tuple(ArrayLike) : Set x_0 baselines used by x_0_dtld.

  • y_idx (None | int | ArrayLike) –

    • None : y_idx_dtld iterates over all output component indices y_idx.

    • int : Select a specific output component index y_idx.

    • ArrayLike : Select multiple output component indices y_idx.

  • n_steps (int) – Number of steps of the Riemann approximation of supporting Integrated Gradients (IG) (see [STY17] for details).

  • batch_size (None | int | tuple(int)) –

    • None : Set x_bsz = 1, x_0_bsz = n_x_0, and y_idx_bsz = n_y_idx (or z_idx_bsz = n_z_idx).

    • int : Total batch size budget automatically distributed between x_bsz, x_0_bsz, and y_idx_bsz (or z_idx_bsz).

    • tuple(int) : Set x_bsz, x_0_bsz, and y_idx_bsz (or z_idx_bsz) individually.

  • x_seed (None | int) – Seed associated with x_dtld.

  • x_0_seed (None | int) – Seed associated with x_0_dtld.

  • n_x (None | int) –

    • None : x_dtld iterates over the whole dataset.

    • int : Number of x inputs sampled from the dataset.

  • check_error (bool) – If True, the mean absolute error of IG and IGC approximations is reported. For each input, baseline, and output component, the Completeness property of IG states that the sum of input component attributions must be equal to the difference between the model predictions associated with the input and baseline under scrutiny. For each output component, the completeness property of IGC states that the sum of input component attributions must be equal to the correlation between model predictions and true outputs.

Returns:

IGC attributions of shape (n_y_idx, * unbatched x shape)

Return type:

ArrayLike | tuple(ArrayLike)

error(igc, y_idx=None, batch_size=None, x_seed=None, n_x=None)[source]#

Compute IGC error.

Parameters:

  • igc (ArrayLike | tuple(ArrayLike)) – IGC attributions of shape (n_y_idx, * unbatched x shape)

  • y_idx (None | int | ArrayLike) – Selected output component indices. If None, y_idx is resolved to all output component indices.

  • batch_size (None | int) –

    • None : Set x_bsz = 1.

    • int : Set x_bsz.

  • x_seed (None | int) – Seed associated with x_dtld.

  • n_x (None | int) –

    • None : x_dtld iterates over the whole dataset.

    • int : Number of x inputs sampled from the dataset.

Returns:

Per output component mean absolute error of IGC approximations. For each output component, the completeness property of IGC states that the sum of input component attributions must be equal to the correlation between model predictions and true outputs.

Return type:

ArrayLike