diff --git a/README.md b/README.md index de81f618..909ee535 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ DIANNA is a Python package that brings explainable AI (XAI) to your research pro 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)](https://onnx.ai/) format. After studying the vast XAI landscape we have made choices in the parts of the [XAI Taxonomy](https://doi.org/10.3390/make3030032) 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: @@ -78,6 +79,7 @@ The key points of DIANNA: For more information on the unique strengths of DIANNA with comparison to other tools, please see the [context landscape](https://dianna.readthedocs.io/en/latest/CONTEXT.html). ## Installation + [![workflow pypi badge](https://img.shields.io/pypi/v/dianna.svg?colorB=blue)](https://pypi.python.org/project/dianna/) [![supported python versions](https://img.shields.io/pypi/pyversions/dianna)](https://pypi.python.org/project/dianna/) @@ -98,18 +100,19 @@ If you get an error related to OpenMP when importing dianna, have a look at [thi ### Pre-requisites only for Macbook Pro with M1 Pro chip users - To install TensorFlow you can follow this [tutorial](https://betterdatascience.com/install-tensorflow-2-7-on-macbook-pro-m1-pro/). - - To install TensorFlow Addons you can follow these [steps](https://github.com/tensorflow/addons/pull/2504). For further reading see this [issue](https://github.com/tensorflow/addons/issues/2503). 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 in `setup.cfg` file (tensorflow package for M1 is called `tensorflow-macos`). ## Getting started + You need: + - your trained ONNX model ([convert my pytorch/tensorflow/keras/scikit-learn model to ONNX](https://github.com/dianna-ai/dianna#onnx-models)) - 1 data item to be explained You get: - - a relevance map overlayed over the data item + +- a relevance map overlayed over the data item In the library's documentation, the general usage is explained in [How to use DIANNA](https://dianna.readthedocs.io/en/latest/usage.html) @@ -118,42 +121,83 @@ In the library's documentation, the general usage is explained in [How to use DI [![Watch the video on YouTube](https://img.youtube.com/vi/u9_c5DJewLU/default.jpg)](https://youtu.be/u9_c5DJewLU) ### Text example: + ```python 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? + ```python labels = [positive_class, negative_class] ``` + Run using the XAI method of your choice, for example LIME: + ```python explanation = dianna.explain_text(model_path, text, 'LIME') dianna.visualization.highlight_text(explanation[labels.index(positive_class)], text) ``` -![image](https://user-images.githubusercontent.com/6087314/155532504-6f90f032-cbb4-4e71-9b99-aa9c0de4e86a.png) +![image](https://user-images.githubusercontent.com/6087314/155532504-6f90f032-cbb4-4e71-9b99-aa9c0de4e86a.png) ### Image example: + ```python 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. + ```python axis_labels = {0: 'channels'} ``` + Which of your model's classes do you want an explanation for? + ```python labels = [class_a, class_b] ``` + Run using the XAI method of your choice, for example RISE: + ```python 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) ``` + ![image](https://user-images.githubusercontent.com/6087314/155557077-e2052094-d8ac-49d3-a840-0160256d53a6.png) +### Time-series example: + +```python +model_path = 'your_model.onnx' # model trained on images +timeseries_instance = pd.read_csv('your_data_instance.csv').astype(float) + +num_features = len(timeseries_instance ) # The number of features to include in the explanation. +num_samples = 500 # The number of samples to generate for the LIME explainer. +``` + +Which of your model's classes do you want an explanation for? + +```python +class_names= [class_a, class_b] # String representation of the different classes of interest +labels = np.argsort(class_names) # Numerical representation of the different classes of interest for the model +``` + +Run using the XAI method of your choice, for example LIME with the following additional arguments: + +```python +explanation = dianna.explain_timeseries(model_path, timeseries_data=timeseries_instance , method='LIME', + labels=labels, class_names=class_names, num_features=num_features, + num_samples=num_samples, distance_method='cosine') + +``` + +For visualization of the heatmap please refer to the [tutorial](https://github.com/dianna-ai/dianna/blob/main/tutorials/lime_timeseries_coffee.ipynb) + ## Dashboard Explore your trained model explained using the DIANNA dashboard. [Click here](https://github.com/dianna-ai/dianna/tree/main/dianna/dashboard) for more information. @@ -163,30 +207,36 @@ Explore your trained model explained using the DIANNA dashboard. [Click here](ht ## 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 mnist_zero_and_one_half_size| Greyscale images of the digits "1" and "0" - a 2-class subset from the famous [MNIST dataset](http://yann.lecun.com/exdb/mnist/) for handwritten digit classification. |BinaryMNIST| [Binary MNIST dataset generation](https://github.com/dianna-ai/dianna-exploration/tree/main/example_data/dataset_preparation/MNIST)| -|[Simple Geometric (circles and triangles)](https://doi.org/10.5281/zenodo.5012824) Simple Geometric Logo | 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. | SimpleGeometric| [Simple geometric shapes dataset generation](https://github.com/dianna-ai/dianna-exploration/tree/main/example_data/dataset_preparation/geometric_shapes) | -|[Simple Scientific (LeafSnap30)](https://zenodo.org/record/5061353/)LeafSnap30 Logo | Color images of tree leaves - a 30-class post-processed subset from the LeafSnap dataset for automatic identification of North American tree species.|LeafSnap| [LeafSnap30 dataset generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/dataset_preparation/LeafSnap/)| + +| Dataset | Description | Examples | Generation | +| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Binary MNIST `mnist_zero_and_one_half_size` | Greyscale images of the digits "1" and "0" - a 2-class subset from the famous[MNIST dataset](http://yann.lecun.com/exdb/mnist/) for handwritten digit classification. | `BinaryMNIST` | [Binary MNIST dataset generation](https://github.com/dianna-ai/dianna-exploration/tree/main/example_data/dataset_preparation/MNIST) | +| [Simple Geometric (circles and triangles)](https://doi.org/10.5281/zenodo.5012824) `Simple Geometric Logo` | 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. | `SimpleGeometric` | [Simple geometric shapes dataset generation](https://github.com/dianna-ai/dianna-exploration/tree/main/example_data/dataset_preparation/geometric_shapes) | +| [Simple Scientific (LeafSnap30)](https://zenodo.org/record/5061353/)`LeafSnap30 Logo` | Color images of tree leaves - a 30-class post-processed subset from the LeafSnap dataset for automatic identification of North American tree species. | `LeafSnap` | [LeafSnap30 dataset generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/dataset_preparation/LeafSnap/) | ### Text -|Dataset|Description|Examples|Generation| -|:-----|:----|:---|:----| -| [Stanford sentiment treebank](https://nlp.stanford.edu/sentiment/index.html)nlp-logo_half_size|Dataset for predicting the sentiment, positive or negative, of movie reviews. | _This movie was actually neither that funny, nor super witty._|[Sentiment treebank](https://nlp.stanford.edu/sentiment/treebank.html)| + +| Dataset | Description | Examples | Generation | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | :--------------------------------------------------------------- | :------------------------------------------------------------------ | +| [Stanford sentiment treebank](https://nlp.stanford.edu/sentiment/index.html) `nlp-logo_half_size` | Dataset for predicting the sentiment, positive or negative, of movie reviews. | _This movie was actually neither that funny, nor super witty._ | [Sentiment treebank](https://nlp.stanford.edu/sentiment/treebank.html) | ### Time series -|Dataset|Description|Examples|Generation| -|:-----|:----|:---|:----| -| [Coffee dataset](https://timeseriesclassification.com/description.php?Dataset=Coffee) Coffe Logo | Food spectographs time series dataset for a two class problem to distinguish between Robusta and Arabica coffee beans.| example image| [data source](https://github.com/QIBChemometrics/Benchtop-NMR-Coffee-Survey)| -| [Weather dataset](https://zenodo.org/record/7525955) Weather Logo |The light version of the weather prediciton dataset, which contains daily observations (89 features) for 11 European locations through the years 2000 to 2010.| example image | [data source](https://github.com/florian-huber/weather_prediction_dataset) | + +| Dataset | Description | Examples | Generation | +| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | +| [Coffee dataset](https://timeseriesclassification.com/description.php?Dataset=Coffee) `Coffe Logo` | Food spectographs time series dataset for a two class problem to distinguish between Robusta and Arabica coffee beans. | `example image` | [data source](https://github.com/QIBChemometrics/Benchtop-NMR-Coffee-Survey) | +| [Weather dataset](https://zenodo.org/record/7525955) `Weather Logo` | The light version of the weather prediciton dataset, which contains daily observations (89 features) for 11 European locations through the years 2000 to 2010. | `example image` | [data source](https://github.com/florian-huber/weather_prediction_dataset) | ## 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](https://github.com/dianna-ai/dianna/blob/main/tutorials/conversion_onnx/pytorch2onnx.ipynb) - use the built-in [`torch.onnx.export`](https://pytorch.org/docs/stable/onnx.html) function to convert pytorch models to onnx, or call the built-in [`to_onnx`](https://pytorch-lightning.readthedocs.io/en/latest/deploy/production_advanced.html) function on your [`LightningModule`](https://lightning.ai/docs/pytorch/latest/api/lightning.pytorch.core.LightningModule.html#lightning.pytorch.core.LightningModule) to export pytorch-lightning models to onnx. * [tensorflow](https://github.com/dianna-ai/dianna/blob/main/tutorials/conversion_onnx/tensorflow2onnx.ipynb) - use the [`tf2onnx`](https://github.com/onnx/tensorflow-onnx) package to convert tensorflow models to onnx. * [keras](https://github.com/dianna-ai/dianna/blob/main/tutorials/conversion_onnx/keras2onnx.ipynb) - same as the conversion from tensorflow to onnx, the [`tf2onnx`](https://github.com/onnx/tensorflow-onnx) package also supports keras. @@ -195,41 +245,44 @@ DIANNA comes with simple datasets. Their main goal is to provide intuitive insig More converters with examples and tutorials can be found on the [ONNX tutorial page](https://github.com/onnx/tutorials). And here are links to notebooks showing how we created our models on the benchmark datasets: + ### Images -|Models|Generation| -|:-----|:----| -|[Binary MNIST model](https://zenodo.org/record/5907177)| [Binary MNIST model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/MNIST/generate_model_binary.ipynb)| -|[Simple Geometric model](https://zenodo.org/deposit/5907059)| [Simple geometric shapes model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/geometric_shapes/generate_model.ipynb)| -|[Simple Scientific model](https://zenodo.org/record/5907196)| [LeafSnap30 model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/LeafSnap/generate_model.ipynb)| + +| Models | Generation | +| :-------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Binary MNIST model](https://zenodo.org/record/5907177) | [Binary MNIST model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/MNIST/generate_model_binary.ipynb) | +| [Simple Geometric model](https://zenodo.org/deposit/5907059) | [Simple geometric shapes model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/geometric_shapes/generate_model.ipynb) | +| [Simple Scientific model](https://zenodo.org/record/5907196) | [LeafSnap30 model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/LeafSnap/generate_model.ipynb) | ### Text -|Models|Generation| -|:-----|:----| -|[Movie reviews model](https://zenodo.org/record/5910598)| [Stanford sentiment treebank model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/movie_reviews/generate_model.ipynb)| + +| Models | Generation | +| :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Movie reviews model](https://zenodo.org/record/5910598) | [Stanford sentiment treebank model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/movie_reviews/generate_model.ipynb) | ### Time series -|Models|Generation| -|:-----|:----| -| Coffee model | [Coffee model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/coffee/generate_model.ipynb)| + +| Models | Generation | +| :-------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Coffee model | [Coffee model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/coffee/generate_model.ipynb) | | [Season prediction model](https://zenodo.org/record/7543883) | [Season prediction model generation](https://github.com/dianna-ai/dianna-exploration/blob/main/example_data/model_generation/season_prediction/generate_model.ipynb) | **_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](./tutorials)). The DIANNA [tutorials](./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](https://dianna.readthedocs.io/en/latest/ROADMAP.html). -|Data \ XAI|[RISE](http://bmvc2018.org/contents/papers/1064.pdf)|[LIME](https://www.kdd.org/kdd2016/papers/files/rfp0573-ribeiroA.pdf)|[KernelSHAP](https://proceedings.neurips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf)| -|:-----|:---|:---|:---| -|Images|:white_check_mark:|:white_check_mark:|:white_check_mark:| -|Text|:white_check_mark:|:white_check_mark:|| -|Timeseries|:white_check_mark:|:white_check_mark:|| -|Embedding|planned|planned|planned| -|Tabular|planned|planned|planned| -|Graphs* |work in progress|work in progress| work in progress| - - +| Data \ XAI | [RISE](http://bmvc2018.org/contents/papers/1064.pdf) | [LIME](https://www.kdd.org/kdd2016/papers/files/rfp0573-ribeiroA.pdf) | [KernelSHAP](https://proceedings.neurips.cc/paper/2017/file/8a20a8621978632d76c43dfd28b67767-Paper.pdf) | +| :--------- | :------------------------------------------------ | :----------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | +| Images | ✅ | ✅ | ✅ | +| Text | ✅ | ✅ | | +| Timeseries | ✅ | ✅ | | +| Embedding | planned | planned | planned | +| Tabular | planned | planned | planned | +| Graphs* | work in progress | work in progress | work in progress | [LRP](https://journals.plos.org/plosone/article/file?id=10.1371/journal.pone.0130140&type=printable) and [PatternAttribution](https://arxiv.org/pdf/1705.05598.pdf) 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!** @@ -244,6 +297,7 @@ have a look at the [contribution guidelines](https://dianna.readthedocs.io/en/la See our [developer documentation](docs/developer_info.rst) for information on developer installation, running tests, generating documentation, versioning and making a release. ## How to cite us + [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5592606.svg)](https://zenodo.org/record/5592606) [![RSD](https://img.shields.io/badge/rsd-dianna-00a3e3.svg)](https://www.research-software.nl/software/dianna)