igc.Gradients#

class igc.Gradients(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: AbstractAttributionMethod

Gradients.

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.

compute(x, y_idx=None, batch_size=None, x_seed=None)[source]#

Compute gradients.

Parameters:

  • x (None | int | ArrayLike | tuple(ArrayLike)) –

    • None : x_dtld iterates over the whole dataset.

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

    • ArrayLike | tuple(ArrayLike) : Set new x used by x_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.

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

    • None : Set x_bsz = 1 and y_idx_bsz = n_y_idx.

    • int : Total batch size budget automatically distributed between x_bsz and y_idx_bsz.

    • tuple(int) : Set x_bsz and y_idx_bsz individually.

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

Returns:

  • ArrayLike | tuple(ArrayLike) : sampled inputs

  • ArrayLike : corresponding true outputs

  • ArrayLike : model predictions

  • ArrayLike | tuple(ArrayLike) : gradients of shape (n_x, n_y_idx, * unbatched x shape)

Return type:

tuple