explainable-transformers 0.0.1
Explanation techniques for Transformer-based architectures
License: MIT

.. -*- mode: rst -*-

|pypi_version|_ |pypi_downloads|_

.. |pypi_version| image:: https://img.shields.io/pypi/v/explainable-transformers.svg
.. _pypi_version: https://pypi.python.org/pypi/explainable-transformers/

.. |pypi_downloads| image:: https://pepy.tech/badge/explainable-transformers/month
.. _pypi_downloads: https://pepy.tech/project/explainable-transformers

.. image:: artwork/cover.png
	:alt: Vision Transformers explanation


=====
explainable-transformers
=====

Explanation and interpretation techniques for Transformer-based architectures. 

-----------
Installation
-----------

Requirements:

* opencv-python
* numpy
* torch
* tqdm

.. code:: bash

    pip install explainable-transformers

--------------
Usage examples
--------------

Please, see **notebook/** for complete examples on how to create representations for the explanations.

For Vision Transformers, use the *VisionTransformerWrapper* passing a Pytorch model.

.. code:: python

    from transformers import ViTModel

    # import explanator module
    from explainable_transformers.image_explainer import VisionTransformerWrapper

    # define the last layer for classification
    class PreTrainedViT(nn.Module):
        def __init__(self, vit_model, d_model, classes):
            ...

        def forward(self, x):
            ...

            
    # load the pre-trained model
    pretrained_vit_model = ViTModel.from_pretrained('google/vit-base-patch16-224-in21k', 
                                                    add_pooling_layer=False, output_attentions=True)

    model = PreTrainedViT(pretrained_vit_model, hidden_size=768, output_dim=10)

    # create the ViT wrapper and register the layers
    vit_wrapper = VisionTransformerWrapper(model, device, num_attn_layers=12)
    vit_wrapper.register_hook()

    # explain a prediction using .generate_visualization(img)
    image = Image.open('images/dogbird.png')
    processed_image = transform(image)
    cat_exp, _ = vit_wrapper.generate_visualization(processed_image)



For Text Transformers, right now we need to know how the attention component is organized. 

.. code:: python

    # first the imports

    from transformers import BertTokenizer, BertForSequenceClassification

    from explainable_transformers.utils import *
    from explainable_transformers import NLPTransformerWrapper


    # for text, we provide the NLP wrapper

    """
    We access the attention component like following:

    - BERT or RoBERTa: '.encoder.layer.#.attention.self.dropout'
    - XLNet: '.layer.#.rel_attn.dropout'

    """
    nlp_wrapper = NLPTransformerWrapper(model, device, 12, 'bert', 'classifier', '.encoder.layer.#.attention.self.dropout')
    nlp_wrapper.register_hook()

    explanation = nlp_wrapper.generate_explanation(input_ids, attention_mask, class_index=true_class, start_layer=NUM_LAYERS-1)
    explanation = explanation.detach().cpu().numpy()




--------
Citation
--------

Please, use the respective authors if you use any of the techniques.

Currently, we have the **Pytorch** implementation of the following approaches:

*Transformer Interpretability Beyond Attention Visualization* (`paper <https://arxiv.org/abs/2012.09838>`_):

1. Transformers: BERT, RoBERTa, and XLNet

2. Vision Transformers

.. code:: bibtex

    @InProceedings{Chefer_2021_CVPR,
        author    = {Chefer, Hila and Gur, Shir and Wolf, Lior},
        title     = {Transformer Interpretability Beyond Attention Visualization},
        booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
        month     = {June},
        year      = {2021},
        pages     = {782-791}
    }


-------
License
-------

*explainable-transformers* follows the 3-clause BSD license and it is based on other open-source implementations: `Chefer's <https://github.com/hila-chefer/Transformer-Explainability>`_.

We also use `nlp_understanding <https://github.com/ENSAE-CKW/nlp_understanding>`_ for generating the heatmap.

E-mail me (wilson_jr at outlook dot com) if you like to contribute.


......