EnsembleXAI.Ensemble module

EnsembleXAI.Ensemble.autoweighted(inputs: TensorOrTupleOfTensorsGeneric, metric_weights: List[float], metrics: List[Callable] | None = None, precomputed_metrics: Any | ndarray | Tensor | None = None) → Tensor

Aggregate explanations weighted by their quality measured by metrics.

This function in an implementation of explanation ensemble algorithm published in [1]. It uses EnsembleXAI.Metrics.ensemble_score() to calculate quality of each explanation. One of metrics or precomputed_metrics should be passed.

Parameters:

inputs (TensorOrTupleOfTensorsGeneric) – Explanations in form of tuple of tensors or tensor. inputs dimensions correspond to no. of observations, no. of explanations for each observation, and single explanation.
metrics (List[Callable], default None) – Metrics used to assess the quality of an explanation. Ignored when precomputed_metrics is not None.
metric_weights (List[float]) – Weights used to calculate EnsembleXAI.Metrics.ensemble_score() of every explanation.
precomputed_metrics (Any, default None) – Metrics’ values can be precomputed and passed as an argument. Need to be in 3 dimensional format where dimensions correspond to observations, explanations and metrics. Supported formats are numpy ndarray and torch tensor.

Returns:

Weighted arithmetic mean of explanations, weighted by EnsembleXAI.Metrics.ensemble_score(). Dimensions correspond to no. of observations, aggregated explanation.

Return type:

Tensor

See also

normEnsembleXAI: Simple aggregation by function, like average.
supervisedXAI: Use Kernel Ridge Regression for aggregation, suitable when masks are available.

Notes

Explanations are normalized by mean and standard deviation before aggregation to ensure comparable values.

References

[1]

Bobek, S., Bałaga, P., Nalepa, G.J. (2021), “Towards Model-Agnostic Ensemble Explanations.” In: Paszynski, M., Kranzlmüller, D., Krzhizhanovskaya, V.V., Dongarra, J.J., Sloot, P.M. (eds) Computational Science – ICCS 2021. ICCS 2021. Lecture Notes in Computer Science(), vol 12745. Springer, Cham. https://doi.org/10.1007/978-3-030-77970-2_4

Examples

>>> import torch
>>> from EnsembleXAI.Ensemble import autoweighted
# We have a tensor of 4 explanations for 15 observations,
# each with 3 channels and image size 32 x 32
>>> explanations = torch.randn(15, 4, 3, 32, 32)
# We use precomputed metrics
# 2 metrics to evaluate each of 4 explanation for 15 observations
>>> metrics = torch.rand(size=(15, 4, 2))
>>> ensembled_explanations = autoweighted(explanations,
...                                       metric_weights=[0.2, 0.8],
...                                       precomputed_metrics=metrics)

EnsembleXAI.Ensemble.normEnsembleXAI(inputs: TensorOrTupleOfTensorsGeneric, aggregating_func: str | Callable[[Tensor], Tensor]) → Tensor

Aggregate explanations in the simplest way.

Use provided aggregating functions or pass a custom callable. Combine explanations for every observation and get one aggregated explanation for every observation.

Parameters:

inputs (TensorOrTupleOfTensorsGeneric) – Explanations in form of tuple of tensors or tensor. inputs dimensions correspond to no. of observations, no. of explanations for each observation, and single explanation.
aggregating_func (Union[str, Callable[[Tensor], Tensor]]) – Aggregating function. Can be string, one of ‘avg’, ‘min’, ‘max’, or a function from a list of tensors to tensor.

Returns:

Aggregated explanations. Dimensions correspond to no. of observations, aggregated explanation.

Return type:

Tensor

See also

autoweighted: Aggregation weighted by quality of each explanation.
supervisedXAI: Use Kernel Ridge Regression for aggregation, suitable when masks are available.

Examples

>>> import torch
>>> from EnsembleXAI.Ensemble import normEnsembleXAI
>>> from captum.attr import IntegratedGradients, GradientShap, Saliency
>>> net = ImageClassifier()
>>> inputs = torch.randn(1, 3, 32, 32)
>>> ig = IntegratedGradients(net).attribute(inputs, target=3)
>>> gs = GradientShap(net).attribute(inputs, target=3)
>>> sal = Saliency(net).attribute(inputs, target=3)
>>> explanations = torch.stack([ig, gs, sal], dim=1)
>>> agg = normEnsembleXAI(explanations, 'avg')

EnsembleXAI.Ensemble.supervisedXAI(inputs: TensorOrTupleOfTensorsGeneric, masks: TensorOrTupleOfTensorsGeneric, n_folds: int = 3, weights: str | TensorOrTupleOfTensorsGeneric | ndarray | None = None, shuffle=False, random_state=None) → Tensor

Aggregate explanations by training supervised machine learning model.

This function in an implementation of explanation ensemble algorithm published in [1]. It uses sklearn.kernel_ridge.KernelRidge to train the Kernel Ridge Regression (KRR) model with explanations as inputs \(X\) and masks as output \(y\). K-Fold split is used to generate aggregated explanations without information leakage. Internally uses sklearn.model_selection.KFold to make the split.

Parameters:

inputs (TensorOrTupleOfTensorsGeneric) – Explanations in form of tuple of tensors or tensor. inputs dimensions correspond to no. of observations, no. of explanations for each observation, and single explanation.
masks (TensorOrTupleOfTensorsGeneric) – Masks used by KRR model as output. Should be 3 dimensional shape, where dimensions correspond to no. of observations, and single mask. Size of single mask should be the same as size of single explanation in inputs.
n_folds (int, default 3) – Number of folds used to train the KRR model. n_folds should be an int greater than 1. When n_folds is equal to no. of observations in inputs, “leave one out” training is done.
weights (Union[str, TensorOrTupleOfTensorsGeneric, np.ndarray, None], default None) – Sample weights for training the KRR. If None, weights are uniform. If ‘auto’, weight of an observation is inversely proportional to the area of the observation’s mask. Can be also provided as tensor, list, tuple or numpy array of custom values. Weights can be used to promote smaller masks.
shuffle (Any, default False) – If True inputs and masks will be shuffled before k-fold split. Internally passed to sklearn.model_selection.KFold.
random_state (Any, default None) – Used only when shuffle is True. Internally passed to sklearn.model_selection.KFold.

Returns:

Tensor of KRR model outputs, which are the aggregated explanations. It has 3 dimensions.

Return type:

Tensor