Metadata-Version: 2.0
Name: saliency
Version: 0.0.2
Summary: Saliency methods for TensorFlow
Home-page: https://github.com/pair-code/saliency
Author: The saliency authors
Author-email: tf-saliency-dev@google.com
License: Apache 2.0
Keywords: saliency mask neural network deep learning
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: numpy
Requires-Dist: tensorflow

# Saliency Methods

## Introduction

This repository contains code for [SmoothGrad](https://pair-code.github.io/saliency/), as well as implementations of
several other saliency techniques. Each of these techniques can also be
augmented with SmoothGrad. The techniques implemented in this library are:

*   Vanilla Gradients
    ([paper](https://scholar.google.com/scholar?q=Visualizing+higher-layer+features+of+a+deep+network&btnG=&hl=en&as_sdt=0%2C22),
    [paper](https://arxiv.org/abs/1312.6034))
*   Guided Backpropogation ([paper](https://arxiv.org/abs/1412.6806))
*   Integrated Gradients ([paper](https://arxiv.org/abs/1703.01365))
*   Occlusion

This list is by no means comprehensive. We are accepting pull requests to add
new methods!

## Download
```
git clone https://github.com/pair-code/saliency
cd saliency
```

## Usage

Each saliency mask class extends from the `SaliencyMask` base class. This class
contains the following methods:

*   `__init__(graph, session, y, x)`: Constructor of the SaliencyMask. This can
    modify the graph, or sometimes create a new graph. Often this will add nodes
    to the graph, so this shouldn't be called continuously. `y` is the output
    tensor to compute saliency masks with respect to, `x` is the input tensor
    with the outer most dimension being batch size.
*   `GetMask(x_value, feed_dict)`: Returns a mask of the shape of non-batched
    `x_value` given by the saliency technique.
*   `GetSmoothedMask(x_value, feed_dict)`: Returns a mask smoothed of the shape
    of non-batched `x_value` with the SmoothGrad technique.

The visualization module contains two visualization methods:

* ```VisualizeImageGrayscale(image_3d, percentile)```: Marginalizes across the
  absolute value of each channel to create a 2D single channel image, and clips
  the image at the given percentile of the distribution. This method returns a
  2D tensor normalized between 0 to 1.
* ```VisualizeImageDiverging(image_3d, percentile)```: Marginalizes across the
  value of each channel to create a 2D single channel image, and clips the
  image at the given percentile of the distribution. This method returns a
  2D tensor normalized between -1 to 1 where zero remains unchanged.

If the sign of the value given by the saliency mask is not important, then use
```VisualizeImageGrayscale```, otherwise use ```VisualizeImageDiverging```. See
the SmoothGrad paper for more details on which visualization method to use.

## Examples

[This example iPython notebook]([http://github.com/pair-code/saliency/blob/master/Examples.ipynb]) shows
these techniques is a good starting place.

Another example of using GuidedBackprop with SmoothGrad from TensorFlow:

```
from guided_backprop import GuidedBackprop
import visualization

...
# Tensorflow graph construction here.
y = logits[5]
x = tf.placeholder(...)
...

# Compute guided backprop.
# NOTE: This creates another graph that gets cached, try to avoid creating many
# of these.
guided_backprop_saliency = GuidedBackpropSaliency(graph, session, y, x)

...
# Load data.
image = GetImagePNG(...)
...

smoothgrad_guided_backprop =
    guided_backprop_saliency.GetSmoothedMask(image, feed_dict={...})

# Compute a 2D tensor for visualization.
grayscale_visualization = visualization.VisualizeImageGrayscale(
    smoothgrad_guided_backprop)
```

This is not an official Google product.


