iNNvestigate 2.0

.git-blame-ignore-revs

@@ -0,0 +1,3 @@
+# Formatting commits
+7bd44f465186adad90caafa765e0d5ab0e246ada
+72f5ffbd9bc407a9e538598872cce3953de1b230

.gitconfig

@@ -0,0 +1 @@
+blame.ignorerevsfile=.git-blame-ignore-revs

.github/workflows/ci.yml

@@ -1,12 +1,13 @@
-name: Test iNNvestigate
+name: CI
 
 on: 
   - push
   - pull_request
 
 jobs:
-  linting:
-    # Run linting outside of matrix
+  formatting:
+    # Run formatting checks outside of matrix
+    name: Formatting
     runs-on: ubuntu-latest
     steps:
       # Check-out repo and set-up python  
@@ -25,12 +26,17 @@ jobs:
       - name: Format check with isort
         run: isort --check .
   test:
-    needs: linting
+    name: Tests Python ${{ matrix.python-version }} - ${{ matrix.os }} - ${{ matrix.architecture }}
     strategy:
       fail-fast: true
       matrix:
-        os: [ "ubuntu-latest", "windows-latest" ]
-        python-version: [ "3.7", ]
+        os: 
+          - ubuntu-latest
+        architecture: 
+          - x64
+        python-version: 
+          - '3.7'
+          - '3.10'
     defaults:
       run:
         shell: bash
@@ -43,27 +49,28 @@ jobs:
         uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
+          architecture: ${{ matrix.architecture }}
       # Install & configure poetry      
       - name: Install Poetry
-        uses: snok/install-poetry@v1.1.6
+        uses: snok/install-poetry@v1
         with:
           virtualenvs-create: true
           virtualenvs-in-project: true
+          installer-parallel: true
       # Load cached venv if cache exists      
       - name: Load cached venv
-        id: cached-pip-wheels
+        id: cached-poetry-dependencies
         uses: actions/cache@v2
         with:
-          path: ~/.cache
-          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+          path: .venv
+          key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
       # Install dependencies
       - name: Install dependencies
-        run: poetry install --no-interaction --no-root
-      # Install your root project, if required 
-      - name: Install library
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
         run: poetry install --no-interaction
-      # Run fast tests on matrix, full tests for coverage
+      # Run fast tests on matrix.
+      # Coverage options can be found in pyproject.toml
       - name: Run tests
         run: |
-          source $VENV
+          source .venv/bin/activate
           pytest ./tests -m fast 

.gitignore

@@ -125,5 +125,14 @@ nosetests.cfg
 *.h5
 *.png
 
+# ignore VGG16
+tests/references/vgg16
+
 # ignore nbconvert script output
-examples/nbconvert_tmp
+examples/nbconvert_tmp
+
+# ignore data downloaded by notebooks
+examples/images
+examples/stanfordSentimentTreebank
+examples/stanfordSentimentTreebank.zip
+examples/__MACOSX

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.5.0
+    hooks:
+    - id: check-added-large-files
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v2.34.0
+    hooks:
+    -   id: pyupgrade
+        args: [--py37-plus]
+  - repo: local
+    hooks:
+    - id: black
+      name: black
+      entry: poetry run black src/
+      language: system
+      always_run: true
+      pass_filenames: false
+    - id: isort
+      name: isort
+      entry: poetry run isort src/
+      language: system
+      always_run: true
+      pass_filenames: false

.pylintrc

@@ -143,7 +143,12 @@ disable=print-statement,
         xreadlines-attribute,
         deprecated-sys-function,
         exception-escape,
-        comprehension-escape
+        comprehension-escape,
+        no-name-in-module, # TensorFlow 2 imports throw "No name [name] in module 'LazyLoader' (no-name-in-module)"
+        missing-module-docstring, # TODO: add back
+        missing-class-docstring, # TODO: add back
+        missing-function-docstring, # TODO: add back
+        too-few-public-methods,
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option
@@ -225,7 +230,6 @@ spelling-store-unknown-words=no
 # List of note tags to take in consideration, separated by a comma.
 notes=FIXME,
       XXX,
-      TODO
 
 # Regular expression of note tags to take in consideration.
 #notes-rgx=
@@ -436,20 +440,18 @@ good-names=i,
            j,
            k,
            l,
+           n,
+           x,
+           y,
+           a,
+           b,
            ex,
            Run,
-           X, 
-           Y,
-           Z,
-           R,
-           A,
-           B,
            _
 
 # Good variable names regexes, separated by a comma. If names match any regex,
 # they will always be accepted
-good-names-rgxs=[XYZRAB]+,
-            _[XYZRAB],
+good-names-rgxs=(.*_)?[XYZRABC]s?,
 
 # Include a hint for the correct naming format with invalid-name.
 include-naming-hint=no

README.md

@@ -1,10 +1,13 @@
 # [iNNvestigate neural networks!](https://github.com/albermax/innvestigate) [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=iNNvestigate%20neural%20networks!&url=https://github.com/albermax/innvestigate&hashtags=iNNvestigate,artificialintelligence,machinelearning,deeplearning,datascience)
 
+[![Build Status](https://github.com/albermax/innvestigate/actions/workflows/ci.yml/badge.svg)](https://github.com/albermax/innvestigate/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://innvestigate.readthedocs.io/en/latest/)
 
-[![GitHub package version](https://img.shields.io/badge/Version-v1.0.9-green.svg)](https://github.com/albermax/innvestigate)
-[![Keras package version](https://img.shields.io/badge/KerasVersion-v2.2.4-green.svg)](https://github.com/albermax/innvestigate)
-[![License: BSD-2](https://img.shields.io/badge/License-BSD--2-blue.svg)](https://github.com/albermax/innvestigate/blob/master/LICENSE)
-[![Build Status](https://travis-ci.org/albermax/innvestigate.svg?branch=master)](https://travis-ci.org/albermax/innvestigate)
+[![PyPI package version](https://img.shields.io/pypi/v/innvestigate)](https://pypi.org/project/innvestigate/)
+[![GitHub package version](https://img.shields.io/github/v/tag/albermax/innvestigate)](https://github.com/albermax/innvestigate/tags)
+[![Keras package version](https://img.shields.io/badge/TensorFlow-^2.7-orange.svg)](https://github.com/albermax/innvestigate)
+[![License: BSD-2](https://img.shields.io/badge/License-BSD--2-purple.svg)](https://github.com/albermax/innvestigate/blob/master/LICENSE)
+[![Black](https://img.shields.io/badge/code_style-black-black.svg)](https://github.com/psf/black)
 
 ![Different explanation methods on ImageNet.](https://github.com/albermax/innvestigate/raw/master/examples/images/analysis_grid.png)
 
@@ -46,13 +49,10 @@ Our goal is to make analyzing neural networks' predictions easy!
 ## Installation
 
 iNNvestigate can be installed with the following commands.
-The library is based on Keras and therefore requires a supported [Keras-backend](https://keras.io/backend/)
-o(Currently only the TensorFlow backend is supported. We test with Python 3.6, TensorFlow 1.12 and Cuda 9.x.):
+The library is based on Keras and therefore requires TensorFlow 2:
 
 ```bash
 pip install innvestigate
-# Installing Keras backend
-pip install [tensorflow | theano | cntk]
 ```
 
 To use the example scripts and notebooks one additionally needs to install the package matplotlib:
@@ -61,11 +61,13 @@ To use the example scripts and notebooks one additionally needs to install the p
 pip install matplotlib
 ```
 
-The library's tests can be executed via:
+The library's tests can be executed via `pytest`. The easiest way to do reproducible development on iNNvestigate is to install all dev dependencies via [Poetry](https://python-poetry.org):
 ```bash
 git clone https://github.com/albermax/innvestigate.git
 cd innvestigate
-python setup.py test
+
+poetry install
+poetry run pytest
 ```
 
 ## Usage and Examples
@@ -78,11 +80,10 @@ The iNNvestigate library contains implementations for the following methods:
 * *signal:*
   * **deconvnet:** [DeConvNet](https://arxiv.org/abs/1311.2901) applies a ReLU in the gradient computation instead of the gradient of a ReLU.
   * **guided:** [Guided BackProp](https://arxiv.org/abs/1412.6806) applies a ReLU in the gradient computation additionally to the gradient of a ReLU.
-  * **pattern.net:** [PatternNet](https://arxiv.org/abs/1705.05598) estimates the input signal of the output neuron.
+  * **pattern.net:** [PatternNet](https://arxiv.org/abs/1705.05598) estimates the input signal of the output neuron. (*Note: not available in iNNvestigate 2.0*)
 * *attribution:*
   * **input_t_gradient:** Input \* Gradient
   * **deep_taylor[.bounded]:** [DeepTaylor](https://www.sciencedirect.com/science/article/pii/S0031320316303582?via%3Dihub) computes for each neuron a root point, that is close to the input, but which's output value is 0, and uses this difference to estimate the attribution of each neuron recursively.
-  * **pattern.attribution:** [PatternAttribution](https://arxiv.org/abs/1705.05598) applies Deep Taylor by searching root points along the signal direction of each neuron.
   * **lrp.\*:** [LRP](http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0130140) attributes recursively to each neuron's input relevance proportional to its contribution of the neuron output.
   * **integrated_gradients:** [IntegratedGradients](https://arxiv.org/abs/1703.01365) integrates the gradient along a path from the input to a reference.
 * *miscellaneous:*
@@ -126,7 +127,7 @@ Let's look at an example ([code](https://github.com/albermax/innvestigate/blob/m
 ```python
 import innvestigate
 import innvestigate.utils
-import keras.applications.vgg16 as vgg16
+import tensorflow.keras.applications.vgg16 as vgg16
 
 # Get model
 model, preprocess = vgg16.VGG16(), vgg16.preprocess_input
@@ -207,3 +208,8 @@ please open an issue or submit a pull request.
 ## Releases
 
 [Can be found here.](https://github.com/albermax/innvestigate/blob/master/VERSION.md)
+
+
+## Acknowledgements
+
+> Adrian Hill acknowledges support by the Federal Ministry of Education and Research (BMBF) for the Berlin Institute for the Foundations of Learning and Data (BIFOLD) (01IS18037A).

docs/source/conf.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # Configuration file for the Sphinx documentation builder.
 #
 # This file does only contain a selection of the most common options. For a

examples/embedding_minimal_example.py

@@ -4,14 +4,15 @@
 
 import innvestigate
 
+# Create Keras Sequential Model
 model = Sequential()
 model.add(Embedding(input_dim=219, output_dim=8))
 model.add(Conv1D(filters=64, kernel_size=8, padding="valid", activation="relu"))
 model.add(GlobalMaxPooling1D())
 model.add(Dense(16, activation="relu"))
 model.add(Dense(2, activation=None))
 
-# test
+# Analyze model
 model.predict(np.random.randint(1, 219, (1, 100)))  # [[0.04913538 0.04234646]]
 
 analyzer = innvestigate.create_analyzer(