Sparsity, Explainability, and Communication.
This is the repository for The Explanation Game: Towards Prediction Explainability through Sparse Communication, accepted at BlackBoxNLP 2020.
First, create a virtualenv using your favorite tool, and then install all dependencies using:
pip3 install -r requirements.txtFinally, install it as a library with:
python3 setup.py installYou can see a complete help message by running:
python3 -m spec --help-
Download the datasets with the script
download_datasets.sh(1.6G). Yelp dataset should be downloaded separately (6G). -
Then run the script
bash generate_dataset_partitions.shto create train/dev/test partitions for AgNews, IMDB and Yelp. -
If you want to use GloVe embeddings (as in our paper), you have two options:
a) Use the script
download_glove_embeddings.shto download all embedding vectors. And, if you want to use only the embeddings for a particular corpus, i.e., restrict the embeddings vocabulary to the corpus vocabulary for all downloaded corpus, use the scriptscripts/reduce_embeddings_model_for_all_corpus.sh.b) Download the already restricted-to-vocab glove embeddings zipped file (1G), unzip it, and put each pickled file in the
embs/glove/dir.
Here is how your data folder will be organized:
data/
├── corpus
│ ├── agnews
│ ├── imdb
│ ├── snli
│ └── sst
│ └── yelp
├── embs
│ └── glove
Basic usage:
python3 -m spec {train,predict,communicate} [OPTIONS]You can use the command train to train a classifier.
Alternatively, if you are interested only in the communication part,
you can download trained classifiers here:
- softmax-based models (743M)
- entmax-based models (743M)
- sparsemax-based models (743M)
After downloading and extracting, put them in data/saved-models/.
Or download all of them with the script download_trained_models.sh.
For training the classifier-explainer-layperson setup, you can use the command communicate
and set the path to load the trained classifier via the --load argument. For example, see experiments/train_sst.sh and experiments/communicate_sst.sh.
Statistics will be displayed during training. Here is a snippet of what you'll see:
Loss (val / epoch) | Prec. Rec. F1 (val / epoch) | ACC (val / epoch) | MCC (val / epoch) | TVD (val / epoch) | ACC L | ACC C |
----------------------+----------------------------------------+----------------------+----------------------+----------------------+--------+--------+
0.6495 (0.6495 / 1) | 0.8005 0.7562 0.7482 (0.7482 / 1) | 0.7579 (0.7579 / 1) | 0.5550 (0.5550 / 1) | 0.4105 (0.4105 / 1) | 0.7350 | 0.9504 |
The accuracy of the communication (ACC) represents the CSR proposed in our paper, ACC L is the accuracy of the layperson model, and ACC C is the accuracy of the classifier.
Take a look in the experiments folder for more examples.
(we'll provide a download link soon!)
For now, enter in contact if you want access to 200 hundred annotated examples of IMDB and SNLI for each explainer in Table 4. Check the supplemental material in our paper for more information about the annotation process.
Machine Translation experiments were carried in possum-nmt, DeepSPIN's private version of joey-nmt created by Ben Peters. Here is the config file that I used to train and save (manually) gradients and attention probabilities: config_iwslt17_sparsemax.yaml. Let me know if you want access to this data (+20GB).
@inproceedings{treviso-martins-2020-explanation,
title = "The Explanation Game: Towards Prediction Explainability through Sparse Communication",
author = "Treviso, Marcos and
Martins, Andr{\'e} F. T.",
booktitle = "Proceedings of the Third BlackboxNLP Workshop on Analyzing and Interpreting Neural Networks for NLP",
month = nov,
year = "2020",
address = "Online",
publisher = "Association for Computational Linguistics",
url = "https://www.aclweb.org/anthology/2020.blackboxnlp-1.10",
pages = "107--118",
}
MIT.