# feedzai/timeshap architecture

> Architecture diagram of the GitHub repository feedzai/timeshap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/feedzai/timeshap
- Repository: https://github.com/feedzai/timeshap

## Overview

TimeSHAP is a model-agnostic explainer for recurrent sequence models. A user supplies sequences, a background instance, and a callable model interface; local workflows produce pruning and event, feature, or cell attributions, while global workflows aggregate explanations across instances. The shared KernelSHAP-based engine supports these explanation stages, and plotting/report modules present their results. PyTorch and TensorFlow wrappers adapt model inputs and predictions. Edges reflect README documentation and SOURCE INDEX references; unsampled implementations are represented only where their capabilities or connections are documented.

Main entry points: [`src/timeshap/explainer/pruning.py`](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/pruning.py) (Pruning), [`src/timeshap/explainer/event_level.py`](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/event_level.py) (Event attribution), [`src/timeshap/explainer/local_methods.py`](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/local_methods.py) (Local report), [`src/timeshap/explainer/global_methods.py`](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/global_methods.py) (Global report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Model interfaces"]
  node_torch["PyTorch wrapper<br/>[torch_wrappers.py]"]
  node_tf["TensorFlow wrapper<br/>[tf_wrappers.py]"]
  node_basewrap["Wrapper base<br/>[base_wrapper.py]"]
end

subgraph group_engine["Attribution engine"]
  node_kernel["TimeSHAP kernel<br/>[timeshap_kernel.py]"]
end

subgraph group_workflows["Explanation workflows"]
  node_pruning["Pruning<br/>[pruning.py]"]
  node_event["Event attribution<br/>[event_level.py]"]
  node_feature["Feature attribution<br/>[feature_level.py]"]
  node_cell["Cell attribution<br/>[cell_level.py]"]
  node_local["Local report<br/>[local_methods.py]"]
  node_global["Global report<br/>[global_methods.py]"]
end

subgraph group_presentation["Reports and plots"]
  node_plotprune["Pruning plots<br/>[pruning.py]"]
  node_plotevent["Event plots<br/>[event_level.py]"]
  node_plotfeature["Feature plots<br/>[feature_level.py]"]
  node_plotcell["Cell plots<br/>[cell_level.py]"]
  node_plotlocal["Local report plots<br/>[local_report.py]"]
  node_plotglobal["Global report plots<br/>[global_report.py]"]
end

subgraph group_support["Shared support"]
  node_legacy["SHAP compatibility<br/>[timeshap_legacy.py]"]
  node_plotutils["Plot utilities<br/>[utils.py]"]
  node_utils["Data utilities<br/>[utils.py]"]
  node_compat["Model compatibility<br/>[compatibility.py]"]
end

node_user(("Analyst"))
node_model["Sequence model"]

node_user -->|"requests local"| node_local
node_user -->|"requests global"| node_global
node_torch -->|"extends"| node_basewrap
node_torch -->|"predicts with"| node_model
node_tf -.->|"adapts callable"| node_model
node_user -->|"provides callable"| node_model
node_pruning -->|"uses"| node_kernel
node_event -->|"uses"| node_kernel
node_feature -->|"uses"| node_kernel
node_cell -->|"uses"| node_kernel
node_kernel -->|"converts data"| node_legacy
node_local -->|"calculates"| node_pruning
node_local -->|"calculates"| node_event
node_local -->|"calculates"| node_feature
node_local -->|"plots report"| node_plotlocal
node_global -->|"aggregates"| node_pruning
node_global -->|"aggregates"| node_event
node_global -->|"aggregates"| node_feature
node_global -->|"plots report"| node_plotglobal
node_pruning -->|"results plotted by"| node_plotprune
node_event -->|"results plotted by"| node_plotevent
node_feature -->|"results plotted by"| node_plotfeature
node_cell -->|"results plotted by"| node_plotcell
node_plotevent -->|"uses"| node_plotutils
node_plotfeature -->|"uses"| node_plotutils
node_plotlocal -->|"renders"| node_pruning
node_plotglobal -->|"renders"| node_event
node_torch -->|"uses compatibility"| node_compat
node_pruning -->|"uses data helpers"| node_utils
node_event -->|"uses data helpers"| node_utils
node_feature -->|"uses data helpers"| node_utils

click node_torch "https://github.com/feedzai/timeshap/blob/main/src/timeshap/wrappers/torch_wrappers.py"
click node_tf "https://github.com/feedzai/timeshap/blob/main/src/timeshap/wrappers/tf_wrappers.py"
click node_basewrap "https://github.com/feedzai/timeshap/blob/main/src/timeshap/wrappers/base_wrapper.py"
click node_kernel "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/kernel/timeshap_kernel.py"
click node_legacy "https://github.com/feedzai/timeshap/blob/main/src/timeshap/utils/timeshap_legacy.py"
click node_pruning "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/pruning.py"
click node_event "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/event_level.py"
click node_feature "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/feature_level.py"
click node_cell "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/cell_level.py"
click node_local "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/local_methods.py"
click node_global "https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/global_methods.py"
click node_plotprune "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/pruning.py"
click node_plotevent "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/event_level.py"
click node_plotfeature "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/feature_level.py"
click node_plotcell "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/cell_level.py"
click node_plotlocal "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/local_report.py"
click node_plotglobal "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/global_report.py"
click node_plotutils "https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/utils.py"
click node_utils "https://github.com/feedzai/timeshap/blob/main/src/timeshap/utils/utils.py"
click node_compat "https://github.com/feedzai/timeshap/blob/main/src/timeshap/utils/compatibility.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_torch,node_tf,node_basewrap toneBlue
class node_kernel toneAmber
class node_pruning,node_event,node_feature,node_cell,node_local,node_global toneMint
class node_plotprune,node_plotevent,node_plotfeature,node_plotcell,node_plotlocal,node_plotglobal toneRose
class node_legacy,node_plotutils,node_utils,node_compat,node_user,node_model toneIndigo
```

## Components

### Model interfaces

- [PyTorch wrapper](https://github.com/feedzai/timeshap/blob/main/src/timeshap/wrappers/torch_wrappers.py): `src/timeshap/wrappers/torch_wrappers.py`
- [TensorFlow wrapper](https://github.com/feedzai/timeshap/blob/main/src/timeshap/wrappers/tf_wrappers.py): `src/timeshap/wrappers/tf_wrappers.py`
- [Wrapper base](https://github.com/feedzai/timeshap/blob/main/src/timeshap/wrappers/base_wrapper.py): `src/timeshap/wrappers/base_wrapper.py`

### Attribution engine

- [TimeSHAP kernel](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/kernel/timeshap_kernel.py): `src/timeshap/explainer/kernel/timeshap_kernel.py`

### Explanation workflows

- [Pruning](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/pruning.py): `src/timeshap/explainer/pruning.py`
- [Event attribution](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/event_level.py): `src/timeshap/explainer/event_level.py`
- [Feature attribution](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/feature_level.py): `src/timeshap/explainer/feature_level.py`
- [Cell attribution](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/cell_level.py): `src/timeshap/explainer/cell_level.py`
- [Local report](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/local_methods.py): `src/timeshap/explainer/local_methods.py`
- [Global report](https://github.com/feedzai/timeshap/blob/main/src/timeshap/explainer/global_methods.py): `src/timeshap/explainer/global_methods.py`

### Reports and plots

- [Pruning plots](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/pruning.py): `src/timeshap/plot/pruning.py`
- [Event plots](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/event_level.py): `src/timeshap/plot/event_level.py`
- [Feature plots](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/feature_level.py): `src/timeshap/plot/feature_level.py`
- [Cell plots](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/cell_level.py): `src/timeshap/plot/cell_level.py`
- [Local report plots](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/local_report.py): `src/timeshap/plot/local_report.py`
- [Global report plots](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/global_report.py): `src/timeshap/plot/global_report.py`

### Shared support

- [SHAP compatibility](https://github.com/feedzai/timeshap/blob/main/src/timeshap/utils/timeshap_legacy.py): `src/timeshap/utils/timeshap_legacy.py`
- [Plot utilities](https://github.com/feedzai/timeshap/blob/main/src/timeshap/plot/utils.py): `src/timeshap/plot/utils.py`
- [Data utilities](https://github.com/feedzai/timeshap/blob/main/src/timeshap/utils/utils.py): `src/timeshap/utils/utils.py`
- [Model compatibility](https://github.com/feedzai/timeshap/blob/main/src/timeshap/utils/compatibility.py): `src/timeshap/utils/compatibility.py`

### Other components

- **Analyst**
- **Sequence model**

## Connections

- Analyst → Local report: requests local (evidence: `README.md`)
- Analyst → Global report: requests global (evidence: `README.md`)
- PyTorch wrapper → Wrapper base: extends (evidence: `src/timeshap/wrappers/base_wrapper.py`)
- PyTorch wrapper → Sequence model: predicts with (evidence: `src/timeshap/wrappers/torch_wrappers.py`)
- TensorFlow wrapper → Sequence model: adapts callable (evidence: `README.md`)
- Analyst → Sequence model: provides callable (evidence: `README.md`)
- Pruning → TimeSHAP kernel: uses (evidence: `src/timeshap/explainer/pruning.py`)
- Event attribution → TimeSHAP kernel: uses (evidence: `src/timeshap/explainer/event_level.py`)
- Feature attribution → TimeSHAP kernel: uses (evidence: `src/timeshap/explainer/feature_level.py`)
- Cell attribution → TimeSHAP kernel: uses (evidence: `src/timeshap/explainer/cell_level.py`)
- TimeSHAP kernel → SHAP compatibility: converts data (evidence: `src/timeshap/explainer/kernel/timeshap_kernel.py`)
- Local report → Pruning: calculates (evidence: `src/timeshap/explainer/local_methods.py`)
- Local report → Event attribution: calculates (evidence: `src/timeshap/explainer/local_methods.py`)
- Local report → Feature attribution: calculates (evidence: `src/timeshap/explainer/local_methods.py`)
- Local report → Local report plots: plots report (evidence: `src/timeshap/explainer/local_methods.py`)
- Global report → Pruning: aggregates (evidence: `src/timeshap/explainer/global_methods.py`)
- Global report → Event attribution: aggregates (evidence: `src/timeshap/explainer/global_methods.py`)
- Global report → Feature attribution: aggregates (evidence: `src/timeshap/explainer/global_methods.py`)
- Global report → Global report plots: plots report (evidence: `src/timeshap/explainer/global_methods.py`)
- Pruning → Pruning plots: results plotted by (evidence: `README.md`)
- Event attribution → Event plots: results plotted by (evidence: `README.md`)
- Feature attribution → Feature plots: results plotted by (evidence: `README.md`)
- Cell attribution → Cell plots: results plotted by (evidence: `README.md`)
- Event plots → Plot utilities: uses (evidence: `src/timeshap/plot/event_level.py`)
- Feature plots → Plot utilities: uses (evidence: `src/timeshap/plot/feature_level.py`)
- Local report plots → Pruning: renders (evidence: `src/timeshap/plot/local_report.py`)
- Global report plots → Event attribution: renders (evidence: `src/timeshap/plot/global_report.py`)
- PyTorch wrapper → Model compatibility: uses compatibility (evidence: `src/timeshap/wrappers/__init__.py`)
- Pruning → Data utilities: uses data helpers (evidence: `src/timeshap/explainer/pruning.py`)
- Event attribution → Data utilities: uses data helpers (evidence: `src/timeshap/explainer/event_level.py`)
- Feature attribution → Data utilities: uses data helpers (evidence: `src/timeshap/explainer/feature_level.py`)
