Refactor names/folders/objects for better verbosity

.gitignore

@@ -36,6 +36,7 @@ otx_models/
 
 *.jpg
 *.jpeg
+*.JPEG
 *.png
 
 html_build/

CHANGELOG.md

@@ -11,6 +11,7 @@
 
 ### What's Changed
 
+* Refactor names/folders/objects for better verbosity by @GalyaZalesskaya in https://github.com/openvinotoolkit/openvino_xai/pull/5
 * Support classification task by @negvet in https://github.com/intel-sandbox/openvino_xai/commit/dd5fd9b73fe8c12e2d741792043372bcd900a850
 * Support detection task by @negvet in https://github.com/intel-sandbox/openvino_xai/commit/84f285f2f40a8b1fc50a8cd49798aae37afd58dc
 * Support Model API as inference engine by @negvet in https://github.com/intel-sandbox/openvino_xai/commit/5f575f122dedc0461975bd58f81e730a901a69a6

README.md

@@ -46,9 +46,9 @@ To explain [OpenVINO™](https://github.com/openvinotoolkit/openvino) Intermedia
 preprocessing function (and sometimes postprocessing).
 
 ```python
-explainer = Explainer(
+explainer = xai.Explainer(
     model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     preprocess_fn=preprocess_fn,
 )
 explanation = explainer(data, explanation_parameters)
@@ -66,9 +66,8 @@ import cv2
 import numpy as np
 import openvino.runtime as ov
 
-from openvino_xai.common.parameters import TaskType
-from openvino_xai.explanation.explainer import Explainer
-from openvino_xai.explanation.explanation_parameters import ExplanationParameters
+import openvino_xai as xai
+from openvino_xai.explainer.explanation_parameters import ExplanationParameters
 
 
 def preprocess_fn(x: np.ndarray) -> np.ndarray:
@@ -82,9 +81,9 @@ def preprocess_fn(x: np.ndarray) -> np.ndarray:
 model = ov.Core().read_model("path/to/model.xml")  # type: ov.Model
 
 # Explainer object will prepare and load the model once in the beginning
-explainer = Explainer(
+explainer = xai.Explainer(
     model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     preprocess_fn=preprocess_fn,
 )
 
@@ -95,7 +94,7 @@ explanation_parameters = ExplanationParameters(
 )
 explanation = explainer(image, explanation_parameters)
 
-explanation: ExplanationResult
+explanation: Explanation
 explanation.saliency_map: Dict[int: np.ndarray]  # key - class id, value - processed saliency map e.g. 354x500x3
 
 # Saving saliency maps

docs/Usage.md

@@ -21,9 +21,11 @@ Content:
 ## Explainer - interface to XAI algorithms
 
 ```python
-explainer = Explainer(
+import openvino_xai as xai
+
+explainer = xai.Explainer(
     model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     preprocess_fn=preprocess_fn,
 )
 explanation = explainer(data, explanation_parameters)
@@ -43,9 +45,8 @@ import cv2
 import numpy as np
 import openvino.runtime as ov
 
-from openvino_xai.common.parameters import TaskType
-from openvino_xai.explanation.explainer import Explainer
-from openvino_xai.explanation.explanation_parameters import ExplanationParameters
+import openvino_xai as xai
+from openvino_xai.explainer.explanation_parameters import ExplanationParameters
 
 
 def preprocess_fn(x: np.ndarray) -> np.ndarray:
@@ -59,9 +60,9 @@ def preprocess_fn(x: np.ndarray) -> np.ndarray:
 model = ov.Core().read_model("path/to/model.xml")  # type: ov.Model
 
 # Explainer object will prepare and load the model once in the beginning
-explainer = Explainer(
+explainer = xai.Explainer(
     model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     preprocess_fn=preprocess_fn,
 )
 
@@ -90,11 +91,9 @@ import cv2
 import numpy as np
 import openvino.runtime as ov
 
-from openvino_xai.common.parameters import TaskType, XAIMethodType
-from openvino_xai.explanation.explainer import Explainer
-from openvino_xai.explanation.explanation_parameters import ExplainMode, ExplanationParameters, TargetExplainGroup,
-    PostProcessParameters
-from openvino_xai.insertion.insertion_parameters import ClassificationInsertionParameters
+import openvino_xai as xai
+from openvino_xai.explainer.parameters import ExplainMode, ExplanationParameters, TargetExplainGroup, VisualizationParameters
+from openvino_xai.inserter.parameters import ClassificationInsertionParameters
 
 
 def preprocess_fn(x: np.ndarray) -> np.ndarray:
@@ -111,13 +110,13 @@ model = ov.Core().read_model("path/to/model.xml")  # type: ov.Model
 insertion_parameters = ClassificationInsertionParameters(
     # target_layer="last_conv_node_name",  # target_layer - node after which XAI branch will be inserted
     embed_normalization=True,  # True by default.  If set to True, saliency map normalization is embedded in the model
-    explain_method_type=XAIMethodType.RECIPROCAM,  # ReciproCAM is the default XAI method for CNNs
+    explain_method=xai.Method.RECIPROCAM,  # ReciproCAM is the default XAI method for CNNs
 )
 
 # Explainer object will prepare and load the model once in the beginning
-explainer = Explainer(
+explainer = xai.Explainer(
     model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     preprocess_fn=preprocess_fn,
     explain_mode=ExplainMode.WHITEBOX,
     insertion_parameters=insertion_parameters,
@@ -131,7 +130,7 @@ explanation_parameters = ExplanationParameters(
     target_explain_group=TargetExplainGroup.CUSTOM,
     target_explain_labels=[11, 14],  # target classes to explain, also ['dog', 'person'] is a valid input
     label_names=voc_labels,
-    post_processing_parameters=PostProcessParameters(overlay=True),  # by default, saliency map overlay over image
+    visualization_parameters=VisualizationParameters(overlay=True),  # by default, saliency map overlay over image
 )
 explanation = explainer(image, explanation_parameters)
 
@@ -154,9 +153,8 @@ import cv2
 import numpy as np
 import openvino.runtime as ov
 
-from openvino_xai.common.parameters import TaskType
-from openvino_xai.explanation.explainer import Explainer
-from openvino_xai.explanation.explanation_parameters import ExplainMode, ExplanationParameters
+import openvino_xai as xai
+from openvino_xai.explainer.explanation_parameters import ExplainMode, ExplanationParameters
 
 
 def preprocess_fn(x: np.ndarray) -> np.ndarray:
@@ -176,9 +174,9 @@ def postprocess_fn(x: ov.utils.data_helpers.wrappers.OVDict):
 model = ov.Core().read_model("path/to/model.xml")  # type: ov.Model
 
 # Explainer object will prepare and load the model once in the beginning
-explainer = Explainer(
+explainer = xai.Explainer(
     model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     preprocess_fn=preprocess_fn,
     postprocess_fn=postprocess_fn,
     explain_mode=ExplainMode.BLACKBOX,
@@ -212,9 +210,9 @@ Note: original model outputs are not affected and the model should be inferable
 
 ```python
 import openvino.runtime as ov
-import openvino_xai as ovxai
-from openvino_xai.common.parameters import TaskType, XAIMethodType
-from openvino_xai.insertion.insertion_parameters import ClassificationInsertionParameters
+
+import openvino_xai as xai
+from openvino_xai.inserter.parameters import ClassificationInsertionParameters
 
 
 # Creating model
@@ -224,13 +222,13 @@ model = ov.Core().read_model("path/to/model.xml")  # type: ov.Model
 insertion_parameters = ClassificationInsertionParameters(
     # target_layer="last_conv_node_name",  # target_layer - node after which XAI branch will be inserted
     embed_normalization=True,  # True by default.  If set to True, saliency map normalization is embedded in the model
-    explain_method_type=XAIMethodType.RECIPROCAM,  # ReciproCAM is the default XAI method for CNNs
+    explain_method=xai.Method.RECIPROCAM,  # ReciproCAM is the default XAI method for CNNs
 )
 
 # Inserting XAI branch into the model graph
-model_xai = ovxai.insert_xai(
+model_xai = xai.insert_xai(
     model=model,
-    task_type=TaskType.CLASSIFICATION,
+    task=xai.Task.CLASSIFICATION,
     insertion_parameters=insertion_parameters,
 )  # type: ov.Model
 

docs/api/source/api.rst

@@ -22,9 +22,9 @@ To explain the model (getting saliency maps), use openvino_xai.explanation
 Algorithms
 ----------
 
-To access/modify implemented XAI methods, use openvino_xai.algorithms
+To access/modify implemented XAI methods, use openvino_xai.methods
 
-.. automodule:: openvino_xai.algorithms
+.. automodule:: openvino_xai.methods
     :members:
 
 Insertion

examples/run_classification.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2023 Intel Corporation
+# Copyright (C) 2023-2024 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
 import argparse
@@ -10,18 +10,14 @@
 import numpy as np
 import openvino.runtime as ov
 
-import openvino_xai as ovxai
-from openvino_xai.common.parameters import TaskType, XAIMethodType
+import openvino_xai as xai
 from openvino_xai.common.utils import logger
-from openvino_xai.explanation.explain import Explainer
-from openvino_xai.explanation.explanation_parameters import (
+from openvino_xai.explainer.parameters import (
     ExplainMode,
     ExplanationParameters,
     TargetExplainGroup,
 )
-from openvino_xai.insertion.insertion_parameters import (
-    ClassificationInsertionParameters,
-)
+from openvino_xai.inserter.parameters import ClassificationInsertionParameters
 
 
 def get_argument_parser():
@@ -56,9 +52,9 @@ def explain_auto(args):
     model = ov.Core().read_model(args.model_path)
 
     # Create explainer object
-    explainer = Explainer(
+    explainer = xai.Explainer(
         model=model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
         preprocess_fn=preprocess_fn,
     )
 
@@ -74,7 +70,7 @@ def explain_auto(args):
 
     logger.info(
         f"explain_auto: Generated {len(explanation.saliency_map)} classification "
-        f"saliency maps of layout {explanation.layout} with shape {explanation.sal_map_shape}."
+        f"saliency maps of layout {explanation.layout} with shape {explanation.shape}."
     )
 
     # Save saliency maps for visual inspection
@@ -99,13 +95,13 @@ def explain_white_box(args):
         target_layer="/backbone/conv/conv.2/Div",  # OTX mnet_v3
         # target_layer="/backbone/features/final_block/activate/Mul",  # OTX effnet
         embed_normalization=True, # True by default.  If set to True, saliency map normalization is embedded in the model
-        explain_method_type=XAIMethodType.RECIPROCAM,  # ReciproCAM is the default XAI method for CNNs
+        explain_method=xai.Method.RECIPROCAM,  # ReciproCAM is the default XAI method for CNNs
     )
 
     # Create explainer object
-    explainer = Explainer(
+    explainer = xai.Explainer(
         model=model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
         preprocess_fn=preprocess_fn,
         explain_mode=ExplainMode.WHITEBOX,  # defaults to AUTO
         insertion_parameters=insertion_parameters,
@@ -126,7 +122,7 @@ def explain_white_box(args):
 
     logger.info(
         f"explain_white_box: Generated {len(explanation.saliency_map)} classification "
-        f"saliency maps of layout {explanation.layout} with shape {explanation.sal_map_shape}."
+        f"saliency maps of layout {explanation.layout} with shape {explanation.shape}."
     )
 
     # Save saliency maps for visual inspection
@@ -146,9 +142,9 @@ def explain_black_box(args):
     model = ov.Core().read_model(args.model_path)
 
     # Create explainer object
-    explainer = Explainer(
+    explainer = xai.Explainer(
         model=model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
         preprocess_fn=preprocess_fn,
         postprocess_fn=postprocess_fn,
         explain_mode=ExplainMode.BLACKBOX,  # defaults to AUTO
@@ -173,7 +169,7 @@ def explain_black_box(args):
 
     logger.info(
         f"explain_black_box: Generated {len(explanation.saliency_map)} classification "
-        f"saliency maps of layout {explanation.layout} with shape {explanation.sal_map_shape}."
+        f"saliency maps of layout {explanation.layout} with shape {explanation.shape}."
     )
 
     # Save saliency maps for visual inspection
@@ -192,9 +188,9 @@ def explain_white_box_multiple_images(args):
     model = ov.Core().read_model(args.model_path)
 
     # Create explainer object
-    explainer = Explainer(
+    explainer = xai.Explainer(
         model=model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
         preprocess_fn=preprocess_fn,
     )
 
@@ -221,7 +217,7 @@ def explain_white_box_multiple_images(args):
 
     logger.info(
         f"explain_white_box_multiple_images: Generated {len(explanation)} explanations "
-        f"of layout {explanation[0].layout} with shape {explanation[0].sal_map_shape}."
+        f"of layout {explanation[0].layout} with shape {explanation[0].shape}."
     )
 
     # Save saliency maps for visual inspection
@@ -241,13 +237,13 @@ def explain_white_box_vit(args):
     insertion_parameters = ClassificationInsertionParameters(
         # target_layer="/layers.10/ffn/Add",  # OTX deit-tiny
         # target_layer="/blocks/blocks.10/Add_1",  # timm vit_base_patch8_224.augreg_in21k_ft_in1k
-        explain_method_type=XAIMethodType.VITRECIPROCAM,
+        explain_method=xai.Method.VITRECIPROCAM,
     )
 
     # Create explainer object
-    explainer = Explainer(
+    explainer = xai.Explainer(
         model=model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
         preprocess_fn=preprocess_fn,
         explain_mode=ExplainMode.WHITEBOX,  # defaults to AUTO
         insertion_parameters=insertion_parameters,
@@ -265,7 +261,7 @@ def explain_white_box_vit(args):
 
     logger.info(
         f"explain_white_box_vit: Generated {len(explanation.saliency_map)} classification "
-        f"saliency maps of layout {explanation.layout} with shape {explanation.sal_map_shape}."
+        f"saliency maps of layout {explanation.layout} with shape {explanation.shape}."
     )
 
     # Save saliency maps for visual inspection
@@ -284,9 +280,9 @@ def insert_xai(args):
     model = ov.Core().read_model(args.model_path)
 
     # insert XAI branch
-    model_xai = ovxai.insert_xai(
+    model_xai = xai.insert_xai(
         model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
     )
 
     logger.info("insert_xai: XAI branch inserted into IR.")
@@ -311,13 +307,13 @@ def insert_xai_w_params(args):
         target_layer="/backbone/conv/conv.2/Div",  # OTX mnet_v3
         # target_layer="/backbone/features/final_block/activate/Mul",  # OTX effnet
         embed_normalization=True,
-        explain_method_type=XAIMethodType.RECIPROCAM,
+        explain_method=xai.Method.RECIPROCAM,
     )
 
     # insert XAI branch
-    model_xai = ovxai.insert_xai(
+    model_xai = xai.insert_xai(
         model,
-        task_type=TaskType.CLASSIFICATION,
+        task=xai.Task.CLASSIFICATION,
         insertion_parameters=insertion_parameters,
     )