igc.bsc.BslShapCorr#

class igc.bsc.BslShapCorr(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: BaselineShapley

Baseline Shapley Correlation (BSC).

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) – 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

Note

Using categorical inputs with torch.nn.Embedding layers modifies the output shape of attributions associated with this categorical input. The number of embedding categories is added at the end of the original shape.

compute(x_0=None, y_idx=None, n_iter=8, x_0_batch_size=1, x_seed=None, x_0_seed=100, n_x=None, check_error=True)[source]#

Compute Baseline Shapley Correlation (BSC).

Warning

Baseline Shapley Correlation (BSC) does not support multiple inputs.

Parameters:

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

    • None : Zero baseline x_0.

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

    • float : Constant baseline x_0.

    • 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_iter (int) – Number of iterations, i.e. the number of random sequences of input component indices enabled one after the other.

  • x_0_batch_size (None | int) –

    • None : Set x_0_bsz = n_x_0.

    • int : Set x_0_bsz.

  • 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 BS and BSC approximations is reported. For each input, baseline, and output component, the Completeness property of BS 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 BSC states that the sum of input component attributions must be equal to the correlation between model predictions and true outputs.

Returns:

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

Return type:

ArrayLike

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

Compute BSC error.

Parameters:

  • bsc (ArrayLike) – BSC 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 (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 BSC approximations. For each output component, the completeness property of BSC states that the sum of input component attributions must be equal to the correlation between model predictions and true outputs.

Return type:

ArrayLike