XAI Inverse Estimation

CONTRIBUTING.md

@@ -89,7 +89,7 @@ It is possible to limit the scope of testing to specific sections of the codebas
 Faithfulness metrics using python3.9 (make sure the python versions match in your environment):
 
 ```bash
-python3 -m tox run -e py39 -- -m evaluate_func -s
+python3 -m tox run -e py39 -- -m faithfulness -s
 ```
 
 For a complete overview of the possible testing scopes, please refer to `pytest.ini`.

quantus/evaluation.py

@@ -12,9 +12,7 @@
 import numpy as np
 import pandas as pd
 
-from quantus.helpers import asserts
-from quantus.helpers import utils
-from quantus.helpers import warn
+from quantus.helpers import asserts, utils, warn
 from quantus.helpers.model.model_interface import ModelInterface
 from quantus.functions.explanation_func import explain
 
@@ -162,6 +160,8 @@ def evaluate(
 
     if call_kwargs is None:
         call_kwargs = {"call_kwargs_empty": {}}
+    elif not isinstance(call_kwargs, Dict):
+        raise TypeError("call_kwargs type should be of Dict[str, Dict] (if not None).")
 
     elif not isinstance(call_kwargs, Dict):
         raise TypeError("call_kwargs type should be of Dict[str, Dict] (if not None).")
@@ -205,7 +205,7 @@ def evaluate(
             a_batch = utils.expand_attribution_channel(a_batch, x_batch)
 
             # Asserts.
-            asserts.assert_attributions(a_batch=a_batch, x_batch=x_batch)
+            warn.warn_attributions(a_batch=a_batch, x_batch=x_batch)
 
         elif isinstance(value, Dict):
 
@@ -226,7 +226,7 @@ def evaluate(
             a_batch = utils.expand_attribution_channel(a_batch, x_batch)
 
             # Asserts.
-            asserts.assert_attributions(a_batch=a_batch, x_batch=x_batch)
+            warn.warn_attributions(a_batch=a_batch, x_batch=x_batch)
 
         elif isinstance(value, np.ndarray):
             explain_funcs[method] = explain
@@ -241,11 +241,11 @@ def evaluate(
         if explain_func_kwargs is None:
             explain_func_kwargs = {}
 
-        for (metric, metric_func) in metrics.items():
+        for metric, metric_func in metrics.items():
 
             results[method][metric] = {}
 
-            for (call_kwarg_str, call_kwarg) in call_kwargs.items():
+            for call_kwarg_str, call_kwarg in call_kwargs.items():
 
                 if verbose:
                     print(
@@ -287,8 +287,8 @@ def evaluate(
         # Clean up the results if there is only one call_kwarg.
         for method, value in xai_methods.items():
             results_ordered[method] = {}
-            for (metric, metric_func) in metrics.items():
-                for (call_kwarg_str, call_kwarg) in call_kwargs.items():
+            for metric, metric_func in metrics.items():
+                for call_kwarg_str, call_kwarg in call_kwargs.items():
                     results_ordered[method][metric] = results[method][metric][
                         call_kwarg_str
                     ]

quantus/functions/explanation_func.py

@@ -671,7 +671,7 @@ def f_reduce_axes(a):
             inputs = inputs.cpu()
 
         inputs_numpy = inputs.detach().numpy()
-                
+
         for i in range(len(explanation)):
             explanation[i] = torch.Tensor(
                 np.clip(scipy.ndimage.sobel(inputs_numpy[i]), 0, 1)

quantus/helpers/asserts.py

@@ -8,6 +8,7 @@
 
 
 from typing import Callable, Tuple, Sequence, Union
+import warnings
 import numpy as np
 
 
@@ -128,74 +129,6 @@ def assert_layer_order(layer_order: str) -> None:
     assert layer_order in ["top_down", "bottom_up", "independent"]
 
 
-def assert_attributions(x_batch: np.array, a_batch: np.array) -> None:
-    """
-    Asserts on attributions, assumes channel first layout.
-
-    Parameters
-    ----------
-    x_batch: np.ndarray
-         The batch of input to compare the shape of the attributions with.
-    a_batch: np.ndarray
-         The batch of attributions.
-
-    Returns
-    -------
-    None
-    """
-    assert (
-        type(a_batch) == np.ndarray
-    ), "Attributions 'a_batch' should be of type np.ndarray."
-    assert np.shape(x_batch)[0] == np.shape(a_batch)[0], (
-        "The inputs 'x_batch' and attributions 'a_batch' should "
-        "include the same number of samples."
-        "{} != {}".format(np.shape(x_batch)[0], np.shape(a_batch)[0])
-    )
-    assert np.ndim(x_batch) == np.ndim(a_batch), (
-        "The inputs 'x_batch' and attributions 'a_batch' should "
-        "have the same number of dimensions."
-        "{} != {}".format(np.ndim(x_batch), np.ndim(a_batch))
-    )
-    a_shape = [s for s in np.shape(a_batch)[1:] if s != 1]
-    x_shape = [s for s in np.shape(x_batch)[1:]]
-    assert a_shape[0] == x_shape[0] or a_shape[-1] == x_shape[-1], (
-        "The dimensions of attribution and input per sample should correspond in either "
-        "the first or last dimensions, but got shapes "
-        "{} and {}".format(a_shape, x_shape)
-    )
-    assert all([a in x_shape for a in a_shape]), (
-        "All attribution dimensions should be included in the input dimensions, "
-        "but got shapes {} and {}".format(a_shape, x_shape)
-    )
-    assert all(
-        [
-            x_shape.index(a) > x_shape.index(a_shape[i])
-            for a in a_shape
-            for i in range(a_shape.index(a))
-        ]
-    ), (
-        "The dimensions of the attribution must correspond to dimensions of the input in the same order, "
-        "but got shapes {} and {}".format(a_shape, x_shape)
-    )
-    assert not np.all((a_batch == 0)), (
-        "The elements in the attribution vector are all equal to zero, "
-        "which may cause inconsistent results since many metrics rely on ordering. "
-        "Recompute the explanations."
-    )
-    assert not np.all((a_batch == 1.0)), (
-        "The elements in the attribution vector are all equal to one, "
-        "which may cause inconsistent results since many metrics rely on ordering. "
-        "Recompute the explanations."
-    )
-    assert len(set(a_batch.flatten().tolist())) > 1, (
-        "The attributions are uniformly distributed, "
-        "which may cause inconsistent results since many "
-        "metrics rely on ordering."
-        "Recompute the explanations."
-    )
-    assert not np.all((a_batch < 0.0)), "Attributions should not all be less than zero."
-
-
 def assert_segmentations(x_batch: np.array, s_batch: np.array) -> None:
     """
     Asserts on segmentations, assumes channel first layout.

quantus/helpers/constants.py

@@ -27,7 +27,7 @@
         "Faithfulness Correlation": FaithfulnessCorrelation,
         "Faithfulness Estimate": FaithfulnessEstimate,
         "Pixel-Flipping": PixelFlipping,
-        "Region Segmentation": RegionPerturbation,
+        "Region Perturbation": RegionPerturbation,
         "Monotonicity-Arya": Monotonicity,
         "Monotonicity-Nguyen": MonotonicityCorrelation,
         "Selectivity": Selectivity,
@@ -74,6 +74,15 @@
     },
 }
 
+# Quantus metrics that include a step-wise 'masking'/ perturbation that is
+# based on attribution order/ ranking (and not magnitude).
+AVAILABLE_INVERSE_ESTIMATION_METRICS = {
+    "Pixel-Flipping": PixelFlipping,
+    "Region Perturbation": RegionPerturbation,  # order = 'morf'
+    "ROAD": ROAD,  # return_only_values = True
+    "Selectivity": Selectivity,
+}
+#
 
 AVAILABLE_PERTURBATION_FUNCTIONS = {
     "baseline_replacement_by_indices": baseline_replacement_by_indices,

quantus/helpers/model/pytorch_model.py

@@ -362,6 +362,38 @@ def sample(
                         )
         return model_copy
 
+    def perturb_layer_weights(self, layer_idx: int, noise: float):
+        """
+        Perturb the weights of a specific layer in a PyTorch model.
+
+        Parameters
+        ----------
+        model : torch.nn.Module
+            The PyTorch model.
+        layer_idx : int
+            The index of the layer to perturb.
+        noise : float
+            The standard deviation of the Gaussian noise to add to the weights.
+
+        Returns
+        -------
+        None
+        """
+        original_parameters = self.state_dict()
+        model_copy = deepcopy(self.model)
+        model_copy.load_state_dict(original_parameters)
+
+        # Get the specific layer.
+        layer = list(model_copy.modules())[layer_idx]
+
+        # Generate Gaussian noise.
+        noise_tensor = torch.randn_like(layer.weight) * noise
+
+        # Add the noise to the layer's weights.
+        layer.weight.data.add_(noise_tensor)
+
+        return model_copy
+
     def add_mean_shift_to_first_layer(
         self,
         input_shift: Union[int, float],

quantus/helpers/perturbation_utils.py

@@ -28,7 +28,23 @@ def __call__(
 def make_perturb_func(
     perturb_func: PerturbFunc, perturb_func_kwargs: Mapping[str, ...] | None, **kwargs
 ) -> PerturbFunc | functools.partial:
-    """A utility function to save few lines of code during perturbation metric initialization."""
+    """
+    A utility function to save few lines of code during perturbation metric initialization.
+
+    Parameters
+    ----------
+    perturb_func: callable
+        Perturbation function.
+    perturb_func_kwargs: dict
+        Perturbation function kwargs.
+    kwargs: dict
+        Perturbation metric kwargs.
+
+    Returns
+    -------
+    perturb_func: callable
+        Perturbation function.
+    """
     if perturb_func_kwargs is not None:
         func_kwargs = kwargs.copy()
         func_kwargs.update(perturb_func_kwargs)
@@ -41,7 +57,19 @@ def make_perturb_func(
 def make_changed_prediction_indices_func(
     return_nan_when_prediction_changes: bool,
 ) -> Callable[[ModelInterface, np.ndarray, np.ndarray], List[int]]:
-    """A utility function to improve static analysis."""
+    """
+    A utility function to improve static analysis.
+
+    Parameters
+    ----------
+    return_nan_when_prediction_changes: boolean
+        Indicates if metric should return NaN when model prediction changes due to perturbation.
+
+    Returns
+    -------
+    changed_prediction_indices: callable
+        Function that returns indices in batch, for which predicted label has changed after applying perturbation.
+    """
     return functools.partial(
         changed_prediction_indices,
         return_nan_when_prediction_changes=return_nan_when_prediction_changes,
@@ -62,15 +90,15 @@ def changed_prediction_indices(
     ----------
     return_nan_when_prediction_changes:
         Instance attribute of perturbation metrics.
-    model:
+    model: ModelInterface
+        Model to be used for prediction.
     x_batch:
         Batch of original inputs provided by user.
     x_perturbed:
         Batch of inputs after applying perturbation.
 
     Returns
     -------
-
     changed_idx:
         List of indices in batch, for which predicted label has changed afer.
 

quantus/helpers/plotting.py

@@ -67,6 +67,67 @@ def plot_pixel_flipping_experiment(
     plt.show()
 
 
+def plot_inverse_curves(
+    y_batch: np.ndarray,
+    scores_ori: List[Any],
+    scores_inv: List[Any],
+    single_class: Union[int, None] = None,
+    *args,
+    **kwargs,
+) -> None:
+    """
+    Plot the pixel-flipping experiment as done in paper:
+
+    References:
+        1) Bach, Sebastian, et al. "On pixel-wise explanations for non-linear classifier
+        decisions by layer-wise relevance propagation." PloS one 10.7 (2015): e0130140.
+
+    Parameters
+    ----------
+    y_batch: np.ndarray
+         The list of true labels.
+    scores_ori: list
+        The list of evalution scores.
+    scores_inv: list
+        The list of evalution scores (inverse curve).
+    single_class: integer, optional
+        An integer to specify the label to plot.
+    args: optional
+        Arguments.
+    kwargs: optional
+        Keyword arguments.
+
+    Returns
+    -------
+    None
+    """
+
+    fig = plt.figure(figsize=(8, 6))
+    if single_class is None:
+        for c in np.unique(y_batch):
+            indices = np.where(y_batch == c)
+            plt.plot(
+                np.linspace(0, 1, len(scores_ori[0])),
+                np.mean(np.array(scores_ori)[indices], axis=0),
+                label=f"Original curve: {str(c)} ({indices[0].size} samples)",
+            )
+            plt.plot(
+                np.linspace(0, 1, len(scores_inv[0])),
+                np.mean(np.array(scores_inv)[indices], axis=0),
+                label=f"Inverse curve: {str(c)} ({indices[0].size} samples)",
+            )
+    plt.xlabel("Fraction masked")
+    plt.ylabel("Mean Prediction")
+    plt.gca().set_yticklabels(
+        ["{:.0f}%".format(x * 100) for x in plt.gca().get_yticks()]
+    )
+    plt.gca().set_xticklabels(
+        ["{:.0f}%".format(x * 100) for x in plt.gca().get_xticks()]
+    )
+    plt.legend()
+    plt.show()
+
+
 def plot_selectivity_experiment(results: Dict[str, List[Any]], *args, **kwargs) -> None:
     """
     Plot the selectivity experiment as done in paper: