tslens

Which time steps and which features did your time series model actually use?

tslens is a Captum-compatible interpretability toolkit for deep time series models, giving you a consistent PyTorch interface to WinTSR and other established attribution methods. WinTSR (Windowed Temporal Saliency Rescaling), the native flagship method, accounts for the temporal dependency between neighbouring time steps and scores the time and feature dimensions jointly rather than separately — unlike attribution methods borrowed from vision and NLP.

Paper: arXiv:2412.04532 · Code: github.com/khairulislam/tslens

Install

pip install tslens

Use

Works with any PyTorch model that maps (batch, seq_len, n_features) to predictions. No training framework to adopt, no dataset format to conform to.

import torch
from tslens import WinTSR

inputs = torch.randn(16, 96, 7)          # (batch, seq_len, n_features)
attr = WinTSR(model).attribute(
    inputs,
    baselines=torch.zeros_like(inputs),
    threshold=0.5,                        # skip the least relevant time steps
)

attr.shape  # (16, n_output, 96, 7) -- (batch, n_output, seq_len, n_features)

Plot it as a heatmap over (seq_len, n_features) and you can read off what the model used.

Options that matter

Multi-input models

Pass a tuple, get a tuple back. This is how you explain a TSlib model (DLinear, iTransformer, TimesNet, ...) — its four forward arguments split into two attributed inputs and two context tensors, with no wrapper class:

attr_enc, attr_mark = WinTSR(model).attribute(
    inputs=(x_enc, x_mark_enc),
    baselines=(torch.zeros_like(x_enc), torch.zeros_like(x_mark_enc)),
    additional_forward_args=(x_dec, x_mark_dec),
)

More recipes

The integration cookbook has copy-paste snippets for dict/tuple model outputs, classification models, baseline choice, explaining a single forecast horizon, speed tuning, and troubleshooting. Two runnable notebooks: quickstart and TSlib models.

Requirements

torch, numpy, captum, and time-interpret.

Citation

@article{islam2024wintsr,
  title={WinTSR: A Windowed Temporal Saliency Rescaling Method for Interpreting Time Series Deep Learning Models},
  author={Islam, Md Khairul and Fox, Judy},
  journal={arXiv preprint arXiv:2412.04532},
  year={2024}
}