tslens 0.1.0__tar.gz

tslens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Md. Khairul Islam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tslens-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: tslens
+Version: 0.1.0
+Summary: A consistent PyTorch interface to attribution methods for time series deep learning models, including WinTSR
+Author: Judy Fox
+Author-email: Md Khairul Islam <khairulislam@virginia.edu>
+License: MIT License
+        
+        Copyright (c) 2023 Md. Khairul Islam
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/khairulislam/tslens
+Project-URL: Repository, https://github.com/khairulislam/tslens
+Project-URL: Paper, https://arxiv.org/abs/2412.04532
+Keywords: time-series,interpretability,explainable-ai,xai,saliency,captum,pytorch,forecasting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=1.13
+Requires-Dist: numpy
+Requires-Dist: captum>=0.6
+Requires-Dist: time-interpret>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Dynamic: license-file
+
+# 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](https://arxiv.org/abs/2412.04532) ·
+Code: [github.com/khairulislam/tslens](https://github.com/khairulislam/tslens)
+
+## Install
+
+```bash
+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.
+
+```python
+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](https://github.com/thuml/Time-Series-Library) model (DLinear, iTransformer,
+TimesNet, ...) — its four forward arguments split into two attributed inputs and two
+context tensors, with no wrapper class:
+
+```python
+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](https://github.com/khairulislam/tslens/blob/main/docs/integration.md)
+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](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/quickstart.ipynb)
+and
+[TSlib models](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/tslib_models.ipynb).
+
+## Requirements
+
+`torch`, `numpy`, `captum`, and [`time-interpret`](https://github.com/josephenguehard/time_interpret).
+
+## Citation
+
+```bibtex
+@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}
+}
+```

tslens-0.1.0/README.md

@@ -0,0 +1,219 @@
+# tslens
+
+### A consistent PyTorch interface to time-series attribution methods
+
+[![arXiv](https://img.shields.io/badge/arXiv-2412.04532-b31b1b.svg)](https://arxiv.org/abs/2412.04532)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/quickstart.ipynb)
+[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://khairulislam.github.io/tslens/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Which time steps and features did your time-series model actually use?**
+
+tslens is a drop-in, Captum-compatible interpretability toolkit for PyTorch
+time-series models. Every method produces a saliency map over the input window so you
+can inspect *when* and *where* a model found evidence for its prediction.
+
+Explaining time series models is hard for two reasons that attribution methods borrowed
+from vision and NLP do not handle: subsequent time steps are strongly dependent, and
+feature importance varies over time. Existing studies (1) do not consider the temporal
+dependencies among the feature vectors in the input window, and (2) consider the time
+dimension separately from the feature dimension when calculating importance scores.
+**Windowed Temporal Saliency Rescaling (WinTSR)**, the toolkit's native flagship
+method, addresses both.
+
+![WinTSR attribution heatmap](docs/assets/wintsr_heatmap.png)
+
+## Why tslens?
+
+- **Model-agnostic:** explain any callable PyTorch model with the expected input shape.
+- **Time-aware:** preserve relationships between neighbouring observations, via WinTSR.
+- **Joint attribution:** identify important time–feature regions, not just global features.
+- **Practical:** support multi-input models, custom baselines, classification, and forecasting.
+- **One interface:** compare established attribution methods from Captum, Time Interpret,
+  and this package's own native implementations side by side.
+
+## Quickstart
+
+```bash
+pip install tslens
+```
+
+Requires Python 3.9+ and PyTorch 1.13+. Works with any PyTorch model mapping
+`(batch, seq_len, n_features)` to predictions — no training framework to adopt, no
+dataset format to conform to:
+
+```python
+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,
+)
+attr.shape   # (16, n_output, 96, 7)
+```
+
+For local development, install the package with its test and documentation tools:
+
+```bash
+pip install -e ".[dev,docs]"
+pytest
+```
+
+Plot `attr` as a heatmap over `(seq_len, n_features)` to read off what the model used.
+
+### Getting started
+
+| | |
+| --- | --- |
+| **[Quickstart notebook](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/quickstart.ipynb)** | 60 seconds, no dataset download. Plants a known signal, trains a small GRU, checks WinTSR recovers it. |
+| **[TSlib models notebook](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/tslib_models.ipynb)** | Explaining DLinear, iTransformer, TimesNet and friends. No wrapper class needed. |
+| **[Classification notebook](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/classification.ipynb)** | `n_output` becomes the class count; a padding mask goes through as context, not as an attributed input. |
+| **[Baselines notebook](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/baselines.ipynb)** | Why the baseline matters, `get_baseline`'s four modes compared by attribution quality, and how to use a custom one. |
+| **[Custom outputs notebook](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/custom_outputs.ipynb)** | Wrapping models that return a dict or tuple (TimeLLM-style) with a one-line lambda. |
+| **[Integration cookbook](https://khairulislam.github.io/tslens/integration/)** | Copy-paste recipes: dict/tuple outputs, classification, baselines, single horizons, speed, troubleshooting. |
+| **[Interpretation methods](https://khairulislam.github.io/tslens/methods/)** | What WinTSR, TSR, WinIT and GateMask each do differently, and when to reach for which one. |
+| **[API reference](https://khairulislam.github.io/tslens/reference/wintsr/)** | Every argument, generated from the docstrings, including `legacy_normalize=True` to reproduce the published numbers. |
+
+Already have a TSlib model? It takes four tensors, so split them into what you want
+attributed and what is just context:
+
+```python
+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),
+)
+```
+
+## Interpretation methods
+
+tslens gives you a broad set of attribution methods through one interface, and works
+with any PyTorch time series model. WinTSR, TSR, WinIT, and GateMask are implemented
+natively here; the rest call [Captum](https://captum.ai/docs/introduction) and
+[tint](https://josephenguehard.github.io/time_interpret/build/html/index.html) directly.
+See [Interpretation methods](https://khairulislam.github.io/tslens/methods/) for what
+each one does differently and when to use it.
+
+<details>
+<summary><b>Supported methods</b> (click to expand)</summary>
+
+| Method | Type | Paper |
+| --- | --- | --- |
+| WinTSR | Perturbation | [Islam & Fox, arXiv:2412.04532](https://arxiv.org/abs/2412.04532) |
+| TSR | Gradient | [Ismail et al., NeurIPS 2020](https://proceedings.neurips.cc/paper_files/paper/2020/file/47a3893cc405396a5c30d91320572d6d-Paper.pdf) |
+| WinIT | Perturbation | [Leung et al., ICLR 2023](https://arxiv.org/abs/2107.14317) |
+| GateMask | Learned mask | [Liu et al., ICLR 2024](https://arxiv.org/abs/2401.08552) |
+| Occlusion | Perturbation | [Zeiler & Fergus, ECCV 2014](https://arxiv.org/abs/1311.2901) |
+| Feature Ablation | Perturbation | [Kokhlikyan et al., arXiv:2009.07896](https://arxiv.org/abs/2009.07896) |
+| Feature Permutation | Perturbation | [Kokhlikyan et al., arXiv:2009.07896](https://arxiv.org/abs/2009.07896) |
+| Augmented Occlusion | Perturbation | [Enguehard, ICML 2023](https://proceedings.mlr.press/v202/enguehard23a.html) |
+| Integrated Gradients | Gradient | [Sundararajan et al., ICML 2017](https://arxiv.org/abs/1703.01365) |
+| Gradient SHAP | Gradient | [Lundberg & Lee, NeurIPS 2017](https://arxiv.org/abs/1705.07874) |
+| FIT | Perturbation | [Tonekaboni et al., NeurIPS 2020](https://proceedings.neurips.cc/paper/2020/hash/08fa43588c2571ade19bc0fa5936e028-Abstract.html) |
+| Dyna Mask | Learned mask | [Crabbé & van der Schaar, ICML 2021](https://proceedings.mlr.press/v139/crabbe21a.html) |
+| Extremal Mask | Learned mask | [Enguehard, ICML 2023](https://proceedings.mlr.press/v202/enguehard23a.html) |
+| Lime | Surrogate | [Ribeiro et al., KDD 2016](https://arxiv.org/abs/1602.04938) |
+
+Full comparison matrix (model requirement, baseline, API doc):
+[Interpretation methods](https://khairulislam.github.io/tslens/methods/).
+</details>
+
+## Supported models
+
+tslens attributes any callable that maps `(batch, seq_len, n_features)` — or a tuple of
+tensors — to predictions, so nothing here is hard-coded to a specific architecture. The
+list below is what this package and its [research harness](https://github.com/khairulislam/WinTSR-research)
+have actually been run against.
+
+<details>
+<summary><b>Supported model architectures</b> (click to expand)</summary>
+
+| Model | Family | Paper |
+| --- | --- | --- |
+| DLinear | Linear | [Zeng et al., AAAI 2023](https://arxiv.org/abs/2205.13504) |
+| LightTS | Linear/MLP | [Zhang et al., arXiv:2207.01186](https://arxiv.org/abs/2207.01186) |
+| TiDE | Linear/MLP | [Das et al., TMLR 2023](https://arxiv.org/abs/2304.08424) |
+| FiLM | Linear/MLP | [Zhou et al., NeurIPS 2022](https://arxiv.org/abs/2205.08897) |
+| TSMixer | MLP-Mixer | [Chen et al., TMLR 2023](https://arxiv.org/abs/2303.06053) |
+| FreTS | Frequency-domain MLP | [Yi et al., NeurIPS 2023](https://arxiv.org/abs/2311.06184) |
+| MICN | Convolutional | [Wang et al., ICLR 2023](https://openreview.net/pdf?id=zt53IDUR1U) |
+| Crossformer | Transformer | [Zhang & Yan, ICLR 2023](https://openreview.net/pdf?id=vSVLM2j9eie) |
+| PatchTST | Transformer | [Nie et al., ICLR 2023](https://arxiv.org/abs/2211.14730) |
+| Pyraformer | Transformer | [Liu et al., ICLR 2022](https://openreview.net/pdf?id=0EXmFzUn5I) |
+| SegRNN | Recurrent | [Lin et al., arXiv:2308.11200](https://arxiv.org/abs/2308.11200) |
+| Koopa | Koopman operator | [Liu et al., NeurIPS 2023](https://arxiv.org/abs/2305.18803) |
+| LSTM | Recurrent | [Hochreiter & Schmidhuber, Neural Computation 1997](https://www.bioinf.jku.at/publications/older/2604.pdf) |
+| TCN | Convolutional | [Bai et al., arXiv:1803.01271](https://arxiv.org/abs/1803.01271) |
+| CALF | LLM-backed foundation model | [Liu et al., arXiv:2403.07300](https://arxiv.org/abs/2403.07300) |
+| OFA (GPT4TS) | LLM-backed foundation model | [Zhou et al., NeurIPS 2023](https://arxiv.org/abs/2302.11939) |
+| TimeLLM | LLM-backed foundation model | [Jin et al., ICLR 2024](https://arxiv.org/abs/2310.01728) |
+| Transformer | Transformer | [Vaswani et al., NeurIPS 2017](https://proceedings.neurips.cc/paper/2017/file/3f5ee243547dee91fbd053c1c4a845aa-Paper.pdf) |
+| Informer | Transformer | [Zhou et al., AAAI 2021](https://ojs.aaai.org/index.php/AAAI/article/view/17325) |
+| Autoformer | Transformer | [Wu et al., NeurIPS 2021](https://openreview.net/pdf?id=I55UqU-M11y) |
+| FEDformer | Transformer | [Zhou et al., ICML 2022](https://proceedings.mlr.press/v162/zhou22g.html) |
+| ETSformer | Transformer | [Woo et al., arXiv:2202.01381](https://arxiv.org/abs/2202.01381) |
+| Nonstationary Transformer | Transformer | [Liu et al., NeurIPS 2022](https://openreview.net/pdf?id=ucNDIDRNjjv) |
+| Reformer | Transformer | [Kitaev et al., ICLR 2020](https://openreview.net/forum?id=rkgNKkHtvB) |
+| iTransformer | Transformer | [Liu et al., ICLR 2024](https://arxiv.org/abs/2310.06625) |
+| TimeXer | Transformer | [Wang et al., NeurIPS 2024](https://arxiv.org/abs/2402.19072) |
+| TimeMixer | MLP-Mixer | [Wang et al., ICLR 2024](https://arxiv.org/abs/2405.14616) |
+| TimesNet | Convolutional | [Wu et al., ICLR 2023](https://openreview.net/pdf?id=ju_Uqw384Oq) |
+| RNN | Recurrent | [Hochreiter & Schmidhuber, Neural Computation 1997](https://www.bioinf.jku.at/publications/older/2604.pdf) |
+
+Calling convention (single vs. dual-input) and trained checkpoints:
+[Supported models](https://khairulislam.github.io/tslens/models/).
+</details>
+
+## Repository layout
+
+| Path | What it is |
+| --- | --- |
+| [src/tslens/](/src/tslens/) | The installable library. `WinTSR` plus the paper's baseline methods (`TSR`, `WinIT`, `GateMask`). |
+| [notebooks/](/notebooks/) | Runnable quickstart and TSlib walkthrough. |
+| [tests/](/tests/) | Test suite, including a numerical-equivalence check against the pre-refactor implementation. |
+| [docs/](/docs/) | Source for the [docs site](https://khairulislam.github.io/tslens/): tutorials, method explainer, API reference, and the PyPI-page library reference. |
+
+This repo is the library only. The training/interpretation harness that produced the
+paper's results — model zoo, experiment scripts, saved results — lives in
+[WinTSR-research](https://github.com/khairulislam/WinTSR-research) and depends on this
+package the same way any user would (`pip install tslens`).
+
+## Reproducing the paper
+
+Training the models, running the full benchmark, and the paper's saved results live in
+[WinTSR-research](https://github.com/khairulislam/WinTSR-research), which installs this
+package as a regular dependency. That repo also has the model zoo — DLinear,
+iTransformer, TimesNet, CALF, TimeLLM and 25 others from
+[TSlib](https://github.com/thuml/Time-Series-Library) — dataset download instructions,
+and Docker/Singularity definitions.
+
+## Citation
+
+Find our paper on [arXiv](https://arxiv.org/pdf/2412.04532). Please cite the following if you use our work
+(also available as [CITATION.cff](CITATION.cff), used by GitHub's "Cite this repository" button).
+
+```bibtex
+@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}
+}
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Core libraries
+
+tslens builds on these open-source projects:
+
+- **[Captum](https://captum.ai/docs/introduction)** — model interpretability library for PyTorch.
+- **[Time Interpret (tint)](https://josephenguehard.github.io/time_interpret/build/html/index.html)** — extends Captum with methods designed for time series.
+- **[Time-Series-Library (TSlib)](https://github.com/thuml/Time-Series-Library)** — deep time series analysis models used in the benchmark.
+
+<!-- add here https://github.com/thuml/OpenLTM, https://github.com/thuml/Large-Time-Series-Model, https://github.com/fzi-forschungszentrum-informatik/TSInterpret.git -->

tslens-0.1.0/docs/pypi_readme.md

@@ -0,0 +1,90 @@
+# 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](https://arxiv.org/abs/2412.04532) ·
+Code: [github.com/khairulislam/tslens](https://github.com/khairulislam/tslens)
+
+## Install
+
+```bash
+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.
+
+```python
+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](https://github.com/thuml/Time-Series-Library) model (DLinear, iTransformer,
+TimesNet, ...) — its four forward arguments split into two attributed inputs and two
+context tensors, with no wrapper class:
+
+```python
+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](https://github.com/khairulislam/tslens/blob/main/docs/integration.md)
+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](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/quickstart.ipynb)
+and
+[TSlib models](https://colab.research.google.com/github/khairulislam/tslens/blob/main/notebooks/tslib_models.ipynb).
+
+## Requirements
+
+`torch`, `numpy`, `captum`, and [`time-interpret`](https://github.com/josephenguehard/time_interpret).
+
+## Citation
+
+```bibtex
+@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}
+}
+```

tslens-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tslens"
+version = "0.1.0"
+description = "A consistent PyTorch interface to attribution methods for time series deep learning models, including WinTSR"
+readme = "docs/pypi_readme.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Md Khairul Islam", email = "khairulislam@virginia.edu" },
+    { name = "Judy Fox" },
+]
+keywords = [
+    "time-series",
+    "interpretability",
+    "explainable-ai",
+    "xai",
+    "saliency",
+    "captum",
+    "pytorch",
+    "forecasting",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "torch>=1.13",
+    "numpy",
+    "captum>=0.6",
+    "time-interpret>=0.3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "matplotlib"]
+docs = ["mkdocs-material>=9", "mkdocstrings[python]>=0.25"]
+
+[project.urls]
+Homepage = "https://github.com/khairulislam/tslens"
+Repository = "https://github.com/khairulislam/tslens"
+Paper = "https://arxiv.org/abs/2412.04532"
+
+[tool.setuptools]
+# src-layout: only what lives under src/ ships. The training/interpretation
+# harness that reproduces the paper's results lives in a separate repo, see
+# the Homepage README.
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tslens-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tslens-0.1.0/src/tslens/__init__.py

@@ -0,0 +1,18 @@
+"""tslens: attribution methods for time series deep learning models.
+
+A drop-in, Captum-compatible interpretability toolkit for any PyTorch model
+that consumes ``(batch, seq_len, n_features)`` tensors. Includes WinTSR and
+other natively implemented methods, plus a consistent interface over Captum
+and Time Interpret baselines.
+
+    >>> from tslens import WinTSR
+    >>> attr = WinTSR(model).attribute(inputs, baselines=torch.zeros_like(inputs))
+
+WinTSR paper: https://arxiv.org/abs/2412.04532
+"""
+
+from .attr import WinTSR
+from .functional import get_baseline, normalize_scale
+
+__version__ = "0.1.0"
+__all__ = ["WinTSR", "get_baseline", "normalize_scale", "__version__"]

tslens-0.1.0/src/tslens/attr/__init__.py

@@ -0,0 +1,50 @@
+"""Attribution methods for time series models.
+
+:class:`WinTSR` is the method introduced in the paper it's named after.
+:class:`TSR`, :class:`WinIT` and :class:`GateMask` are the baselines used in
+its evaluation. All four work from a plain ``pip install tslens`` -- none of
+them require the research harness under ``research/``.
+
+The baselines are imported lazily so that ``import tslens`` stays cheap and
+does not drag in ``pytorch_lightning`` or ``sklearn`` unless a method that
+needs them is actually requested.
+"""
+
+from typing import TYPE_CHECKING
+
+from .wintsr import WinTSR
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .gate_mask import GateMask
+    from .tsr import TSR
+    from .winit import WinIT
+
+_LAZY = {"TSR": ".tsr", "WinIT": ".winit", "GateMask": ".gate_mask"}
+
+__all__ = ["WinTSR", "TSR", "WinIT", "GateMask"]
+
+
+def __getattr__(name: str):
+    """PEP 562 lazy import for the baseline methods."""
+    if name not in _LAZY:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    from importlib import import_module
+
+    try:
+        module = import_module(_LAZY[name], __name__)
+    except ImportError as exc:
+        raise ImportError(
+            f"{name} could not be imported. It is a baseline method whose "
+            "dependencies normally arrive with `time-interpret`; a broken or "
+            "partial install is the usual cause. Try reinstalling with "
+            f"`pip install --force-reinstall tslens`. Original error: {exc}"
+        ) from exc
+
+    value = getattr(module, name)
+    globals()[name] = value  # cache so __getattr__ runs once per name
+    return value
+
+
+def __dir__():
+    return sorted(__all__)