Deep Insight And Neural Network Analysis
Project description
Deep Insight And Neural Network Analysis
DIANNA is a Python package that brings explainable AI (XAI) to your research project. It wraps carefully selected XAI methods in a simple, uniform interface. It's built by, with and for (academic) researchers and research software engineers working on machine learning projects.
Why DIANNA?
DIANNA software is addressing needs of both (X)AI researchers and mostly the various domains scientists who are using or will use AI models for their research without being experts in (X)AI. DIANNA is future-proof: one of the very few XAI library supporting the Open Neural Network Exchange (ONNX) format.
After studying the vast XAI landscape we have made choices in the parts of the XAI Taxonomy on which methods, data modalities and problems types to focus. Our choices, based on the largest usage in scientific literature, are shown graphically in the XAI taxonomy below:
The key points of DIANNA:
- Provides an easy-to-use interface for non (X)AI experts
- Implements well-known XAI methods (LIME, RISE and Kernal SHAP) chosen by systematic and objective evaluation criteria
- Supports the de-facto standard format for neural network models - ONNX.
- Includes clear instructions for export/conversions from Tensorflow, Pytorch, Keras and scikit-learn to ONNX.
- Supports both images and text data modalities. Time series is work in progress, tabular data and even embeddings support is planned.
- Comes with simple intuitive image and text benchmarks
- Easily extendable to other XAI methods
For more information on the unique strengths of DIANNA with comparison to other tools, please see the context landscape.
Installation
DIANNA can be installed from PyPI using pip on any of the supported Python versions (see badge):
python3 -m pip install dianna
To install the most recent development version directly from the GitHub repository run:
python3 -m pip install git+https://github.com/dianna-ai/dianna.git
If you get an error related to OpenMP when importing dianna, have a look at this issue for possible workarounds.
Pre-requisites only for Macbook Pro with M1 Pro chip users
-
To install TensorFlow you can follow this tutorial.
-
To install TensorFlow Addons you can follow these steps. For further reading see this issue. Note that this temporary solution works only for macOS versions >= 12.0. Note that this step may have changed already, see https://github.com/dianna-ai/dianna/issues/245.
-
Before installing DIANNA, comment
tensorflow
requirement insetup.cfg
file (tensorflow package for M1 is calledtensorflow-macos
).
Getting started
You need:
- your trained ONNX model (convert my pytorch/tensorflow/keras/scikit-learn model to ONNX)
- 1 data item to be explained
You get:
- a relevance map overlayed over the data item
In the library's documentation, the general usage is explained in How to use DIANNA
Demo movie
Text example:
model_path = 'your_model.onnx' # model trained on text
text = 'The movie started great but the ending is boring and unoriginal.'
Which of your model's classes do you want an explanation for?
labels = [positive_class, negative_class]
Run using the XAI method of your choice, for example LIME:
explanation = dianna.explain_text(model_path, text, 'LIME')
dianna.visualization.highlight_text(explanation[labels.index(positive_class)], text)
Image example:
model_path = 'your_model.onnx' # model trained on images
image = PIL.Image.open('your_image.jpeg')
Tell us what label refers to the channels, or colors, in the image.
axis_labels = {0: 'channels'}
Which of your model's classes do you want an explanation for?
labels = [class_a, class_b]
Run using the XAI method of your choice, for example RISE:
explanation = dianna.explain_image(model_path, image, 'RISE', axis_labels=axis_labels, labels=labels)
dianna.visualization.plot_image(explanation[labels.index(class_a)], original_data=image)
Datasets
DIANNA comes with simple datasets. Their main goal is to provide intuitive insight into the working of the XAI methods. They can be used as benchmarks for evaluation and comparison of existing and new XAI methods.
Images
Dataset | Description | Examples | Generation |
---|---|---|---|
Binary MNIST | Greyscale images of the digits "1" and "0" - a 2-class subset from the famous MNIST dataset for handwritten digit classification. | Binary MNIST dataset generation | |
Simple Geometric (circles and triangles) | Images of circles and triangles for 2-class geometric shape classificaiton. The shapes of varying size and orientation and the background have varying uniform gray levels. | Simple geometric shapes dataset generation | |
Simple Scientific (LeafSnap30) | Color images of tree leaves - a 30-class post-processed subset from the LeafSnap dataset for automatic identification of North American tree species. | LeafSnap30 dataset generation |
Text
Dataset | Description | Examples | Generation |
---|---|---|---|
Stanford sentiment treebank | Dataset for predicting the sentiment, positive or negative, of movie reviews. | This movie was actually neither that funny, nor super witty. | Sentiment treebank |
ONNX models
We work with ONNX! ONNX is a great unified neural network standard which can be used to boost reproducible science. Using ONNX for your model also gives you a boost in performance! In case your models are still in another popular DNN (deep neural network) format, here are some simple recipes to convert them:
- pytorch and pytorch-lightning - use the built-in
torch.onnx.export
function to convert pytorch models to onnx, or call the built-into_onnx
function on yourLightningModule
to export pytorch-lightning models to onnx. - tensorflow - use the
tf2onnx
package to convert tensorflow models to onnx. - keras - same as the conversion from tensorflow to onnx, the
tf2onnx
package also supports keras. - scikit-learn - use the
skl2onnx
package to scikit-learn models to onnx.
More converters with examples and tutorials can be found on the ONNX tutorial page.
And here are links to notebooks showing how we created our models on the benchmark datasets:
Images
Models | Generation |
---|---|
Binary MNIST model | Binary MNIST model generation |
Simple Geometric model | Simple geometric shapes model generation |
Simple Scientific model | LeafSnap30 model generation |
Text
Models | Generation |
---|---|
Movie reviews model | Stanford sentiment treebank model generation |
We envision the birth of the ONNX Scientific models zoo soon...
Tutorials
DIANNA supports different data modalities and XAI methods. The table contains links to the relevant XAI method's papers (for some explanatory videos on the methods, please see tutorials). The DIANNA tutorials cover each supported method and data modality on a least one dataset. Our future plans to expand DIANNA with more data modalities and XAI methods are given in the ROADMAP.
Data \ XAI | RISE | LIME | KernelSHAP |
---|---|---|---|
Images | :white_check_mark: | :white_check_mark: | :white_check_mark: |
Text | :white_check_mark: | :white_check_mark: | planned |
Timeseries | work in progress | work in progress | work in progress |
Embedding | coming soon | coming soon | coming soon |
Graphs | planned | planned | planned |
Tabular |
LRP and PatternAttribution also feature in the top 5 of our thoroughly evaluated XAI methods using objective criteria (details in coming blog-post). Contributing by adding these and more (new) post-hoc explainability methods on ONNX models is very welcome!
Reference documentation
For detailed information on using specific DIANNA functions, please visit the documentation page hosted at Readthedocs.
Contributing
If you want to contribute to the development of DIANNA, have a look at the contribution guidelines. See our developer documentation for information on developer installation, running tests, generating documentation, versioning and making a release.
How to cite us
If you use this package for your scientific work, please consider citing it as:
Ranguelova, E., Bos, P., Liu, Y., Meijer, C., Oostrum, L., Crocioni, G., Ootes, L., Chandramouli, P., Jansen, A. (2022). dianna (*[VERSION YOU USED]*). Zenodo. https://zenodo.org/record/5592607
See also the Zenodo page for exporting the citation to BibTteX and other formats.
Credits
This package was created with Cookiecutter and the NLeSC/python-template.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file dianna-0.8.0.tar.gz
.
File metadata
- Download URL: dianna-0.8.0.tar.gz
- Upload date:
- Size: 39.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 245e024843faff22b57cfc8b39c6c7e19f2323ea2c848a48329abe8b20711909 |
|
MD5 | b22c0678a52ee13b37befdf975899973 |
|
BLAKE2b-256 | 79731dd66c04a8b2ed7211bf8b3e9edaa9a52603dc10ba227fc4a02edf2bae7c |
File details
Details for the file dianna-0.8.0-py3-none-any.whl
.
File metadata
- Download URL: dianna-0.8.0-py3-none-any.whl
- Upload date:
- Size: 33.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.16
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ab9a9643b196d63f54ac92b5931900f09fea8fd60c972ba7261b6283a97cb7c4 |
|
MD5 | c24f0a37b69c005dfe675fa2443e36bd |
|
BLAKE2b-256 | 1859d4af1e87651fff85e562b622ea3dead578a986ca99431359685e951af060 |