Merge branch 'master' into optim-wip

Author: ProGamerGov

.gitattributes

@@ -1 +1,2 @@
 tutorials/* linguist-documentation
+*.pt binary

CONTRIBUTING.md

@@ -1,6 +1,23 @@
 # Contributing to Captum
 
-We want to make contributing to Captum as easy and transparent as possible.
+Thank you for your interest in contributing to Captum! We want to make contributing to Captum as easy and transparent as possible.
+Before you begin writing code, it is important that you share your intention to contribute with the team, based on the type of contribution:
+
+
+1. You want to propose and implement a new algorithm, add a new feature or fix a bug. This can be both code and documentation proposals.
+    1. For all non-outstanding features, bug-fixes and algorithms in the Captum issue list (https://github.com/pytorch/captum/issues) please create an issue first.
+    2. If the implementation requires API or any other major code changes (new files, packages or algorithms), we will likely request a design document to review and discuss the design and implementation before making changes. An example design document for LIME can be found here (https://github.com/pytorch/captum/issues/467).
+    3. Once we agree that the plan looks good or confirmed that the change is small enough to not require a detailed design discussion, go ahead and implement it!
+
+2. You want to implement a feature or bug-fix for an outstanding issue.
+
+    1. Search for your issue in the Captum issue list (https://github.com/pytorch/captum/issues).
+    2. Pick an issue and comment that you'd like to work on the feature or bug-fix.
+    3. If you need more context on a particular issue, please ask and we’ll be happy to help.
+
+Once you implement and test your feature or bug-fix, please submit a Pull Request to https://github.com/pytorch/captum (https://github.com/pytorch/pytorch).
+
+This document covers some of the techical aspects of contributing to Captum. More details on what we are looking for in the contributions can be found in the [Contributing Guidelines](https://captum.ai/docs/contribution_guide).
 
 
 ## Development installation
@@ -29,7 +46,7 @@ from the repository root. No additional configuration should be needed (see the
 [black documentation](https://black.readthedocs.io/en/stable/installation_and_usage.html#usage)
 for advanced usage).
 
-Captum also uses [isort](https://github.com/timothycrosley/isort) to sort imports 
+Captum also uses [isort](https://github.com/timothycrosley/isort) to sort imports
 alphabetically and separate into sections. isort is installed easily via
 pip using `pip install isort`, and run locally by calling
 ```bash
@@ -45,18 +62,18 @@ CircleCI will fail on your PR if it does not adhere to the black or flake8 forma
 
 Captum is fully typed using python 3.6+
 [type hints](https://www.python.org/dev/peps/pep-0484/).
-We expect any contributions to also use proper type annotations, and we enforce 
-consistency of these in our continuous integration tests. 
+We expect any contributions to also use proper type annotations, and we enforce
+consistency of these in our continuous integration tests.
 
-To type check your code locally, install [mypy](https://github.com/python/mypy), 
+To type check your code locally, install [mypy](https://github.com/python/mypy),
 which can be done with pip using `pip install "mypy>=0.760"`
 Then run this script from the repository root:
 ```bash
 ./scripts/run_mypy.sh
 ```
-Note that we expect mypy to have version 0.760 or higher, and when type checking, use PyTorch 1.4 or 
-higher due to fixes to PyTorch type hints available in 1.4. We also use the Literal feature which is 
-available only in Python 3.8 or above. If type-checking using a previous version of Python, you will 
+Note that we expect mypy to have version 0.760 or higher, and when type checking, use PyTorch 1.4 or
+higher due to fixes to PyTorch type hints available in 1.4. We also use the Literal feature which is
+available only in Python 3.8 or above. If type-checking using a previous version of Python, you will
 need to install the typing-extension package which can be done with pip using `pip install typing-extensions`.
 
 #### Unit Tests

README.md

@@ -175,12 +175,12 @@ Convergence Delta: tensor([2.3842e-07, -4.7684e-07])
 The algorithm outputs an attribution score for each input element and a
 convergence delta. The lower the absolute value of the convergence delta the better
 is the approximation. If we choose not to return delta,
-we can simply not provide `return_convergence_delta` input
+we can simply not provide the `return_convergence_delta` input
 argument. The absolute value of the returned deltas can be interpreted as an
 approximation error for each input sample.
 It can also serve as a proxy of how accurate the integral approximation for given
 inputs and baselines is.
-If the approximation error is large, we can try larger number of integral
+If the approximation error is large, we can try a larger number of integral
 approximation steps by setting `n_steps` to a larger value. Not all algorithms
 return approximation error. Those which do, though, compute it based on the
 completeness property of the algorithms.
@@ -224,7 +224,7 @@ in order to get per example average delta.
 
 
 Below is an example of how we can apply `DeepLift` and `DeepLiftShap` on the
-`ToyModel` described above. Current implementation of DeepLift supports only
+`ToyModel` described above. The current implementation of DeepLift supports only the
 `Rescale` rule.
 For more details on alternative implementations, please see the [DeepLift paper](https://arxiv.org/abs/1704.02685).
 
@@ -286,7 +286,7 @@ In order to smooth and improve the quality of the attributions we can run
 to smoothen the attributions by aggregating them for multiple noisy
 samples that were generated by adding gaussian noise.
 
-Here is an example how we can use `NoiseTunnel` with `IntegratedGradients`.
+Here is an example of how we can use `NoiseTunnel` with `IntegratedGradients`.
 
 ```python
 ig = IntegratedGradients(model)
@@ -324,7 +324,7 @@ In this case, we choose to analyze the first neuron in the linear layer.
 
 ```python
 nc = NeuronConductance(model, model.lin1)
-attributions = nc.attribute(input, neuron_index=1, target=0)
+attributions = nc.attribute(input, neuron_selector=1, target=0)
 print('Neuron Attributions:', attributions)
 ```
 Output
@@ -338,7 +338,7 @@ It is an extension of path integrated gradients for hidden layers and holds the
 completeness property as well.
 
 It doesn't attribute the contribution scores to the input features
-but shows the importance of each neuron in selected layer.
+but shows the importance of each neuron in the selected layer.
 ```python
 lc = LayerConductance(model, model.lin1)
 attributions, delta = lc.attribute(input, baselines=baseline, target=0, return_convergence_delta=True)
@@ -433,6 +433,7 @@ Image Classification Models and Saliency Maps, K. Simonyan, et. al. 2014](https:
 * `Occlusion`: [Visualizing and Understanding Convolutional Networks](https://arxiv.org/abs/1311.2901)
 * `Shapely Value`: [A value for n-person games. Contributions to the Theory of Games 2.28 (1953): 307-317](https://apps.dtic.mil/dtic/tr/fulltext/u2/604084.pdf)
 * `Shapely Value Sampling`: [Polynomial calculation of the Shapley value based on sampling](https://www.sciencedirect.com/science/article/pii/S0305054808000804)
+* `Infidelity and Sensitivity`: [On the (In)fidelity and Sensitivity for Explanations](https://arxiv.org/abs/1901.09392)
 
 More details about the above mentioned [algorithms](https://captum.ai/docs/algorithms) and their pros and cons can be found on our [web-site](https://captum.ai/docs/algorithms_comparison_matrix).
 

captum/__init__.py

@@ -1,3 +1,3 @@
 #!/usr/bin/env python3
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

captum/_utils/common.py

@@ -9,10 +9,11 @@
 from torch import Tensor, device
 from torch.nn import Module
 
-from .._utils.typing import (
+from captum._utils.typing import (
     BaselineType,
     Literal,
     TargetType,
+    TensorOrTupleOfTensorsGeneric,
     TupleOrTensorOrBoolGeneric,
 )
 
@@ -353,6 +354,43 @@ def _format_output(
     return output if is_inputs_tuple else output[0]
 
 
+@typing.overload
+def _format_outputs(
+    is_multiple_inputs: Literal[False], outputs: List[Tuple[Tensor, ...]]
+) -> Union[Tensor, Tuple[Tensor, ...]]:
+    ...
+
+
+@typing.overload
+def _format_outputs(
+    is_multiple_inputs: Literal[True], outputs: List[Tuple[Tensor, ...]]
+) -> List[Union[Tensor, Tuple[Tensor, ...]]]:
+    ...
+
+
+@typing.overload
+def _format_outputs(
+    is_multiple_inputs: bool, outputs: List[Tuple[Tensor, ...]]
+) -> Union[Tensor, Tuple[Tensor, ...], List[Union[Tensor, Tuple[Tensor, ...]]]]:
+    ...
+
+
+def _format_outputs(
+    is_multiple_inputs: bool, outputs: List[Tuple[Tensor, ...]]
+) -> Union[Tensor, Tuple[Tensor, ...], List[Union[Tensor, Tuple[Tensor, ...]]]]:
+    assert isinstance(outputs, list), "Outputs must be a list"
+    assert is_multiple_inputs or len(outputs) == 1, (
+        "outputs should contain multiple inputs or have a single output"
+        f"however the number of outputs is: {len(outputs)}"
+    )
+
+    return (
+        [_format_output(len(output) > 1, output) for output in outputs]
+        if is_multiple_inputs
+        else _format_output(len(outputs[0]) > 1, outputs[0])
+    )
+
+
 def _run_forward(
     forward_func: Callable,
     inputs: Union[Tensor, Tuple[Tensor, ...]],
@@ -417,6 +455,15 @@ def _select_targets(output: Tensor, target: TargetType) -> Tensor:
         raise AssertionError("Target type %r is not valid." % target)
 
 
+def _contains_slice(target: Union[int, Tuple[Union[int, slice], ...]]) -> bool:
+    if isinstance(target, tuple):
+        for index in target:
+            if isinstance(index, slice):
+                return True
+        return False
+    return isinstance(target, slice)
+
+
 def _verify_select_column(
     output: Tensor, target: Union[int, Tuple[Union[int, slice], ...]]
 ) -> Tensor:
@@ -427,6 +474,24 @@ def _verify_select_column(
     return output[(slice(None), *target)]
 
 
+def _verify_select_neuron(
+    layer_output: Tuple[Tensor, ...],
+    selector: Union[int, Tuple[Union[int, slice], ...], Callable],
+) -> Tensor:
+    if callable(selector):
+        return selector(layer_output if len(layer_output) > 1 else layer_output[0])
+
+    assert len(layer_output) == 1, (
+        "Cannot select neuron index from layer with multiple tensors,"
+        "consider providing a neuron selector function instead."
+    )
+
+    selected_neurons = _verify_select_column(layer_output[0], selector)
+    if _contains_slice(selector):
+        return selected_neurons.reshape(selected_neurons.shape[0], -1).sum(1)
+    return selected_neurons
+
+
 def _extract_device(
     module: Module,
     hook_inputs: Union[None, Tensor, Tuple[Tensor, ...]],
@@ -520,3 +585,9 @@ def _sort_key_list(
     "devices with computed tensors."
 
     return out_list
+
+
+def _flatten_tensor_or_tuple(inp: TensorOrTupleOfTensorsGeneric) -> Tensor:
+    if isinstance(inp, Tensor):
+        return inp.flatten()
+    return torch.cat([single_inp.flatten() for single_inp in inp])