Package: dianna
Deep Insight And Neural Network AnalysisDIANNA 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 theOpen Neural Network Exchange (ONNX)format.After studying the vast XAI landscape we have made choices in the parts of theXAI Taxonomyon 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 expertsImplements well-known XAI methods (LIME, RISE and Kernal SHAP) chosen by systematic and objective evaluation criteriaSupports 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 images, text and time series data modalities. Tabular data and even embeddings support is planned.Comes with simple intuitive image and text benchmarksEasily extendable to other XAI methodsFor more information on the unique strengths of DIANNA with comparison to other tools, please see thecontext landscape.InstallationDIANNA can be installed from PyPI usingpipon any of the supported Python versions (see badge):python3 -m pip install diannaTo install the most recent development version directly from the GitHub repository run:python3 -m pip install git+https://github.com/dianna-ai/dianna.gitIf you get an error related to OpenMP when importing dianna, have a look atthis issuefor possible workarounds.Pre-requisites only for Macbook Pro with M1 Pro chip usersTo install TensorFlow you can follow thistutorial.To install TensorFlow Addons you can follow thesesteps. For further reading see thisissue. Note that this temporary solution works only for macOS versions >= 12.0. Note that this step may have changed already, seehttps://github.com/dianna-ai/dianna/issues/245.Before installing DIANNA, commenttensorflowrequirement insetup.cfgfile (tensorflow package for M1 is calledtensorflow-macos).Getting startedYou need:your trained ONNX model (convert my pytorch/tensorflow/keras/scikit-learn model to ONNX)1 data item to be explainedYou get:a relevance map overlayed over the data itemIn the library's documentation, the general usage is explained inHow to use DIANNADemo movieText example:model_path='your_model.onnx'# model trained on texttext='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 imagesimage=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)Time-series example:model_path='your_model.onnx'# model trained on imagestimeseries_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?class_names=[class_a,class_b]# String representation of the different classes of interestlabels=np.argsort(class_names)# Numerical representation of the different classes of interest for the modelRun using the XAI method of your choice, for example LIME with the following additional arguments: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 thetutorialTabular example:model_path='your_model.onnx'# model trained on tabular datatabular_instance=pd.read_csv('your_data_instance.csv')Run using the XAI method of your choice. Note that you need to specify the mode, either regression or classification. This case, for instance a regression task using KernelSHAP with the following additional arguments:explanation=dianna.explain_tabular(run_model,input_tabular=data_instance,method='kernelshap',mode='regression',training_data=X_train,training_data_kmeans=5,feature_names=input_features.columns)plot_tabular(explanation,X_test.columns,num_features=10)# display 10 most salient featuresDashboardExplore your trained model explained using the DIANNA dashboard.Click herefor more information.DatasetsDIANNA 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.ImagesDatasetDescriptionExamplesGenerationBinary MNISTGreyscale images of the digits "1" and "0" - a 2-class subset from the famousMNIST datasetfor handwritten digit classification.Binary MNIST dataset generationSimple 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 generationSimple 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 generationTextDatasetDescriptionExamplesGenerationStanford sentiment treebankDataset for predicting the sentiment, positive or negative, of movie reviews.This movie was actually neither that funny, nor super witty.Sentiment treebankTime seriesDatasetDescriptionExamplesGenerationCoffee datasetFood spectographs time series dataset for a two class problem to distinguish between Robusta and Arabica coffee beans.data sourceWeather datasetThe light version of the weather prediciton dataset, which contains daily observations (89 features) for 11 European locations through the years 2000 to 2010.data sourceTabularDatasetDescriptionExamplesGenerationPengiun datasetPalmer Archipelago (Antarctica) penguin dataset is a great intro dataset for data exploration & visualization similar to the famous Iris dataset.data sourceWeather datasetThe light version of the weather prediciton dataset, which contains daily observations (89 features) for 11 European locations through the years 2000 to 2010.data sourceONNX modelsWe 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-intorch.onnx.exportfunction to convert pytorch models to onnx, or call the built-into_onnxfunction on yourLightningModuleto export pytorch-lightning models to onnx.tensorflow- use thetf2onnxpackage to convert tensorflow models to onnx.keras- same as the conversion from tensorflow to onnx, thetf2onnxpackage also supports keras.scikit-learn- use theskl2onnxpackage to scikit-learn models to onnx.More converters with examples and tutorials can be found on theONNX tutorial page.And here are links to notebooks showing how we created our models on the benchmark datasets:ImagesModelsGenerationBinary MNIST modelBinary MNIST model generationSimple Geometric modelSimple geometric shapes model generationSimple Scientific modelLeafSnap30 model generationTextModelsGenerationMovie reviews modelStanford sentiment treebank model generationTime seriesModelsGenerationCoffee modelCoffee model generationSeason prediction modelSeason prediction model generationTabularModelsGenerationPenguin model    (classification)Penguin model generationSunshine hours prediction model (regression)Sunshine hours prediction model generationWe envision the birth of the ONNX Scientific models zoo soon...TutorialsDIANNA 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 seetutorials). The DIANNAtutorialscover 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 theROADMAP.Data \ XAIRISELIMEKernelSHAPImages✅✅✅Text✅✅Timeseries✅✅Tabularplanned✅plannedEmbeddingplannedplannedplannedGraphs*work in progresswork in progresswork in progressLRPandPatternAttributionalso 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 documentationFor detailed information on using specific DIANNA functions, please visit thedocumentation page hosted at Readthedocs.ContributingIf you want to contribute to the development of DIANNA,
have a look at thecontribution guidelines.
See ourdeveloper documentationfor information on developer installation, running tests, generating documentation, versioning and making a release.How to cite usIf you use this package for your scientific work, please consider citing directly the software as:Ranguelova, E., Bos, P., Liu, Y., Meijer, C., Oostrum, L., Crocioni, G., Ootes, L., Chandramouli, P., Jansen, A., Smeets, S. (2023). dianna (*[VERSION YOU USED]*). Zenodo. https://zenodo.org/record/5592606or the JOSS paper as:Ranguelova et al., (2022). DIANNA: Deep Insight And Neural Network Analysis. Journal of Open Source Software, 7(80), 4493, https://doi.org/10.21105/joss.04493See also theZenodo pageor theJOSS pagefor exporting the software citation to BibTteX and other formats.CreditsThis package was created withCookiecutterand theNLeSC/python-template.