[Enhancement] New Augmenter: Temporal Patch Shuffle (TPS)

[jafarbakhshaliyev]

Summary

I would like to propose adding Temporal Patch Shuffle (TPS) as a new augmenter to tsaug. TPS is a simple, model-agnostic data augmentation method for time series that extracts overlapping temporal patches, selectively shuffles a subset of low-variance patches, and reconstructs the sequence by averaging overlapping regions. It increases sample diversity while preserving local temporal structure.

Why TPS belongs in tsaug

tsaug currently provides transformation-based augmenters (noise injection, time warping, dropout, quantization, etc.), but does not include any patch-based augmentation method. Patch-based augmentations are widely used in computer vision (PatchShuffle, PatchMix) but have not been adapted to the time series domain until TPS. Adding TPS would expand tsaug's coverage into this category.

TPS has been evaluated extensively across nine long-term and four short-term forecasting benchmarks using five model families (TSMixer, DLinear, PatchTST, TiDE, LightTS), consistently outperforming 11 existing augmentation baselines including FreqMask/Mix, WaveMask/Mix, Dominant Shuffle, and others. TPS also transfers to time series classification (UCR and UEA benchmarks). Full details are available in the preprint:

Temporal Patch Shuffle (TPS): Leveraging Patch-Level Shuffling to Boost Generalization and Robustness in Time Series Forecasting
Bakhshaliyev, Burchert, Landwehr, Schmidt-Thieme (2026)
Preprint: https://arxiv.org/abs/2604.09067
Code: https://github.com/jafarbakhshaliyev/TPS

How TPS works (brief)

1. Temporal Patching: Extract overlapping patches of length p with stride s from the time series.
2. Variance-Aware Shuffling: Compute variance per patch. Select the fraction α of lowest-variance patches and randomly permute them.
3. Reconstruction: Place shuffled patches back and average overlapping regions.

The method has three hyperparameters: patch length (p), stride (s), and shuffle rate (α).

Proposed API

from tsaug import TemporalPatchShuffle

aug = TemporalPatchShuffle(
    patch_len=16,       # length of each patch
    stride=5,           # stride between patches
    rate=0.5,           # fraction of lowest-variance patches to shuffle
    repeats=1,
    prob=1.0,
    seed=None,
)

X_aug, Y_aug = aug.augment(X, Y)

This follows the existing tsaug augmenter pattern (subclass of _Augmenter, same repeats/prob/seed interface, NumPy-based, supports optional label array Y).

Implementation plan

• New file: src/tsaug/_temporal_patch_shuffle.py subclassing _Augmenter
• Pure NumPy implementation (no PyTorch dependency), following the same property/setter validation pattern used in Dropout, TimeWarp, etc.
• X and Y handled separately (unlike the original PyTorch implementation which concatenates them — the tsaug API naturally separates them)
• Unit tests in tests/ covering edge cases (rate=0, rate=1, patch_len > T, single vs. multi-channel, shape preservation, seed reproducibility)
• Documentation with usage examples
• Target branch: develop (since this adds to the public API)

Key design decisions for discussion

1. Parameter flexibility: Should patch_len, stride, and rate follow tsaug's convention of accepting scalar, list, or 2-tuple (interval) types, or keep them as simple scalars given their typical usage?

I am happy to implement this once the design is discussed. Looking forward to your feedback.