Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Fix typos #25

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# The LRP Toolbox for Artificial Neural Networks (1.3.1)

The Layer-wise Relevance Propagation (LRP) algorithm explains a classifer's prediction
The Layer-wise Relevance Propagation (LRP) algorithm explains a classifier's prediction
specific to a given data point by attributing
relevance scores to important components
of the input by using the topology of the learned model itself.
Expand Down Expand Up @@ -60,7 +60,7 @@ Have a look at [the manual](https://github.com/sebastian-lapuschkin/lrp_toolbox/

## The LRP Toolbox Paper

When using (any part) of this toolbox, please cite [our paper](http://jmlr.org/papers/volume17/15-618/15-618.pdf)
When using (any part of) this toolbox, please cite [our paper](http://jmlr.org/papers/volume17/15-618/15-618.pdf)

@article{JMLR:v17:15-618,
author = {Sebastian Lapuschkin and Alexander Binder and Gr{{\'e}}goire Montavon and Klaus-Robert M{{{\"u}}}ller and Wojciech Samek},
Expand Down
2 changes: 1 addition & 1 deletion caffe-master-lrp/docs/multigpu.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ updated model, 0\-\>2, and then 0\-\>1, 2\-\>3.

For best performance, P2P DMA access between devices is needed. Without P2P access, for example crossing PCIe root complex, data is copied through host and effective exchange bandwidth is greatly reduced.

Current implementation has a "soft" assumption that the devices being used are homogeneous. In practice, any devices of the same general class should work together, but performance and total size is limited by the smallest device being used. e.g. if you combine a TitanX and a GTX980, peformance will be limited by the 980. Mixing vastly different levels of boards, e.g. Kepler and Fermi, is not supported.
Current implementation has a "soft" assumption that the devices being used are homogeneous. In practice, any devices of the same general class should work together, but performance and total size is limited by the smallest device being used. e.g. if you combine a TitanX and a GTX980, performance will be limited by the 980. Mixing vastly different levels of boards, e.g. Kepler and Fermi, is not supported.

"nvidia-smi topo -m" will show you the connectivity matrix. You can do P2P through PCIe bridges, but not across socket level links at this time, e.g. across CPU sockets on a multi-socket motherboard.

Expand Down
10 changes: 5 additions & 5 deletions doc/manual/manual.tex
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ \section{Overview}
The toolbox comes with platform-independent stand-alone implementations of LRP in Matlab and python and a plugin for the Caffe~\cite{jia2014caffe} Deep Learning Toolkit.
Models, Data and Results can be imported and exported as Matlab's \texttt{.mat} files, numpy's \texttt{.npy} or \texttt{.npz} files for python or ASCII-formatted plain text. For details about the supported formats for each implementation see Section \ref{sec:implementation}.

Both the Matlab and python code are fully documented and for each example impelentations demonstrate the application of LRP at hand of the MNIST hand written digit data set \cite{lecun1998mnist}.
Both the Matlab and python code are fully documented and for each example implementations demonstrate the application of LRP at hand of the MNIST hand written digit data set \cite{lecun1998mnist}.
The LRP implementation for Caffe extends the respective classes and files with the needed functionality and operates directly on images and pre-trained model from the command line.
The most recent official release of the source code and example data and models are available from
\begin{center}
Expand Down Expand Up @@ -134,7 +134,7 @@ \subsection*{Out of the box: using \emph{Singularity}}

%run the demo
The container comes with a demo skript that calculates relevance scores for images on the caffe models.
It is called using \verb!singularity run! (or directly as an executable, assuming the required permissionas have been set) and a configuration file, a filelist file and an output path need to be specified:
It is called using \verb!singularity run! (or directly as an executable, assuming the required permission as have been set) and a configuration file, a filelist file and an output path need to be specified:
\begin{Verbatim}[frame = single]
[singularity run] ./caffe-lrp-cpu-u16.04.sif -c CONFIGPATH -f FILELISTPATH -p OUTPUTPATH
\end{Verbatim}
Expand Down Expand Up @@ -164,7 +164,7 @@ \subsubsection*{Matlab and python}

\subsubsection*{Caffe open-source package}

\emph{Note that below information is deprecated for Linux versions newer that Ubuntu 16.04 LTS. We recommend sticking to the Singulariy build described earlier to minimize headaches.}
\emph{Note that below information is deprecated for Linux versions newer that Ubuntu 16.04 LTS. We recommend sticking to the Singularity build described earlier to minimize headaches.}
\vspace{2mm}

The LRP implementation for Caffe has been forked from the Caffe repository on October 3rd 2015 (rc2). After fulfilling all requirements listed above, execute
Expand All @@ -173,7 +173,7 @@ \subsubsection*{Caffe open-source package}
make clean
make all
\end{Verbatim}
Note that the Caffe-based LRP implementation currently only supports execution only on CPUs and already provides a correspondingly condigured \texttt{Makefile.config}.
Note that the Caffe-based LRP implementation currently only supports execution only on CPUs and already provides a correspondingly configured \texttt{Makefile.config}.

After successfully building Caffe, navigate to the subdirectory \texttt{demonstrator} and execute \texttt{build.sh} (include and library paths might have to be adjusted) to compile the executables \texttt{lrp\_demo}, \texttt{lrp\_parallel\_demo}, \texttt{lrp\_demo\_minimaloutput} and \texttt{lrp\_parallel\_demo\_minimaloutput} for sequential and parallel heatmap computation respectively. Note that while the binaries ending in \texttt{\_minimaloutput} will only write out plain text relevance maps and the ten dominantly predicted classes, while the other binaries will also produce images showing the actual resized and padded network input, as well as a heatmap visualization as images.

Expand Down Expand Up @@ -289,7 +289,7 @@ \subsection*{Decomposition Variants and Parameters}
\end{align}
Adding the constraint $\alpha + \beta = 1$ ensures the relevance conservation principle to hold and reduces the number of added free parameters to one.

This decomposition method is especially usefull when paired with a networks making use of ReLU activation layers, since hidden layer inputs will always be $\geq 0$ and their pre-activation outputs also need to be $\geq 0$ to ``fire''. This means that positively weighted connections $w_{ij}$ --- which all factor into $z_{ij}^+$ --- propagate the inputs in an activatingly, while negative weights create deactivating messages $z_{ij}^-$. So by choosing $\alpha$ (and therefore $\beta$) appropriately, allows to choose what is backwards-propagated in terms of relevance. For example setting $\alpha = 1$, causes $\beta = 0$ will result in relevance maps which yield insight into which features cause neuron activations, while $\alpha=2, \beta=-1$ yields a more balanced explanation with still more focus on the neuron-exciting inputs. Be careful, however, with setting a variable to 0: Sum-pooling after a ReLu activation layer will only yield positive activations. Here, setting $\alpha=0,\beta=1$ will result in no heatmap at all, since there are no inhibiting layer inputs to propagate the relevance to.
This decomposition method is especially useful when paired with a networks making use of ReLU activation layers, since hidden layer inputs will always be $\geq 0$ and their pre-activation outputs also need to be $\geq 0$ to ``fire''. This means that positively weighted connections $w_{ij}$ --- which all factor into $z_{ij}^+$ --- propagate the inputs in an activatingly, while negative weights create deactivating messages $z_{ij}^-$. So by choosing $\alpha$ (and therefore $\beta$) appropriately, allows to choose what is backwards-propagated in terms of relevance. For example setting $\alpha = 1$, causes $\beta = 0$ will result in relevance maps which yield insight into which features cause neuron activations, while $\alpha=2, \beta=-1$ yields a more balanced explanation with still more focus on the neuron-exciting inputs. Be careful, however, with setting a variable to 0: Sum-pooling after a ReLu activation layer will only yield positive activations. Here, setting $\alpha=0,\beta=1$ will result in no heatmap at all, since there are no inhibiting layer inputs to propagate the relevance to.

\paragraph{The $w^2$-decomposition formula}
The $w^2$-rule was first introduced in \cite{MonArXiv16} and is obtained by choosing the closest root to $\x$ in direction of maximal descent when using Deep Taylor Decomposition. Although it might seem that this decomposition is independent to the input data, the resulting heatmap explanations are unique for each data point through the influence of $R^{(l)}$. The relevance messages for this decomposition compute as
Expand Down
4 changes: 2 additions & 2 deletions singularity/caffe_lrp_commandline.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
"""
This script catches the parameters passed to the runnable singularity container from the outside and
This script catches the parameters passed to the runnable singularity container from the outside and
translates them into command line inputs for the caffe binaries living inside the container.
"""

Expand All @@ -16,7 +16,7 @@

#prepare command line arguments
parser = argparse.ArgumentParser(description="Process models and data, produce explanatory heatmaps")
parser.add_argument('--binary', '-b', default='default', help='Which binary to use for computing heatmaps? Determines asynchronity and amount of meta-infornation.')
parser.add_argument('--binary', '-b', default='default', help='Which binary to use for computing heatmaps? Determines asynchronicity and amount of meta-information.')
parser.add_argument('--config', '-c', required=True, help='Path to the lrp demonstrator configuration file')
parser.add_argument('--filelist', '-f', required=True, help='Path to the list-of-files-file with pairs of img_path class_to_explain in each line')
parser.add_argument('--prepath', '-p', default='./', help='Path segment to preprend to the generated output files. "./" is the default value')
Expand Down