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?

Capability tslens Captum Time Interpret TSInterpret
Time-series-native attribution ✓ — ✓ ✓
Classification and regression/forecasting workflows ✓ Generic Method-dependent Classification-focused
Individual forecast-horizon explanations ✓ Manual Manual —
Modern deep forecaster integrations ✓ — — —
Tested LLM-backed time-series models ✓ — — —

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

Argument Effect
threshold Quantile of time-relevance below which steps are skipped in stage two. Higher is faster and sparser; 0.0 keeps every step.
sliding_window_shapes Window over (time, features). Defaults to (1, 1). Widen the first entry to attribute over multi-step windows.
baselines Replacement values for occluded regions. Defaults to zeros; tslens.get_baseline(inputs, "normal") gives other options.
unflatten True (default) returns (batch, n_output, seq_len, n_features). False returns the flat (batch * n_output, ...) layout used internally.
legacy_normalize Constructor flag. Restores the exact normalization used to produce the published numbers — see below.

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}
}

Project links

Data verified by PyPI on Aug 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for khairulislamtanim from gravatar.com khairulislamtanim

Credits

Author: Md Khairul Islam

GitHub Statistics

Data verified by PyPI on Aug 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.9

Provides Extra

dev docs

Tags

time-series interpretability explainable-ai xai saliency attribution captum pytorch forecasting foundation-models deep-learning

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tslens-1.0.0.tar.gz (31.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

tslens-1.0.0-py3-none-any.whl (24.1 kB view details)

Uploaded Python 3

File details

Details for the file tslens-1.0.0.tar.gz.

File metadata

  • Download URL: tslens-1.0.0.tar.gz
  • Upload date:
  • Size: 31.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tslens-1.0.0.tar.gz
Algorithm Hash digest
SHA256 69eacc79f9cad5a885e409438f9c12f7d5e8e9cc9c2d4da42f268d77b7bc9bea
MD5 0e668a4a3c13eabe26309ab9a9108e7e
BLAKE2b-256 930dba18e4ca6aea43bf5b460c365bc72aa1270147861fae962a072e6a2cbd00

See more details on using hashes here.

Provenance

The following attestation bundles were made for tslens-1.0.0.tar.gz:

Publisher: publish.yml on khairulislam/tslens

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tslens-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: tslens-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 24.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tslens-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7dc5f32d47c6076cd794970521fb07380b3a2935f21a9b056cc73310f349da26
MD5 3b8f0f4cb83049b4fdd8a3dd44029202
BLAKE2b-256 4ff9ac60d6db5a24d36ad977682e1662c8b1603dc9b819429c9e3366eaeb3c03

See more details on using hashes here.

Provenance

The following attestation bundles were made for tslens-1.0.0-py3-none-any.whl:

Publisher: publish.yml on khairulislam/tslens

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.0.1

2 files

This release

1.0.0 This release

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page