tslens

A PyTorch framework for interpreting time-series deep learning models

tslens is a Captum-compatible interpretability toolkit for PyTorch time-series models. It tells you which time steps and features drove a prediction. Over a dozen interpretation methods sit behind one consistent interface, some implemented natively here to account for dependencies between neighbouring time steps, others wired in from Captum and Time Interpret.

Get started Open in Colab · Read the paper

What you get

• Time-aware explanations

  Preserve relationships between neighbouring observations instead of treating every input position independently.

• Joint time–feature attribution

  Locate the specific regions of an input window that mattered for a prediction.

• Flexible model integration

  Explain single- or multi-input PyTorch callables without adopting a training framework or dataset format.

• A consistent comparison surface

  Compare native time-aware methods against established ones from Captum and Time Interpret without changing your call site.

Why tslens instead of another interpretability library?

General-purpose explainability libraries treat a time series as another input tensor, while existing time-series packages are documented primarily around classifier or compact benchmark models. tslens connects a broad attribution API to modern time-series practice: multi-horizon and multivariate outputs, recent deep forecasting architectures, and LLM-backed time-series foundation models.

Capability	tslens	Captum	Time Interpret	TSInterpret
Methods designed for temporal dependencies	✓	—	✓	✓
Classification and regression/forecasting workflows	✓	Generic outputs	Method-dependent	Classification-focused
Attribution for each individual forecast horizon	✓	Manual target wiring	Manual target wiring	—
Joint time–feature maps for multivariate inputs	✓	Generic feature maps	Varies by method	Varies by method
Documented integration with recent deep time-series models	✓	—	—	—
Tested with LLM-backed time-series foundation models	✓	—	—	—
Native and established methods behind one PyTorch API	✓	General-purpose methods	Captum + time-series methods	Separate multi-backend API

A scoped comparison

"—" means the project does not provide first-class, documented support for the capability, not that integration is theoretically impossible. Among these libraries, tslens is the only one with documented, tested integrations spanning TSlib models such as DLinear, iTransformer, and TimesNet and LLM-backed models such as CALF, OFA/GPT4TS, and TimeLLM. See tested models and the integration cookbook.

Interpretation methods

tslens covers perturbation, gradient, learned-mask, and surrogate approaches through the same PyTorch workflow, so you can pick a method based on your model, explanation goal, and available compute.

• Perturbation and occlusion

  WinTSR · WinIT · Occlusion · Feature Ablation · Feature Permutation · Augmented Occlusion · FIT

• Gradient-based

  TSR · Integrated Gradients · Gradient SHAP

• Learned masks

  GateMask · Dyna Mask · Extremal Mask

• Local surrogate

  Lime

See the full method comparison or tested models for details.

Quickstart

Install tslens from PyPI. Python 3.9+ and PyTorch 1.13+ are required.

pip install tslens

Pass a model and a tensor shaped (batch, seq_len, n_features):

import torch
from tslens import WinTSR

inputs = torch.randn(16, 96, 7)
baselines = torch.zeros_like(inputs)

attr = WinTSR(model).attribute(
    inputs,
    baselines=baselines,
    threshold=0.5,
)

attr.shape  # (16, n_output, 96, 7)

The result contains one (seq_len, n_features) saliency map for each model output. Plot a map as a heatmap to inspect where the model found evidence.

Start with a faithful baseline

Zeros are appropriate for standardized inputs. If zero has a special meaning in your data, use get_baseline to generate a mean, normal, or random baseline.

Key options

Argument	Effect
threshold	Quantile of time relevance skipped during stage two. Higher values are faster and produce sparser maps; 0.0 keeps every step.
sliding_window_shapes	Attribution window over (time, features). Increase the first value to attribute multi-step regions.
baselines	Values substituted for occluded regions. Defaults to zero.
unflatten	When True (default), returns (batch, n_output, seq_len, n_features).
legacy_normalize	Constructor option that reproduces the normalization used for the published results.

See the WinTSR API reference for every option.

Multi-input models

Pass attributed tensors as a tuple and supply unchanged context through additional_forward_args. For a TSlib model:

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),
)

The integration cookbook covers TSlib, classification, custom model outputs, single forecast horizons, baseline selection, and performance tuning.

Further reading

• Integration cookbook: recipes for common model signatures and attribution workflows.
• Interpretation methods: requirements, trade-offs, and recommended use cases for every method.
• Supported models: architectures and calling conventions tested with tslens.
• API reference: signatures and parameters generated from the package docstrings.

Reproduce the research

The separate WinTSR-research repository contains the training harness, model zoo, datasets, experiment scripts, and saved results used in the paper.

Citation

If tslens supports your research, please cite:

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