TSLib: Time Series Library

The project follows a structured pipeline for time series analysis:

• Execution Flow: scripts/*.sh (parameters) $\rightarrow$ run.py (entry point/dispatcher) $\rightarrow$ exp/* (task-specific experiment logic) $\rightarrow$ data_provider (data loading) & models (network instantiation) $\rightarrow$ results saved to ./checkpoints.
• Experiment Layer (exp/): Exp_Basic serves as the base class for all tasks, handling model registration and device management. Subclasses (e.g., exp_long_term_forecasting.py) implement task-specific train, test, and val logic.
• Model & Layer Layer (models/ & layers/): models/ contains the network architectures. Common building blocks like attention, convolutions, and frequency-domain units are stored in layers/ to promote reuse.
• Data Layer (data_provider/): data_factory.py selects the appropriate DataLoader based on the task. data_loader.py handles sequence slicing, sliding windows, and masking strategies.
• Utility Layer (utils/): Contains evaluation metrics (metrics.py), training tools like EarlyStopping (tools.py), and task-specific augmentation or masking logic.

The project follows a layered architecture designed for end-to-end (E2E) time-series analysis:

• Entry Point (run.py): The unified interface that parses arguments and dispatches tasks to the appropriate experiment class based on --task_name.
• Experiment Layer (exp/): Contains task-specific logic. Exp_Basic serves as the base class for registering models and devices, while subclasses (e.g., exp_imputation.py, exp_classification.py) implement the specific train and test flows.
• Model & Layer Layer (models/ and layers/): models/ contains the high-level architectures (e.g., TimesNet.py), while layers/ contains reusable primitives like attention blocks, convolutional units, or embedding layers.
• Data Layer (data_provider/): Uses a data_factory.py to return the correct DataLoader for a given task. The data_loader.py handles windowing, masking, and sampling logic.
• Utility Layer (utils/): Provides shared tools for metrics, augmentation, masking, and training helpers like EarlyStopping.
• Script Layer (scripts/): Contains bash recipes that capture specific hyperparameters and configurations for reproducibility.

E2E Data Flow: scripts/*.sh $\rightarrow$ run.py $\rightarrow$ exp/* $\rightarrow$ data_provider & models $\rightarrow$ utils $\rightarrow$ results written to ./checkpoints.

You can perform data augmentation by passing specific augmentation type labels as command-line arguments to run.py.

To control the frequency of augmentation, use the --augmentation_ratio parameter. This parameter represents how many times the augmentation method is performed. For example:

• Setting --augmentation_ratio 1 followed by --jitter performs the jitter augmentation once.
• Setting --augmentation_ratio 3 followed by three different augmentation labels will perform those three augmentations three times each (or according to the specific implementation logic of the ratio).

Note: The augmentation code follows the standard Time-Series-Library prototype. All other training parameters (like --batch_size, --learning_rate, etc.) are configurable via run.py.

export CUDA_VISIBLE_DEVICES=0

model_name=PatchTST

for aug in jitter scaling permutation magwarp timewarp windowslice windowwarp rotation spawner dtwwarp shapedtwwarp wdba discdtw discsdtw
do
echo using augmentation: ${aug}

python -u run.py \
  --task_name classification \
  --is_training 1 \
  --root_path ./dataset/EthanolConcentration/ \
  --model_id EthanolConcentration \
  --model $model_name \
  --data UEA \
  --e_layers 3 \
  --batch_size 16 \
  --d_model 128 \
  --d_ff 256 \
  --top_k 3 \
  --des 'Exp' \
  --itr 1 \
  --learning_rate 0.001 \
  --train_epochs 100 \
  --patience 10 \
  --augmentation_ratio 1 \
  --${aug}
 done

Follow these steps to set up a local development environment:

1. Clone the repository:

   git clone https://github.com/thuml/Time-Series-Library.git
   cd Time-Series-Library

2. Create and activate a Conda environment:

   conda create -n tslib python=3.11
   conda activate tslib

3. Install Core Dependencies: Ensure you install a torch version that matches your local CUDA version. Recommended: torch==2.5.1.

   pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cu121
   pip install -r requirements.txt

4. Install Mamba Model dependencies (Linux only, required for models/Mamba.py): The Mamba wheel must match your CUDA version. Example for CUDA 12:

   pip install https://github.com/state-spaces/mamba/releases/download/v2.2.6.post3/mamba_ssm-2.2.6.post3+cu12torch2.5cxx11abiFALSE-cp311-cp311-linux_x86_64.whl

5. Install Moirai Model dependencies (Required for models/Moirai.py):

   pip install uni2ts --no-deps