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 over a dozen interpretation methods. Unlike methods borrowed from vision and NLP, the ones implemented natively here account for the temporal dependency between neighbouring time steps and score the time and feature dimensions jointly rather than separately.

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

Why tslens?

Among these libraries, tslens is the only one with documented, tested integrations spanning recent TSlib architectures and LLM-backed time-series models, while also supporting classification, regression, individual forecast horizons, and multivariate time–feature attribution. A dash means no first-class documented support; custom integration may still be possible. See the full comparison.

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

Please cite the following if you use this work, also the related paper arXiv:2412.04532.

@software{islam_2026_22088943,
  author       = {Islam, Md Khairul},
  title        = {tslens: A PyTorch Framework for Interpreting Time Series Deep Learning Models},
  month        = aug,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.22088943},
  url          = {https://doi.org/10.5281/zenodo.22088943}
}