Getting Started

tdhook is a package for explaining torch deep neural networks based on tensordict and torch hooks. It is designed to be easy to use and to work with the most common interpretability methods.

Installation

To get started with tdhook, install it with pip.

pip install tdhook

Basic Example

Most methods should work with minimal configuration. Here’s a basic example of running Integrated Gradients on a VGG16 model:

import torch
from tensordict import TensorDict
from tdhook.attribution import IntegratedGradients

# Define attribution target (e.g., zebra class = 340)
def init_attr_targets(targets, _):
    zebra_logit = targets["output"][..., 340]
    return TensorDict(out=zebra_logit, batch_size=targets.batch_size)

# Compute attribution
with IntegratedGradients(init_attr_targets=init_attr_targets).prepare(model) as hooked_model:
    td = TensorDict({
        "input": image_tensor,
        ("baseline", "input"): torch.zeros_like(image_tensor)  # required for integrated gradients
    }).unsqueeze(0)
    td = hooked_model(td)  # Access attribution with td.get(("attr", "input"))

For more detailed examples, see the Methods page.