Transformers-interpret

Zero Shot Classification Explainer Improvements (49)
- Changes the default behavior of how the zero shot classification explainer works by calculating attributions for each
label by default and displaying the attributions for every label in the visualization. This required some major reorganization of the former implementation.

Memory Optimizations (54)
- Every explainer instance can now take an optional parameter `internal_batch_size`.
- This helps prevent issues where the explainer would cause OOM errors because all the steps (50 by default) used to calculate the attributions are batched together.
- For large models like Longformer etc it is recommended to select very low values (1 or 2) for `internal_batch_size` (51).
- This addition has been extremely helpful in stabilizing the performance of the streamlit [demo app](https://share.streamlit.io/cdpierse/transformers-interpret-streamlit/main/app.py) which prior to this update was crashing frequently. Lowering internal_batch_size should greatly reduce memory overhead in situations where more than a single batch of gradients would cause OOM.
Internal Batch Size Example
python
cls_explainer('A very short 100 character text here!', internal_batch_size=1)


Custom Steps For Attribution (54)
- Explainer instances can now also accept another optional parameter `n_steps`. Default value for `n_steps` in Captum is 50.
- `n_steps` controls the number of steps used to calculate the approximate attributions from the baseline inputs to the true inputs.
- Higher values for `n_steps` should result in less noisy approximations than lower values but longer calculation times.
- If `n_steps` is set to a particularly high value it is highly recommended to set `internal_batch_size` to a low value to prevent OOM issues.

N Steps Example
python
cls_explainer('A very short 100 character text here!', n_steps=100)

Zero-Shot Classification Explainer (19, 40)
This release introduces a new explainer `ZeroShotClassificationExplainer` that allows for word attributions to be calculated in a zero shot manner with the appropriate NLI type models. To achieve this we implement zero shot exactly how the hugging face team did based off the following [paper](https://arxiv.org/abs/1909.00161). A list of compatible models with this explainer can be found at the transformers [model hub](https://huggingface.co/models?pipeline_tag=zero-shot-classification).

Below is an example of instantiating and calling the `ZeroShotClassificationExplainer`:

python
from transformers import AutoModelForSequenceClassification, AutoTokenizer
from transformers_interpret import ZeroShotClassificationExplainer

tokenizer = AutoTokenizer.from_pretrained("facebook/bart-large-mnli")

model = AutoModelForSequenceClassification.from_pretrained("facebook/bart-large-mnli")


zero_shot_explainer = ZeroShotClassificationExplainer(model, tokenizer)


word_attributions = zero_shot_explainer(
"Today apple released the new Macbook showing off a range of new features found in the proprietary silicon chip computer. ",
labels = ["finance", "technology", "sports"], any labels you want can be passed, even a list with one label
)



Which will return the following list of tuples:

python
>>> word_attributions

Changes to explainer constructor

In previous versions the constructor for explainers allowed for text to passed along with the model and tokenizer, text could also be passed to the explainer instance and would replace the text passed in the constructor. This behavior was confusing and also didn't work with integrating into future explainers. This version changes that behavior so that only the model and tokenizer are passed to the constructor and text is always passed to the instance.

Old
python
cls_explainer = SequenceClassificationExplainer(
"I love you, I like you",
model,
tokenizer)
cls_explainer("I hate you, I loathe you") overwrites intial text

New
python
cls_explainer = SequenceClassificationExplainer(
model,
tokenizer)
cls_explainer("I love you, I like you")


Question Answering Explainer (Experimental release)

This release adds an initial implementation of an explainer for question-answering models from the Huggingface library called the `QuestionAnsweringExplainer`. This explainer is still somewhat experimental and has not been tested with a wide range of models and architectures.

I'm still figuring some things out such as the default embeddings to explain attributions for. In some cases I can get the average attributions for three embedding types combined (word, position, token type) while in others this is not possible so I currently default to word attributions. While this was fine for the classification explainer, position ids and token type ids play a big role in calculating attributions for question-answering models.

How to create a QA explainer
python
from transformers import AutoModelForQuestionAnswering, AutoTokenizer
from transformers_interpret import QuestionAnsweringExplainer

tokenizer = AutoTokenizer.from_pretrained("bert-large-uncased-whole-word-masking-finetuned-squad")
model = AutoModelForQuestionAnswering.from_pretrained("bert-large-uncased-whole-word-masking-finetuned-squad")

qa_explainer = QuestionAnsweringExplainer(
model,
tokenizer,
)

Getting word attributions
python

context = """
In Artificial Intelligence and machine learning, Natural Language Processing relates to the usage of machines to process and understand human language.
Many researchers currently work in this space.
"""

word_attributions = qa_explainer(
"What is natural language processing ?",
context,
)


`word_attributions` are a dict with two keys `start` and `end` the values for each key are a list of tuples. The values in `start` are the word attributions for the predicted start position from the `context` and the values in `end` are for the predicted end position.

We can get the text span for the predicted answer with

python
>>> qa_explainer.predicted_answer
'usage of machines to process and understand human language'


Like the classification explainer attributions can be visualized with

python
qa_explainer.visualize("bert_qa_viz.html")


This will create a table of two rows, the first for start position attributions and the second for end position attributions.

**Please report any bugs or quirks you find with this new explainer. Thanks**

Support Attributions for Multiple Embedding Types

- `SequenceClassificationExplainer` now has support for word attributions for both `word_embeddings` and `position_embeddings` for model's where `position_ids` are part of a model's forward method. Embeddings for attribution can be set with the class's call method.
python
from transformers import AutoTokenizer, AutoModelForSequenceClassification
tokenizer = AutoTokenizer.from_pretrained("aychang/roberta-base-imdb")
model = AutoModelForSequenceClassification.from_pretrained("aychang/roberta-base-imdb")

Word Embedding Attributions
python
from transformers_interpret import SequenceClassificationExplainer
cls_explainer = SequenceClassificationExplainer(
"This was a really good film I enjoyed it a lot",
model,
tokenizer)
attributions = cls_explainer(embedding_type=0) 0 = word

>>> attributions.word_attributions

- Classification explainer model's now use `model.get_input_embeddings()` by default. This is equivalent to calculating attributions exclusively w.r.t to word embeddings. This makes attribution calculation much more streamlined for many more models and will greatly improve compatibility with different architectures. (21)
- `SequenceClassificationExplainer`'s `visualize` method now returns the `HTML` object by default. 99c6db7013969f1e7d78871fd08c430e131f301f

- Add fixes for GPU support.
- `word_attributions` are now calculated using decoded input_ids rather than original input text. This is due to certain encoding methods like Byte-Pair-Encoding (BPE) breaking words into byte pairs. Captum's attributions are on byte pair level not word level. Rather than averaging the byte pairs back into the original word I am choosing to just return byte pairs in the list.