update docs

Author: holyseven

docs/input_feature_interpreter.rst

@@ -3,10 +3,19 @@
 Input Feature Based Interpreters
 ================================
 
-Smooth Gradients
+Consensus
 ----------------
 
-.. autoclass:: interpretdl.SmoothGradInterpreter
+.. autoclass:: interpretdl.ConsensusInterpreter
+   :members:
+      
+Gradient Shap
+-------------
+
+.. autoclass:: interpretdl.GradShapCVInterpreter
+   :members:
+
+.. autoclass:: interpretdl.GradShapNLPInterpreter
    :members:
 
 Integrated Gradients
@@ -17,22 +26,7 @@ Integrated Gradients
 
 .. autoclass:: interpretdl.IntGradNLPInterpreter
    :members:
-   
-Occlusion
----------
 
-.. autoclass:: interpretdl.OcclusionInterpreter
-   :members:
-      
-Gradient Shap
--------------
-
-.. autoclass:: interpretdl.GradShapCVInterpreter
-   :members:
-
-.. autoclass:: interpretdl.GradShapNLPInterpreter
-   :members:
-   
 LIME
 ----
 
@@ -48,6 +42,30 @@ LIME With Global Prior
 .. autoclass:: interpretdl.LIMEPriorInterpreter
    :members:
 
+LRP
+----------------
+
+.. autoclass:: interpretdl.LRPCVInterpreter
+   :members:
+
+Occlusion
+---------
+
+.. autoclass:: interpretdl.OcclusionInterpreter
+   :members:
+
+Smooth Gradients
+----------------
+
+.. autoclass:: interpretdl.SmoothGradInterpreter
+   :members:
+
+Smooth Gradients V2
+-------------------
+
+.. autoclass:: interpretdl.SmoothGradInterpreterV2
+   :members:
+
 NormLIME
 --------
 
@@ -56,9 +74,3 @@ NormLIME
 
 .. autoclass:: interpretdl.NormLIMENLPInterpreter
   :members:
-
-LRP
-----------------
-
-.. autoclass:: interpretdl.LRPCVInterpreter
-   :members:

interpretdl/interpreter/abc_interpreter.py

@@ -11,23 +11,27 @@
 
 class Interpreter(ABC):
     """
-    Interpreter is the base abstract class for all interpretation algorithms. 
-    Interpreters should (1) prepare the ``self.predict_fn`` that outputs probability predictions, gradients or other 
-    desired intermediate results of the model, and (2) implement the core function ``interpret`` of the interpretation
-    algorithm.
+    Interpreter is the base abstract class for all Interpreters. 
+    The implementation of Interpreters should (1) prepare the ``self.predict_fn`` that outputs probability predictions,
+    gradients or other desired intermediate results of the model, and (2) implement the core function ``interpret`` of
+    the interpretation algorithm.
+    This kind of implementation works for all post-poc interpretation algorithms. While there are other algorithms that
+    may have different features, this kind of implementation can cover most of them. So we follow this design for all 
+    Interpreters in this library.
     
     Three sub-abstract Interpreters that implement ``self.predict_fn`` are currently provided in this file:
     ``InputGradientInterpreter``, ``InputOutputInterpreter``, ``IntermediateLayerInterpreter``. For each of them, the
     implemented ``predict_fn`` can be used by several different algorithms. Therefore, the further implementations can
-    focus on the core algorithm.
-
-    Args:
-        paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
-        device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
-        use_cuda (bool):  Would be deprecated soon. Use ``device`` directly.
+    focus on the core algorithm. More sub-abstract Interpreters will be provided if necessary.
     """
 
     def __init__(self, paddle_model: callable, device: str, use_cuda: bool = None, **kwargs):
+        """
+        
+        Args:
+            paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
+            device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
+        """
         self.device = device
         self.paddle_model = paddle_model
         self.predict_fn = None
@@ -54,13 +58,16 @@ def interpret(self, **kwargs):
         raise NotImplementedError
 
     def _build_predict_fn(self, **kwargs):
-        """Build self.predict_fn for interpreters."""
+        """ Build self.predict_fn for interpreters. This will be called by interpret(). """
         raise NotImplementedError
 
     def _paddle_env_setup(self):
         """Prepare the environment setup. This is not always necessary because the setup can be done within the 
-        function of ``_build_predict_fn``. This function is a simple implementation for disabling gradient computation.
+        function of ``_build_predict_fn``.
         """
+        #######################################################################
+        # This is a simple implementation for disabling gradient computation. #
+        #######################################################################
         import paddle
         if not paddle.is_compiled_with_cuda() and self.device[:3] == 'gpu':
             print("Paddle is not installed with GPU support. Change to CPU version now.")
@@ -79,11 +86,16 @@ class InputGradientInterpreter(Interpreter):
     ``InputGradientInterpreter`` are used by input gradient based Interpreters. Interpreters that are derived from 
     ``InputGradientInterpreter``: ``GradShapCVInterpreter``, ``IntGradCVInterpreter``, ``SmoothGradInterpreter``.
 
-    The ``predict_fn`` provided by this interpreter will output input gradient given an input. 
-
+    The ``predict_fn`` in this interpreter will return input gradient given an input. 
     """
 
     def __init__(self, paddle_model: callable, device: str, use_cuda: bool = None, **kwargs):
+        """
+        
+        Args:
+            paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
+            device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
+        """        
         Interpreter.__init__(self, paddle_model, device, use_cuda, **kwargs)
         assert hasattr(paddle_model, 'forward'), \
             "paddle_model has to be " \
@@ -197,6 +209,12 @@ class InputOutputInterpreter(Interpreter):
     """
 
     def __init__(self, paddle_model: callable, device: str, use_cuda: bool = None, **kwargs):
+        """
+        
+        Args:
+            paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
+            device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
+        """        
         Interpreter.__init__(self, paddle_model, device, use_cuda, **kwargs)
         assert hasattr(paddle_model, 'forward'), \
             "paddle_model has to be " \
@@ -259,11 +277,17 @@ class IntermediateLayerInterpreter(Interpreter):
     Interpreters that are derived from ``IntermediateLayerInterpreter``:
     ``RolloutInterpreter``, ``ScoreCAMInterpreter``.
 
-    The ``predict_fn`` provided by this interpreter will output the model's intermediate outputs given an input. 
-
+    The ``predict_fn`` provided by this interpreter will return the model's intermediate outputs given an input. 
     """
 
     def __init__(self, paddle_model: callable, device: str, use_cuda: bool = None, **kwargs):
+        """
+
+        Args:
+            paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
+            device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
+        """
+        
         Interpreter.__init__(self, paddle_model, device, use_cuda, **kwargs)
         assert hasattr(paddle_model, 'forward'), \
             "paddle_model has to be " \
@@ -272,16 +296,15 @@ def __init__(self, paddle_model: callable, device: str, use_cuda: bool = None, *
     def _build_predict_fn(self, rebuild: bool = False, target_layer: str = None, target_layer_pattern: str = None):
         """Build self.predict_fn for IntermediateLayer based algorithms.
         The model is supposed to be a classification model.
-        target_layer and target_layer_pattern cannot be set at the same time.
+        ``target_layer`` and ``target_layer_pattern`` cannot be set at the same time. See the arguments below.
 
         Args:
             rebuild (bool, optional): forces to rebuild. Defaults to False.
-            target_layer (str, optional): the name of the desired layer whose features will output. 
-                This is used when there is only one layer to output. Conflict with ``target_layer_pattern``.
-                Defaults to None.
-            target_layer_pattern (str, optional): the pattern name of the layers whose features will output. 
-                This is used when there are several layers to output and they share a common pattern name. 
-                Conflict with ``target_layer``. Defaults to None.
+            target_layer (str, optional): the name of the desired layer whose features will output. This is used when
+                there is only one layer to output. Conflict with ``target_layer_pattern``. Defaults to None.
+            target_layer_pattern (str, optional): the pattern name of the layers whose features will output. This is 
+                used when there are several layers to output and they share a common pattern name. Conflict with 
+                ``target_layer``. Defaults to None.
         """
 
         if self.predict_fn is not None:

interpretdl/interpreter/consensus.py

@@ -5,19 +5,17 @@
 class ConsensusInterpreter(object):
     """
     
-    ConsensusInterpreter averages the explanations of a given Interpreter over a list of models.
-    The averaged result is more like an explanation for the data, instead of specific models.
-    For visual object recognition tasks, the Consensus explanation would be more aligned with the object than
-    individual models.
+    ConsensusInterpreter averages the explanations of a given Interpreter over a list of models. The averaged result 
+    is more like an explanation for the data, instead of specific models. For visual object recognition tasks, the 
+    Consensus explanation would be more aligned with the object than individual models.
 
     More details regarding the Consensus method can be found in the original paper:
     https://arxiv.org/abs/2109.00707.
-
     """
 
     def __init__(self, InterpreterClass, list_of_models: list, device: str = 'gpu:0', use_cuda=None, **kwargs):
         """
-
+        
         Args:
             InterpreterClass ([type]): The given Interpreter defined in InterpretDL.
             list_of_models (list): a list of trained models. Can be found from paddle.vision.models, or 
@@ -35,13 +33,14 @@ def __init__(self, InterpreterClass, list_of_models: list, device: str = 'gpu:0'
     def interpret(self, inputs: str or list(str) or np.ndarray, **kwargs) -> np.ndarray:
         """
         The technical details are simple to understand for the Consensus method:
-        Given the ``inputs`` and the interpretation algorithm (one of Interpreters), each model in ``list_of_models`` 
-        will produce an explanation, then Consensus will concatenate all the explanations. Subsequent normalization 
-        and average can be done as users' preference. The suggested operation for input gradient based algorithms is 
-        average of the absolute values.
+        Given the ``inputs`` and the interpretation algorithm (one of the Interpreters), each model in 
+        ``list_of_models`` will produce an explanation, then Consensus will concatenate all the explanations. 
+        Subsequent normalization and average can be done as users' preference. The suggested operation for input
+        gradient based algorithms is average of the absolute values.
 
         We leave the visualization to users. 
-        See https://github.com/PaddlePaddle/InterpretDL/tree/master/tutorials/consensus_tutorial_cv.ipynb for an example.
+        See https://github.com/PaddlePaddle/InterpretDL/tree/master/tutorials/consensus_tutorial_cv.ipynb for an 
+        example.
 
         .. code-block:: python
 
@@ -74,7 +73,8 @@ def interpret(self, inputs: str or list(str) or np.ndarray, **kwargs) -> np.ndar
             ax[-1].set_title('Consensus')
 
         Args:
-            inputs (str or list of strs or numpy.ndarray): The input image filepath or a list of filepaths or numpy array of read images.
+            inputs (str or list of strs or numpy.ndarray): The input image filepath or a list of filepaths or numpy 
+                array of read images.
 
         Returns:
             np.ndarray: Concatenated raw explanations.

interpretdl/interpreter/forgetting_events.py

@@ -21,14 +21,13 @@ class ForgettingEventsInterpreter(Interpreter):
     https://arxiv.org/abs/1812.05159.
     """
 
-    def __init__(self, paddle_model: callable, device: str, use_cuda=None):
-        """Initialize the ForgettingEventsInterpreter.
-
-        Args:
-            paddle_model (callable): A user-defined function that gives access to model predictions. 
-                It takes in data inputs and output predictions.
-            device (str): Whether or not to use cuda. Default: None.
+    def __init__(self, paddle_model: callable, device: str = 'gpu:0', use_cuda=None):
         """
+        
+        Args:
+            paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
+            device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
+        """        
         Interpreter.__init__(self, paddle_model, device, use_cuda)
 
     def interpret(self,

interpretdl/interpreter/gradient_cam.py

@@ -11,7 +11,7 @@ class GradCAMInterpreter(Interpreter):
 
     Given a convolutional network and an image classification task, classification activation map (CAM) can be derived
     from the global average pooling and the last fully-connected layer, and show the important regions that affect
-    model decisions.
+    model's decisions.
 
     GradCAM further looks at the gradients flowing into one of the convolutional layers to give weight to activation 
     maps. Note that if there is a global average pooling layer in the network, GradCAM targeting the last layer is 
@@ -25,11 +25,11 @@ class GradCAMInterpreter(Interpreter):
 
     def __init__(self, paddle_model: callable, device: str = 'gpu:0', use_cuda=None):
         """
-
+        
         Args:
             paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
             device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
-        """
+        """        
         Interpreter.__init__(self, paddle_model, device, use_cuda)
         self.paddle_prepared = False
 
@@ -47,9 +47,9 @@ def interpret(self,
                   save_path: str = None) -> np.ndarray:
         """
         The technical details of the GradCAM method are described as follows:
-        GradCAM computes the feature map and the gradient of the objective function w.r.t. ``target_layer_name``.
-        With the average of gradients along the spatial dimensions, gradients will be multiplied with feature map,
-        following by a ReLU activation to produce the final explanation.
+        GradCAM computes the feature map at the layer of ``target_layer_name`` and the gradient of the objective 
+        function w.r.t. ``target_layer_name``. With the average of gradients along the spatial dimensions, gradients
+        will be multiplied with feature map, following by a ReLU activation to produce the final explanation.
 
         Args:
             inputs (str or list of strs or numpy.ndarray): The input image filepath or a list of filepaths or numpy 

interpretdl/interpreter/gradient_shap.py

@@ -16,12 +16,12 @@ class GradShapCVInterpreter(InputGradientInterpreter):
     GradShap uses noised inputs to get input gradients and then average.
 
     More details regarding the GradShap method can be found in the original paper:
-    http://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions
+    http://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions.
     """
 
     def __init__(self, paddle_model: callable, device: str = 'gpu:0', use_cuda=None):
         """
-
+        
         Args:
             paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
             device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
@@ -128,16 +128,16 @@ class GradShapNLPInterpreter(Interpreter):
     are done for the embeddings.
 
     More details regarding the GradShap method can be found in the original paper:
-    http://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions
+    http://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions.
     """
 
     def __init__(self, paddle_model: callable, device: str = 'gpu:0', use_cuda: bool = None) -> None:
         """
-
+        
         Args:
             paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
             device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
-        """
+        """        
         Interpreter.__init__(self, paddle_model, device, use_cuda)
 
     def interpret(self,

interpretdl/interpreter/integrated_gradients.py

@@ -22,11 +22,11 @@ class IntGradCVInterpreter(InputGradientInterpreter):
 
     def __init__(self, paddle_model: callable, device: str = 'gpu:0', use_cuda: bool = None):
         """
-
+        
         Args:
             paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
             device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
-        """
+        """        
         InputGradientInterpreter.__init__(self, paddle_model, device, use_cuda)
 
     def interpret(self,
@@ -138,16 +138,16 @@ class IntGradNLPInterpreter(Interpreter):
     are done for the embeddings.
 
     More details regarding the Integrated Gradients method can be found in the original paper:
-    https://arxiv.org/abs/1703.01365
+    https://arxiv.org/abs/1703.01365.
     """
 
     def __init__(self, paddle_model: callable, device: str = 'gpu:0', use_cuda: bool = None) -> None:
         """
-
+        
         Args:
             paddle_model (callable): A model with ``forward`` and possibly ``backward`` functions.
             device (str): The device used for running `paddle_model`, options: ``cpu``, ``gpu:0``, ``gpu:1`` etc.
-        """
+        """        
         Interpreter.__init__(self, paddle_model, device, use_cuda)
 
     def interpret(self,