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 18, 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 18, 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-0.1.1.tar.gz (31.5 kB view details)

Uploaded Source

Built Distribution

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

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

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for tslens-0.1.1.tar.gz
Algorithm Hash digest
SHA256 b32aefa621de001c2a0af360d877cacfdf46ad891c9f52f54058739721c58024
MD5 146a2bc1b34700eafdd7d341475a32a5
BLAKE2b-256 27bdcdb9a01a0fb17457cddc8aeeca0b0088865228793cd189efbcc26bc6647d

See more details on using hashes here.

Provenance

The following attestation bundles were made for tslens-0.1.1.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-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: tslens-0.1.1-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-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 48c9ca08df07a4d70964b3c8914415947e8d36d65663529aef2417a0a28592ed
MD5 bf7ea32d0c8f7a2045fcbb8757db441c
BLAKE2b-256 32d398c80d82900faaec0c000c817cdcd9870a48b577b7bf32e1ac5b87877518

See more details on using hashes here.

Provenance

The following attestation bundles were made for tslens-0.1.1-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

1.0.0

2 files

This release

0.1.1 This release

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