3 -> 2 arguments

Author: GalyaZalesskaya

docs/source/user-guide.md

@@ -137,7 +137,7 @@ explanation = explainer(
 )
 
 # Save saliency maps
-explanation.save("output_path", "name")
+explanation.save("output_path", "name_")
 ```
 
 ### Specifying `preprocess_fn`
@@ -184,7 +184,7 @@ explanation = explainer(
 )
 
 # Save saliency maps
-explanation.save("output_path", "name")
+explanation.save("output_path", "name_")
 ```
 
 
@@ -242,7 +242,7 @@ explanation = explainer(
 )
 
 # Save saliency maps
-explanation.save("output_path", "name")
+explanation.save("output_path", "name_")
 ```
 
 
@@ -298,7 +298,7 @@ explanation = explainer(
 )
 
 # Save saliency maps
-explanation.save("output_path", "name")
+explanation.save("output_path", "name_")
 
 ```
 
@@ -333,16 +333,16 @@ model_xai = xai.insert_xai(
 
 ## Saving saliency maps
 
-You can easily save saliency maps with flexible naming options, including image name as prefix, so saliency maps from the same image will start the same, target prefix, terget suffix.
+You can easily save saliency maps with flexible naming options by using a `prefix` and `postfix`. The `prefix` allows saliency maps from the same image to have consistent naming.
 
-For the name `image_name_target_aeroplane.jpg`:
-- image_name_prefix = `image_name`,
-- target_prefix = `target`,
-- label name = `aeroplane`,
-- target_suffix = ``.
+The format for naming is:
+
+`{prefix} + target_id + {postfix}.jpg`
 
 Additionally, you can include the confidence score for each class in the saved saliency map's name.
 
+`{prefix} + target_id + {postfix} + confidence.jpg`
+
 ```python
 import cv2
 import numpy as np
@@ -352,13 +352,20 @@ import openvino_xai as xai
 
 def preprocess_fn(image: np.ndarray) -> np.ndarray:
     """Preprocess the input image."""
-    resized_image = cv2.resize(src=image, dsize=(224, 224))
-    expanded_image = np.expand_dims(resized_image, 0)
-    return expanded_image
+    x = cv2.resize(src=image, dsize=(224, 224))
+    x = x.transpose((2, 0, 1))
+    processed_image = np.expand_dims(x, 0)
+    return processed_image
 
 def postprocess_fn(output: Mapping):
     """Postprocess the model output."""
-    return output["logits"]
+    output = softmax(output)
+    return output[0]
+
+def softmax(x: np.ndarray) -> np.ndarray:
+    """Compute softmax values of x."""
+    e_x = np.exp(x - np.max(x))
+    return e_x / e_x.sum()
 
 # Generate and process saliency maps (as many as required, sequentially)
 image = cv2.imread("path/to/image.jpg")
@@ -367,17 +374,7 @@ image = cv2.imread("path/to/image.jpg")
 MODEL_PATH = "path/to/model.xml"
 model = ov.Core().read_model(MODEL_PATH)  # type: ov.Model
 
-# Get predicted confidences for the image
-compiled_model = core.compile_model(model=model, device_name="AUTO")
-logits = compiled_model([preprocess_fn(image)])[0]
-postprocessed_logits = postprocess_fn(logits)[0]
-result_index = np.argmax(postprocessed_logits)
-result_scores = postprocessed_logits[result_index]
-
-# Generate dict {class_index: confidence} to save saliency maps
-scores_dict = {i: score for i, score in enumerate(result_scores)}
-
-# The Explainer object will prepare and load the model once in the beginning
+# Initialize Explainer
 explainer = xai.Explainer(
     model,
     task=xai.Task.CLASSIFICATION,
@@ -389,30 +386,40 @@ voc_labels = [
     'dog', 'horse', 'motorbike', 'person', 'pottedplant', 'sheep', 'sofa', 'train', 'tvmonitor'
 ]
 
+# Get predicted confidences for the image
+compiled_model = core.compile_model(model=model, device_name="AUTO")
+logits = compiled_model(preprocess_fn(image))[0]
+result_infer = postprocess_fn(logits)
+
+# Generate list of predicted class indices and scores
+result_idxs = np.argwhere(result_infer > 0.4).flatten()
+result_scores = result_infer[result_idxs]
+
+# Generate dict {class_index: confidence} to save saliency maps
+scores_dict = {i: score for i, score in zip(result_idxs, result_scores)}
+
 # Run explanation
 explanation = explainer(
     image,
-    explain_mode=ExplainMode.WHITEBOX,
+    explain_mode=xai.ExplainMode.WHITEBOX,
     label_names=voc_labels,
-    target_explain_labels=1,  # target classes to explain
+    target_explain_labels=result_idxs,  # target classes to explain
 )
 
 # Save saliency maps flexibly
 OUTPUT_PATH = "output_path"
-explanation.save(OUTPUT_PATH)  # target_aeroplane.jpg
-explanation.save(OUTPUT_PATH, "image_name")  # image_name_target_aeroplane.jpg
-explanation.save(OUTPUT_PATH, image_name_prefix="image_name")  # image_name_target_aeroplane.jpg
-
-# Avoid "target" in salinecy map names
-explanation.save(OUTPUT_PATH, target_prefix="")  # aeroplane.jpg
-explanation.save(OUTPUT_PATH, target_prefix="", target_suffix="class")  # aeroplane_class.jpg
-explanation.save(OUTPUT_PATH, image_name_prefix="image_name", target_prefix="")  # image_name_aeroplane.jpg
+explanation.save(OUTPUT_PATH)  # aeroplane.jpg
+explanation.save(OUTPUT_PATH, "image_name_target_")  # image_name_target_aeroplane.jpg
+explanation.save(OUTPUT_PATH, prefix="image_name_target_")  # image_name_target_aeroplane.jpg
+explanation.save(OUTPUT_PATH, postfix="_class_map")  # aeroplane_class_map.jpg
+explanation.save(OUTPUT_PATH, prefix="image_name_", postfix="_class_map")  # image_name_aeroplane_class_map.jpg
 
 # Save saliency maps with confidence scores
-explanation.save(OUTPUT_PATH, target_suffix="conf", confidence_scores=scores_dict)  # target_aeroplane_conf_0.92.jpg```
+explanation.save(
+    OUTPUT_PATH, prefix="image_name_", postfix="_conf_", confidence_scores=scores_dict
+)  # image_name_aeroplane_conf_0.85.jpg
 ```
 
-
 ## Example scripts
 
 More usage scenarios that can be used with your own models and images as arguments are available in [examples](../../examples).

openvino_xai/explainer/explanation.py

@@ -135,63 +135,55 @@ def _select_target_indices(
     def save(
         self,
         dir_path: Path | str,
-        image_name_prefix: str | None = "",
-        target_prefix: str | None = "target",
-        target_suffix: str | None = "",
+        prefix: str = "",
+        postfix: str = "",
         confidence_scores: Dict[int, float] | None = None,
     ) -> None:
         """
         Dumps saliency map images to the specified directory.
 
-        Allows flexibly name the files with the image_name_prefix, target_prefix, and target_suffix.
-        For the name 'image_name_target_aeroplane.jpg': prefix = 'image_name',
-        target_prefix = 'target', label name = 'aeroplane', target_suffix = ''.
+        Allows flexibly name the files with the prefix and postfix.
+        {prefix} + target_id + {postfix}.jpg
 
-        save(output_dir) -> target_aeroplane.jpg
-        save(output_dir, image_name_prefix="test_map", target_prefix="") -> test_map_aeroplane.jpg
-        save(output_dir, image_name_prefix="test_map") -> test_map_target_aeroplane.jpg
-        save(output_dir, target_suffix="conf", confidence_scores=scores) -> target_aeroplane_conf_0.92.jpg
+        Also allows to add confidence scores to the file names.
+        {prefix} + target_id + {postfix} + confidence.jpg
+
+        save(output_dir) -> aeroplane.jpg
+        save(output_dir, prefix="image_name_target_") -> image_name_target_aeroplane.jpg
+        save(output_dir, postfix="_class_map") -> aeroplane_class_map.jpg
+        save(
+            output_dir, prefix="image_name_", postfix="_conf_", confidence_scores=scores
+        ) -> image_name_aeroplane_conf_0.85.jpg
 
         Parameters:
-        :param dir_path: The directory path where the saliency maps will be saved.
-        :type dir_path: Path | str
-        :param image_name_prefix: Optional prefix for the file names. Default is an empty string.
-        :type image_name_prefix: str | None
-        :param target_prefix: Optional suffix for the target. Default is "target".
-        :type target_prefix: str | None
-        :param target_suffix: Optional suffix for the saliency map name. Default is an empty string.
-        :type target_suffix: str | None
-        :param confidence_scores: Dict with confidence scores for each class to saliency maps with them1 Default is None.
-        :type confidence_scores: Dict[int, float] | None
+            :param dir_path: The directory path where the saliency maps will be saved.
+            :type dir_path: Path | str
+            :param prefix: Optional prefix for the saliency map names. Default is an empty string.
+            :type prefix: str
+            :param postfix: Optional postfix for the saliency map names. Default is an empty string.
+            :type postfix: str
+            :param confidence_scores: Dict with confidence scores for each class index. Default is None.
+            :type confidence_scores: Dict[int, float] | None
 
         """
 
         os.makedirs(dir_path, exist_ok=True)
 
-        image_name_prefix = f"{image_name_prefix}_" if image_name_prefix != "" else image_name_prefix
-        target_suffix = f"_{target_suffix}" if target_suffix != "" else target_suffix
-        template = f"{{image_name_prefix}}{{target_prefix}}{{target_name}}{target_suffix}.jpg"
-
-        target_prefix = f"{target_prefix}_" if target_prefix != "" else target_prefix
-        for cls_idx, map_to_save in self._saliency_map.items():
+        template = f"{prefix}{{target_name}}{postfix}{{conf_score}}.jpg"
+        for target_idx, map_to_save in self._saliency_map.items():
+            conf_score = ""
             map_to_save = cv2.cvtColor(map_to_save, code=cv2.COLOR_RGB2BGR)
-            if isinstance(cls_idx, str):
-                target_name = ""
-                if target_prefix == "target_":
-                    # Default activation map suffix
-                    target_prefix = "activation_map"
-                elif target_prefix == "":
-                    # Remove the underscore in case of empty suffix
-                    image_name_prefix = image_name_prefix[:-1] if image_name_prefix.endswith("_") else image_name_prefix
+            if isinstance(target_idx, str):
+                target_name = "activation_map"
+            elif self.label_names and isinstance(target_idx, np.int64):
+                target_name = self.label_names[target_idx]
             else:
-                target_name = self.label_names[cls_idx] if self.label_names else str(cls_idx)
-                if confidence_scores:
-                    class_confidence = confidence_scores[cls_idx]
-                    target_name = f"{target_name}_{class_confidence:.2f}"
+                target_name = str(target_idx)
 
-            image_name = template.format(
-                image_name_prefix=image_name_prefix, target_prefix=target_prefix, target_name=target_name
-            )
+            if confidence_scores and target_idx in confidence_scores:
+                conf_score = f"{confidence_scores[int(target_idx)]:.2f}"
+
+            image_name = template.format(target_name=target_name, conf_score=conf_score)
             cv2.imwrite(os.path.join(dir_path, image_name), img=map_to_save)
 
 

tests/unit/explanation/test_explanation.py

@@ -41,37 +41,37 @@ def test_save(self, tmp_path):
         save_path = tmp_path / "saliency_maps"
 
         explanation = self._get_explanation()
-        explanation.save(save_path, image_name_prefix="test_map")
-        assert os.path.isfile(save_path / "test_map_target_aeroplane.jpg")
-        assert os.path.isfile(save_path / "test_map_target_bird.jpg")
+        explanation.save(save_path, prefix="image_name_")
+        assert os.path.isfile(save_path / "image_name_aeroplane.jpg")
+        assert os.path.isfile(save_path / "image_name_bird.jpg")
 
         explanation = self._get_explanation()
         explanation.save(save_path)
-        assert os.path.isfile(save_path / "target_aeroplane.jpg")
-        assert os.path.isfile(save_path / "target_bird.jpg")
+        assert os.path.isfile(save_path / "aeroplane.jpg")
+        assert os.path.isfile(save_path / "bird.jpg")
 
         explanation = self._get_explanation(label_names=None)
-        explanation.save(save_path, "test_map")
-        assert os.path.isfile(save_path / "test_map_target_0.jpg")
-        assert os.path.isfile(save_path / "test_map_target_2.jpg")
+        explanation.save(save_path, postfix="_class_map")
+        assert os.path.isfile(save_path / "0_class_map.jpg")
+        assert os.path.isfile(save_path / "2_class_map.jpg")
 
         explanation = self._get_explanation()
-        explanation.save(save_path, target_prefix="", target_suffix="map")
-        assert os.path.isfile(save_path / "aeroplane_map.jpg")
-        assert os.path.isfile(save_path / "bird_map.jpg")
+        explanation.save(save_path, prefix="image_name_", postfix="_map")
+        assert os.path.isfile(save_path / "image_name_aeroplane_map.jpg")
+        assert os.path.isfile(save_path / "image_name_bird_map.jpg")
 
         explanation = self._get_explanation()
-        explanation.save(save_path, target_suffix="conf", confidence_scores={0: 0.92, 2: 0.85})
-        assert os.path.isfile(save_path / "target_aeroplane_0.92_conf.jpg")
-        assert os.path.isfile(save_path / "target_bird_0.85_conf.jpg")
+        explanation.save(save_path, postfix="_conf_", confidence_scores={0: 0.92, 2: 0.85})
+        assert os.path.isfile(save_path / "aeroplane_conf_0.92.jpg")
+        assert os.path.isfile(save_path / "bird_conf_0.85.jpg")
 
         explanation = self._get_explanation(saliency_maps=SALIENCY_MAPS_IMAGE, label_names=None)
-        explanation.save(save_path, image_name_prefix="test_map")
+        explanation.save(save_path, prefix="test_map_")
         assert os.path.isfile(save_path / "test_map_activation_map.jpg")
 
         explanation = self._get_explanation(saliency_maps=SALIENCY_MAPS_IMAGE, label_names=None)
-        explanation.save(save_path, image_name_prefix="test_map", target_prefix="")
-        assert os.path.isfile(save_path / "test_map.jpg")
+        explanation.save(save_path, prefix="test_map_", postfix="_result")
+        assert os.path.isfile(save_path / "test_map_activation_map_result.jpg")
 
     def _get_explanation(self, saliency_maps=SALIENCY_MAPS, label_names=VOC_NAMES):
         explain_targets = [0, 2]