TS2Vec

https://github.com/zhihanyue/ts2vec
Admin
TS2Vec is a framework for learning universal representations of time series data through contrastive...
Tokens:9,900
Snippets:53
Trust Score:7
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### TS2Vec Command-Line Training Interface Examples

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Provides examples of using the `train.py` script for various time series tasks including classification, forecasting, and anomaly detection. It showcases different dataset loaders, hyperparameter configurations, and specific task setups like cold-start anomaly detection and handling irregular data.

```bash
# Train and evaluate on UCR classification dataset
python train.py ECG200 my_experiment \
    --loader UCR \
    --batch-size 8 \
    --repr-dims 320 \
    --gpu 0 \
    --epochs 100 \
    --eval

# Train on UEA multivariate classification dataset
python train.py BasicMotions experiment_uea \
    --loader UEA \
    --batch-size 16 \
    --repr-dims 320 \
    --gpu 0 \
    --eval

# Train for time series forecasting
python train.py ETTh1 forecast_exp \
    --loader forecast_csv \
    --batch-size 8 \
    --repr-dims 320 \
    --max-train-length 3000 \
    --gpu 0 \
    --eval

# Train for univariate forecasting
python train.py ETTh1 univar_forecast \
    --loader forecast_csv_univar \
    --batch-size 8 \
    --gpu 0 \
    --eval

# Train for anomaly detection
python train.py yahoo anomaly_exp \
    --loader anomaly \
    --batch-size 8 \
    --repr-dims 320 \
    --gpu 0 \
    --eval

# Cold-start anomaly detection (transfer learning)
python train.py yahoo coldstart_exp \
    --loader anomaly_coldstart \
    --batch-size 8 \
    --gpu 0 \
    --eval

# Training with custom hyperparameters and checkpointing
python train.py FordA custom_exp \
    --loader UCR \
    --batch-size 16 \
    --lr 0.0005 \
    --repr-dims 512 \
    --max-train-length 1000 \
    --iters 500 \
    --save-every 100 \
    --seed 42 \
    --gpu 0 \
    --eval

# Handle irregular/missing data
python train.py ECG200 irregular_exp \
    --loader UCR \
    --irregular 0.1 \
    --gpu 0 \
    --eval
```

--------------------------------

### Command-Line Training Interface

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Provides examples of using the `train.py` script for various time series tasks including classification, forecasting, and anomaly detection with customizable options.

```APIDOC
## Command-Line Training Interface

### Description
The `train.py` script offers a flexible command-line interface for training and evaluating TS2Vec models. It supports multiple tasks (classification, forecasting, anomaly detection) and allows customization of hyperparameters, data loaders, and hardware acceleration.

### Method
Command Line Interface (CLI)

### Endpoint
N/A

### Parameters
Various command-line arguments are supported, including:
- `dataset_name`: Name of the dataset to use.
- `experiment_name`: Name for the experiment.
- `--loader`: Data loader type (e.g., `UCR`, `UEA`, `forecast_csv`, `anomaly`).
- `--batch-size`: Batch size for training.
- `--repr-dims`: Dimension of the representation vectors.
- `--gpu`: GPU ID to use for training.
- `--epochs`: Number of training epochs.
- `--eval`: Flag to enable evaluation.
- `--irregular`: Parameter for handling irregular data.
- `--lr`: Learning rate.
- `--max-train-length`: Maximum sequence length for training.
- `--iters`: Number of iterations for training.
- `--save-every`: Frequency for saving model checkpoints.
- `--seed`: Random seed for reproducibility.

### Request Example
```bash
# Train and evaluate on UCR classification dataset
python train.py ECG200 my_experiment \
    --loader UCR \
    --batch-size 8 \
    --repr-dims 320 \
    --gpu 0 \
    --epochs 100 \
    --eval

# Train for anomaly detection (cold-start)
python train.py yahoo coldstart_exp \
    --loader anomaly_coldstart \
    --batch-size 8 \
    --gpu 0 \
    --eval

# Training with custom hyperparameters and checkpointing
python train.py FordA custom_exp \
    --loader UCR \
    --batch-size 16 \
    --lr 0.0005 \
    --repr-dims 512 \
    --max-train-length 1000 \
    --iters 500 \
    --save-every 100 \
    --seed 42 \
    --gpu 0 \
    --eval
```

### Response
#### Success Response (200)
Executes the training or evaluation process based on the provided arguments and prints logs to the console. Results are typically saved to experiment directories.
```

--------------------------------

### Train TS2Vec Model with fit()

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Shows how to train the TS2Vec model using the `fit` method with sample data. Supports training for a fixed number of iterations or epochs, and includes an example of using callbacks for checkpointing.

```python
from ts2vec import TS2Vec
import numpy as np

# Generate sample training data: 100 instances, 200 timestamps, 3 features
train_data = np.random.randn(100, 200, 3).astype(np.float32)

model = TS2Vec(
    input_dims=3,
    output_dims=320,
    device='cuda'
)

# Train for a fixed number of iterations
loss_log = model.fit(
    train_data,
    n_iters=200,        # Train for 200 iterations
    verbose=True        # Print loss after each epoch
)
# Output: Epoch #0: loss=1.234, Epoch #1: loss=0.987, ...

# Alternative: Train for a fixed number of epochs
loss_log = model.fit(
    train_data,
    n_epochs=10,
    verbose=True
)

# Training with callbacks for checkpointing
def checkpoint_callback(model, loss):
    if model.n_epochs % 5 == 0:
        model.save(f'checkpoint_epoch_{model.n_epochs}.pkl')

model_with_callback = TS2Vec(
    input_dims=3,
    output_dims=320,
    device='cuda',
    after_epoch_callback=checkpoint_callback
)
loss_log = model_with_callback.fit(train_data, n_epochs=20, verbose=True)
```

--------------------------------

### Install TS2Vec Dependencies

Source: https://github.com/zhihanyue/ts2vec/blob/main/README.md

Installs the required Python packages for the TS2Vec framework using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Hierarchical Contrastive Loss Implementation

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Details the `hierarchical_contrastive_loss` function, which combines instance-level and temporal contrastive losses across multiple scales. Examples show its computation with sample encoder outputs and how to adjust the `alpha` parameter to balance the contribution of instance versus temporal contrast.

```python
from models.losses import hierarchical_contrastive_loss, instance_contrastive_loss, temporal_contrastive_loss
import torch

# Sample encoder outputs for two augmented views
batch_size, seq_len, repr_dim = 16, 64, 320
z1 = torch.randn(batch_size, seq_len, repr_dim, requires_grad=True)
z2 = torch.randn(batch_size, seq_len, repr_dim, requires_grad=True)

# Compute hierarchical contrastive loss (default alpha=0.5)
loss = hierarchical_contrastive_loss(z1, z2)
print(f"Hierarchical loss: {loss.item():.4f}")

# Custom alpha balances instance vs temporal contrast
# alpha=1.0: only instance contrast, alpha=0.0: only temporal contrast
loss_instance_heavy = hierarchical_contrastive_loss(z1, z2, alpha=0.8)
loss_temporal_heavy = hierarchical_contrastive_loss(z1, z2, alpha=0.2)
```

--------------------------------

### Initialize TS2Vec Model

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Demonstrates how to initialize the TS2Vec model for both univariate and multivariate time series. Key parameters include input/output dimensions, network architecture, device placement, and training hyperparameters.

```python
from ts2vec import TS2Vec
import numpy as np

# Initialize a TS2Vec model for univariate time series
model = TS2Vec(
    input_dims=1,              # Number of input features (1 for univariate)
    output_dims=320,           # Representation dimension
    hidden_dims=64,            # Hidden layer dimension
    depth=10,                  # Number of residual blocks
    device='cuda',             # Device for training ('cuda' or 'cpu' or GPU index)
    lr=0.001,                  # Learning rate
    batch_size=16,             # Training batch size
    max_train_length=3000,     # Maximum sequence length (longer sequences are cropped)
    temporal_unit=0            # Minimum temporal unit for contrastive learning
)

# Initialize for multivariate time series (e.g., 7 features)
multivariate_model = TS2Vec(
    input_dims=7,
    output_dims=320,
    hidden_dims=64,
    depth=10,
    device=0                   # Use GPU 0
)
```

--------------------------------

### Cold-start Anomaly Detection with TS2Vec

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Demonstrates how to perform anomaly detection without target-specific training data using a pre-trained TS2Vec model. It loads data, initializes the model, fits it to the data, and then evaluates its performance in a cold-start scenario.

```python
from model import TS2Vec
from utils import datautils, tasks

# Load UCR dataset for cold-start anomaly detection
train_data_coldstart, _, _, _ = datautils.load_UCR('FordA')

# Initialize TS2Vec model with specified dimensions and device
model_coldstart = TS2Vec(input_dims=1, output_dims=320, device='cuda')

# Train the model on the loaded data
model_coldstart.fit(train_data_coldstart, n_iters=200)

# Evaluate anomaly detection performance in a cold-start setting
predictions_cs, eval_results_cs = tasks.eval_anomaly_detection_coldstart(
    model_coldstart,
    all_train_data, all_train_labels, all_train_timestamps,
    all_test_data, all_test_labels, all_test_timestamps,
    delay
)

# Print the F1 score for cold-start anomaly detection
print(f"\nCold-start F1: {eval_results_cs['f1']:.4f}")
```

--------------------------------

### Cold-start Anomaly Detection

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Demonstrates how to perform cold-start anomaly detection using a pre-trained TS2Vec model without target-specific training data.

```APIDOC
## Cold-start Anomaly Detection

### Description
This section shows an example of performing anomaly detection in a cold-start scenario, where no specific training data for the target task is available. It utilizes the `TS2Vec` model and a utility function for evaluation.

### Method
Python Script

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from ts2vec import TS2Vec
import datautils
import tasks

# Load UCR dataset for cold-start scenario
train_data_coldstart, _, _, _ = datautils.load_UCR('FordA')

# Initialize TS2Vec model
model_coldstart = TS2Vec(input_dims=1, output_dims=320, device='cuda')

# Train the model
model_coldstart.fit(train_data_coldstart, n_iters=200)

# Evaluate anomaly detection in a cold-start setting
predictions_cs, eval_results_cs = tasks.eval_anomaly_detection_coldstart(
    model_coldstart,
    all_train_data, all_train_labels, all_train_timestamps,
    all_test_data, all_test_labels, all_test_timestamps,
    delay
)

print(f"\nCold-start F1: {eval_results_cs['f1']:.4f}")
```

### Response
#### Success Response (200)
Prints the F1 score for cold-start anomaly detection.

#### Response Example
```
Cold-start F1: 0.8521
```
```

--------------------------------

### TS2Vec Loss Calculation and Backpropagation (Python)

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Demonstrates how to calculate different loss components (instance, temporal, hierarchical) in TS2Vec and perform backpropagation. It shows how to adjust temporal units for long sequences and prints the computed gradients.

```python
loss_long_seq = hierarchical_contrastive_loss(z1, z2, temporal_unit=2)
inst_loss = instance_contrastive_loss(z1, z2)
temp_loss = temporal_contrastive_loss(z1, z2)
print(f"Instance loss: {inst_loss.item():.4f}")
print(f"Temporal loss: {temp_loss.item():.4f}")
loss.backward()
print(f"Gradient computed: z1.grad.shape = {z1.grad.shape}")
```

--------------------------------

### Perform Time Series Forecasting Evaluation

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Shows how to load forecasting data, train the model, and use sliding inference to evaluate forecasting performance across multiple horizons using ridge regression.

```python
import datautils
import tasks
from ts2vec import TS2Vec

# Load ETTh1 forecasting dataset
data, train_slice, valid_slice, test_slice, scaler, pred_lens, n_covariate_cols = \
    datautils.load_forecast_csv('ETTh1')

# Train model on training data
train_data = data[:, train_slice]
model = TS2Vec(
    input_dims=train_data.shape[-1],
    output_dims=320,
    device='cuda',
    max_train_length=3000
)
model.fit(train_data, n_iters=200, verbose=True)

# Evaluate forecasting performance
out_log, eval_results = tasks.eval_forecasting(
    model, data, train_slice, valid_slice, test_slice,
    scaler, pred_lens, n_covariate_cols
)
```

--------------------------------

### Apply Masking During Encoding

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Demonstrates how to apply a mask during the encoding process. This is particularly useful for tasks like anomaly detection where specific timestamps need to be hidden.

```python
repr_masked = model.encode(test_data, mask='mask_last')
```

--------------------------------

### Save and Load TS2Vec Models

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Shows how to persist a trained TS2Vec model to disk as a pickle file and restore it for subsequent inference tasks.

```python
from ts2vec import TS2Vec
import numpy as np

train_data = np.random.randn(100, 200, 1).astype(np.float32)
model = TS2Vec(input_dims=1, output_dims=320, device='cuda')
model.fit(train_data, n_iters=200, verbose=True)

model.save('trained_model.pkl')

loaded_model = TS2Vec(input_dims=1, output_dims=320, device='cuda')
loaded_model.load('trained_model.pkl')

test_data = np.random.randn(10, 200, 1).astype(np.float32)
representations = loaded_model.encode(test_data, encoding_window='full_series')
```

--------------------------------

### Train and Evaluate TS2Vec via CLI

Source: https://github.com/zhihanyue/ts2vec/blob/main/README.md

Executes the training and evaluation process for a specified dataset using the command-line interface.

```bash
python train.py <dataset_name> <run_name> --loader <loader> --batch-size <batch_size> --repr-dims <repr_dims> --gpu <gpu> --eval
```

--------------------------------

### Execute Anomaly Detection Evaluation

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Illustrates the process of preparing anomaly detection data, training the model, and evaluating the detection performance using F1 score, precision, and recall metrics.

```python
import datautils
import tasks
from ts2vec import TS2Vec

# Load anomaly detection dataset
all_train_data, all_train_labels, all_train_timestamps, \
all_test_data, all_test_labels, all_test_timestamps, delay = \
    datautils.load_anomaly('yahoo')

# Prepare training data
train_data = datautils.gen_ano_train_data(all_train_data)

# Train model
model = TS2Vec(input_dims=1, output_dims=320, device='cuda')
model.fit(train_data, n_iters=200, verbose=True)

# Standard anomaly detection evaluation
predictions, eval_results = tasks.eval_anomaly_detection(
    model,
    all_train_data, all_train_labels, all_train_timestamps,
    all_test_data, all_test_labels, all_test_timestamps,
    delay
)
```

--------------------------------

### TSEncoder Neural Network Architecture Initialization and Usage

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Illustrates the initialization and usage of the TSEncoder class, which employs dilated convolutions for hierarchical feature extraction. It covers forward passes during training and inference, demonstrates custom masking strategies, and shows how to handle data with missing values (NaNs).

```python
from models import TSEncoder
import torch

# Initialize encoder directly (for advanced use cases)
encoder = TSEncoder(
    input_dims=3,           # Number of input features
    output_dims=320,        # Representation dimension
    hidden_dims=64,         # Hidden layer size
    depth=10,               # Number of dilated conv layers
    mask_mode='binomial'    # Default masking strategy
)

# Forward pass with sample data
batch_size, seq_len, features = 32, 100, 3
x = torch.randn(batch_size, seq_len, features)

# During training (applies binomial mask automatically)
encoder.train()
output_train = encoder(x)
print(f"Training output shape: {output_train.shape}")  # (32, 100, 320)

# During inference (no mask applied)
encoder.eval()
output_eval = encoder(x)
print(f"Eval output shape: {output_eval.shape}")  # (32, 100, 320)

# Custom masking modes
output_continuous = encoder(x, mask='continuous')  # Continuous segment masking
output_mask_last = encoder(x, mask='mask_last')    # Mask only last timestamp
output_all_true = encoder(x, mask='all_true')      # No masking

# Handle data with NaN values (missing observations)
x_with_nan = x.clone()
x_with_nan[0, 10:20, :] = float('nan')  # Missing segment
output_nan = encoder(x_with_nan)  # Automatically handles NaN values
```

--------------------------------

### Load Forecasting Datasets

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Functions to load forecasting datasets with automatic splitting into training, validation, and test sets, along with time feature extraction.

```python
import datautils
data, train_slice, valid_slice, test_slice, scaler, pred_lens, n_covariate_cols = datautils.load_forecast_csv('ETTh1')
```

--------------------------------

### TS2Vec Model Initialization

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Initialize a TS2Vec model for univariate or multivariate time series data. Configure input/output dimensions, network architecture, device, and training hyperparameters.

```APIDOC
## TS2Vec Model Initialization

### Description
Initialize a TS2Vec model for univariate or multivariate time series data. Configure input/output dimensions, network architecture, device, and training hyperparameters.

### Method
`TS2Vec(...)`

### Parameters
#### Initialization Parameters
- **input_dims** (int) - Required - Number of input features (1 for univariate).
- **output_dims** (int) - Required - Representation dimension.
- **hidden_dims** (int) - Required - Hidden layer dimension.
- **depth** (int) - Required - Number of residual blocks.
- **device** (str or int) - Optional - Device for training ('cuda', 'cpu', or GPU index). Defaults to 'cpu'.
- **lr** (float) - Optional - Learning rate. Defaults to 0.001.
- **batch_size** (int) - Optional - Training batch size. Defaults to 16.
- **max_train_length** (int) - Optional - Maximum sequence length (longer sequences are cropped). Defaults to 3000.
- **temporal_unit** (int) - Optional - Minimum temporal unit for contrastive learning. Defaults to 0.
- **after_epoch_callback** (function) - Optional - Callback function to execute after each epoch.

### Request Example
```python
from ts2vec import TS2Vec

# Initialize for univariate time series
model = TS2Vec(
    input_dims=1,
    output_dims=320,
    hidden_dims=64,
    depth=10,
    device='cuda',
    lr=0.001,
    batch_size=16,
    max_train_length=3000,
    temporal_unit=0
)

# Initialize for multivariate time series (e.g., 7 features)
multivariate_model = TS2Vec(
    input_dims=7,
    output_dims=320,
    hidden_dims=64,
    depth=10,
    device=0 # Use GPU 0
)
```
```

--------------------------------

### Encode Time Series with encode()

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Illustrates how to generate time series representations using the `encode` method. Covers various encoding modes including timestamp-level, instance-level, multiscale, and sliding window inference with causal options.

```python
from ts2vec import TS2Vec
import numpy as np

# Sample test data: 50 instances, 150 timestamps, 3 features
test_data = np.random.randn(50, 150, 3).astype(np.float32)

# Assume model is already trained
model = TS2Vec(input_dims=3, output_dims=320, device='cuda')
# model.fit(train_data, n_iters=200)

# Timestamp-level representations (default)
repr_timestamp = model.encode(test_data)
# Shape: (50, 150, 320) - one representation per timestamp

# Instance-level representations (pooled over entire series)
repr_instance = model.encode(test_data, encoding_window='full_series')
# Shape: (50, 320) - one representation per instance

# Multiscale representations
repr_multiscale = model.encode(test_data, encoding_window='multiscale')
# Shape: (50, 150, 320*num_scales) - concatenated multiscale features

# Fixed window pooling
repr_windowed = model.encode(test_data, encoding_window=10)
# Shape: (50, 150, 320) - pooled over windows of size 10

# Sliding inference for long sequences (causal mode for forecasting)
repr_sliding = model.encode(
    test_data,
    causal=True,           # Only use past information
    sliding_length=1,      # Slide by 1 timestamp
    sliding_padding=50,    # Use 50 timestamps of context
    batch_size=256
)
# Shape: (50, 150, 320) - each timestamp uses only [t-50, t] context
```

--------------------------------

### Train and Encode with TS2Vec Python API

Source: https://github.com/zhihanyue/ts2vec/blob/main/README.md

Demonstrates how to load UCR data, initialize the TS2Vec model, fit it to training data, and generate representations for test data using different encoding windows.

```python
from ts2vec import TS2Vec
import datautils

# Load the ECG200 dataset from UCR archive
train_data, train_labels, test_data, test_labels = datautils.load_UCR('ECG200')

# Train a TS2Vec model
model = TS2Vec(
    input_dims=1,
    device=0,
    output_dims=320
)
loss_log = model.fit(
    train_data,
    verbose=True
)

# Compute timestamp-level representations for test set
test_repr = model.encode(test_data)

# Compute instance-level representations for test set
test_repr = model.encode(test_data, encoding_window='full_series')

# Sliding inference for test set
test_repr = model.encode(
    test_data,
    causal=True,
    sliding_length=1,
    sliding_padding=50
)
```

--------------------------------

### Load Anomaly Detection Datasets

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Loads anomaly detection datasets containing multiple time series with associated labels and timestamps.

```python
import datautils
all_train_data, all_train_labels, all_train_timestamps, all_test_data, all_test_labels, all_test_timestamps, delay = datautils.load_anomaly('yahoo')
```

--------------------------------

### Train and Evaluate Classification Tasks with TS2Vec

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Demonstrates loading UCR datasets, training a TS2Vec model, and evaluating representations using SVM, linear regression, and k-NN classifiers to compute accuracy and AUPRC.

```python
import datautils
import tasks
from ts2vec import TS2Vec

# Load dataset and train model
train_data, train_labels, test_data, test_labels = datautils.load_UCR('ECG200')

model = TS2Vec(input_dims=1, output_dims=320, device='cuda')
model.fit(train_data, n_iters=200, verbose=True)

# Evaluate with SVM classifier
predictions, eval_results = tasks.eval_classification(
    model,
    train_data,
    train_labels,
    test_data,
    test_labels,
    eval_protocol='svm'
)

print(f"Accuracy: {eval_results['acc']:.4f}")
print(f"AUPRC: {eval_results['auprc']:.4f}")
```

--------------------------------

### Load UEA Multivariate Datasets

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Utility to load multivariate time series classification datasets from the UEA archive, handling ARFF processing and scaling.

```python
import datautils
train_data, train_labels, test_data, test_labels = datautils.load_UEA('BasicMotions')
```

--------------------------------

### Load UCR Classification Datasets

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Utility to load univariate time series classification datasets from the UCR archive, including automatic label transformation.

```python
import datautils
train_data, train_labels, test_data, test_labels = datautils.load_UCR('ECG200')
```

--------------------------------

### Training with fit()

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Train the TS2Vec model on time series data using hierarchical contrastive learning. Supports iteration or epoch-based training with optional callbacks.

```APIDOC
## Training with fit()

### Description
Train the TS2Vec model on time series data using hierarchical contrastive learning. Supports iteration or epoch-based training with optional callbacks for checkpointing.

### Method
`model.fit(data, ...)`

### Parameters
#### Input Parameters
- **data** (numpy.ndarray) - Required - Training data as a 3D numpy array (n_instances, n_timestamps, n_features).
- **n_iters** (int) - Optional - Number of iterations to train for. Mutually exclusive with `n_epochs`.
- **n_epochs** (int) - Optional - Number of epochs to train for. Mutually exclusive with `n_iters`.
- **verbose** (bool) - Optional - Print loss after each epoch. Defaults to False.

### Request Example
```python
from ts2vec import TS2Vec
import numpy as np

# Generate sample training data: 100 instances, 200 timestamps, 3 features
train_data = np.random.randn(100, 200, 3).astype(np.float32)

model = TS2Vec(input_dims=3, output_dims=320, device='cuda')

# Train for a fixed number of iterations
loss_log = model.fit(
    train_data,
    n_iters=200,
    verbose=True
)
# Output: Epoch #0: loss=1.234, Epoch #1: loss=0.987, ...

# Alternative: Train for a fixed number of epochs
loss_log = model.fit(
    train_data,
    n_epochs=10,
    verbose=True
)

# Training with callbacks for checkpointing
def checkpoint_callback(model, loss):
    if model.n_epochs % 5 == 0:
        model.save(f'checkpoint_epoch_{model.n_epochs}.pkl')

model_with_callback = TS2Vec(
    input_dims=3,
    output_dims=320,
    device='cuda',
    after_epoch_callback=checkpoint_callback
)
loss_log = model_with_callback.fit(train_data, n_epochs=20, verbose=True)
```

### Response
#### Success Response (200)
- **loss_log** (list) - A list containing the loss values recorded during training.
```

--------------------------------

### POST /tasks/eval_forecasting

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Evaluates time series representations for forecasting tasks using sliding inference and ridge regression.

```APIDOC
## POST /tasks/eval_forecasting

### Description
Performs forecasting evaluation using causal encoding and ridge regression across multiple prediction horizons.

### Method
POST

### Endpoint
/tasks/eval_forecasting

### Parameters
#### Request Body
- **model** (object) - Required - The trained TS2Vec model.
- **data** (array) - Required - Full time series dataset.
- **train_slice** (slice) - Required - Index slice for training.
- **valid_slice** (slice) - Required - Index slice for validation.
- **test_slice** (slice) - Required - Index slice for testing.
- **scaler** (object) - Required - Data scaler instance.
- **pred_lens** (list) - Required - List of prediction horizons.

### Response
#### Success Response (200)
- **eval_results** (object) - Contains MSE and MAE metrics for each prediction horizon.

#### Response Example
{
  "ours": {
    "24": {"norm": {"MSE": 0.0523, "MAE": 0.1734}}
  },
  "ts2vec_infer_time": 5.2
}
```

--------------------------------

### Hierarchical Contrastive Loss

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Explains the `hierarchical_contrastive_loss` function, which combines instance-level and temporal contrastive losses at multiple scales for effective time series representation learning.

```APIDOC
## Hierarchical Contrastive Loss

### Description
The `hierarchical_contrastive_loss` function is the primary objective used for training TS2Vec models. It unifies instance-level and temporal contrastive learning objectives across different temporal scales, leveraging a max-pooling hierarchy to capture multi-scale temporal patterns. This loss function encourages representations that are invariant to augmentations while preserving temporal dynamics.

### Method
Python Function

### Endpoint
N/A

### Parameters
- **z1** (torch.Tensor) - Required - Encoded representations of the first augmented view of a time series.
- **z2** (torch.Tensor) - Required - Encoded representations of the second augmented view of a time series.
- **alpha** (float) - Optional - A hyperparameter that balances the contribution of instance-level contrastive loss (when alpha=1.0) and temporal contrastive loss (when alpha=0.0). Defaults to 0.5.

### Request Example
```python
from models.losses import hierarchical_contrastive_loss
import torch

# Sample encoder outputs for two augmented views
batch_size, seq_len, repr_dim = 16, 64, 320
z1 = torch.randn(batch_size, seq_len, repr_dim, requires_grad=True)
z2 = torch.randn(batch_size, seq_len, repr_dim, requires_grad=True)

# Compute hierarchical contrastive loss with default alpha
loss = hierarchical_contrastive_loss(z1, z2)
print(f"Hierarchical loss: {loss.item():.4f}")

# Compute loss with emphasis on instance contrast
loss_instance_heavy = hierarchical_contrastive_loss(z1, z2, alpha=0.8)

# Compute loss with emphasis on temporal contrast
loss_temporal_heavy = hierarchical_contrastive_loss(z1, z2, alpha=0.2)
```

### Response
#### Success Response (200)
Returns a scalar tensor representing the computed hierarchical contrastive loss.

#### Response Example
```
Hierarchical loss: 1.2345
```
```

--------------------------------

### Encoding with encode()

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Compute representations for time series data using various encoding modes: timestamp-level, instance-level, multiscale, and sliding window inference.

```APIDOC
## Encoding with encode()

### Description
Compute representations for time series data using various encoding modes: timestamp-level, instance-level, multiscale, and sliding window inference for efficient processing of long sequences.

### Method
`model.encode(data, ...)`

### Parameters
#### Input Parameters
- **data** (numpy.ndarray) - Required - Input time series data as a 3D numpy array (n_instances, n_timestamps, n_features).
- **encoding_window** (str or int) - Optional - Specifies the encoding mode. Options include:
    - `'full_series'`: Instance-level representations (pooled over entire series).
    - `'multiscale'`: Multiscale representations (concatenated features).
    - `int`: Fixed window pooling size.
    - Defaults to timestamp-level representations if not specified.
- **causal** (bool) - Optional - If True, only use past information for encoding (useful for forecasting). Defaults to False.
- **sliding_length** (int) - Optional - The length of the sliding window step. Defaults to 1.
- **sliding_padding** (int) - Optional - The amount of context to use in the sliding window. Defaults to 0.
- **batch_size** (int) - Optional - Batch size for inference. Defaults to 256.

### Request Example
```python
from ts2vec import TS2Vec
import numpy as np

# Sample test data: 50 instances, 150 timestamps, 3 features
test_data = np.random.randn(50, 150, 3).astype(np.float32)

# Assume model is already trained
model = TS2Vec(input_dims=3, output_dims=320, device='cuda')
# model.fit(train_data, n_iters=200)

# Timestamp-level representations (default)
repr_timestamp = model.encode(test_data)
# Shape: (50, 150, 320)

# Instance-level representations (pooled over entire series)
repr_instance = model.encode(test_data, encoding_window='full_series')
# Shape: (50, 320)

# Multiscale representations
repr_multiscale = model.encode(test_data, encoding_window='multiscale')
# Shape: (50, 150, 320*num_scales)

# Fixed window pooling
repr_windowed = model.encode(test_data, encoding_window=10)
# Shape: (50, 150, 320)

# Sliding inference for long sequences (causal mode for forecasting)
repr_sliding = model.encode(
    test_data,
    causal=True,
    sliding_length=1,
    sliding_padding=50,
    batch_size=256
)
# Shape: (50, 150, 320)
```

### Response
#### Success Response (200)
- **representations** (numpy.ndarray) - The computed time series representations. The shape depends on the `encoding_window` and other parameters used.
```

--------------------------------

### POST /tasks/eval_anomaly_detection

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Evaluates the model's ability to detect anomalies in time series data using representation difference.

```APIDOC
## POST /tasks/eval_anomaly_detection

### Description
Evaluates anomaly detection performance using representation masking and difference analysis.

### Method
POST

### Endpoint
/tasks/eval_anomaly_detection

### Parameters
#### Request Body
- **model** (object) - Required - Trained TS2Vec model.
- **all_train_data** (array) - Required - Training data.
- **all_test_data** (array) - Required - Testing data.
- **delay** (int) - Required - Anomaly detection delay threshold.

### Response
#### Success Response (200)
- **eval_results** (object) - Contains 'f1', 'precision', 'recall', and 'infer_time'.

#### Response Example
{
  "f1": 0.7234,
  "precision": 0.6890,
  "recall": 0.7612,
  "infer_time": 12.34
}
```

--------------------------------

### POST /tasks/eval_classification

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Evaluates time series representations on classification tasks using specified classifiers like SVM, linear regression, or k-NN.

```APIDOC
## POST /tasks/eval_classification

### Description
Evaluates the performance of a trained TS2Vec model on classification tasks.

### Method
POST

### Endpoint
/tasks/eval_classification

### Parameters
#### Request Body
- **model** (object) - Required - The trained TS2Vec model instance.
- **train_data** (array) - Required - Training dataset features.
- **train_labels** (array) - Required - Training labels.
- **test_data** (array) - Required - Testing dataset features.
- **test_labels** (array) - Required - Testing labels.
- **eval_protocol** (string) - Required - The classifier to use: 'svm', 'linear', or 'knn'.

### Request Example
{
  "eval_protocol": "svm"
}

### Response
#### Success Response (200)
- **predictions** (array) - Predicted labels for the test set.
- **eval_results** (object) - Dictionary containing 'acc' (accuracy) and 'auprc' metrics.

#### Response Example
{
  "acc": 0.8700,
  "auprc": 0.9234
}
```

--------------------------------

### TSEncoder Neural Network Architecture

Source: https://context7.com/zhihanyue/ts2vec/llms.txt

Details the `TSEncoder` class, which implements a neural network using dilated convolutions for time series feature extraction, supporting various masking strategies and NaN handling.

```APIDOC
## TSEncoder Neural Network Architecture

### Description
The `TSEncoder` class is the core neural network component of TS2Vec. It utilizes dilated convolutional layers to capture hierarchical temporal dependencies in time series data. The architecture is designed for contrastive learning and can automatically handle missing data (NaN values) and apply different masking strategies during training.

### Method
Python Class

### Endpoint
N/A

### Parameters
- **input_dims** (int) - Required - The number of input features for each time step.
- **output_dims** (int) - Required - The dimension of the output representation vectors.
- **hidden_dims** (int) - Optional - The number of hidden units in the convolutional layers. Defaults to 64.
- **depth** (int) - Optional - The number of dilated convolutional layers. Defaults to 10.
- **mask_mode** (str) - Optional - The default masking strategy to use during training (e.g., 'binomial', 'continuous'). Defaults to 'binomial'.

### Request Example
```python
from models import TSEncoder
import torch

# Initialize encoder
encoder = TSEncoder(
    input_dims=3,           # Number of input features
    output_dims=320,        # Representation dimension
    hidden_dims=64,         # Hidden layer size
    depth=10,               # Number of dilated conv layers
    mask_mode='binomial'    # Default masking strategy
)

# Sample input data
batch_size, seq_len, features = 32, 100, 3
x = torch.randn(batch_size, seq_len, features)

# Training mode (applies mask)
encoder.train()
output_train = encoder(x)
print(f"Training output shape: {output_train.shape}")

# Inference mode (no mask)
encoder.eval()
output_eval = encoder(x)
print(f"Eval output shape: {output_eval.shape}")

# Using custom mask modes
output_continuous = encoder(x, mask='continuous')
output_mask_last = encoder(x, mask='mask_last')

# Handling data with NaN values
x_with_nan = x.clone()
x_with_nan[0, 10:20, :] = float('nan')  # Introduce missing segment
output_nan = encoder(x_with_nan)
```

### Response
#### Success Response (200)
Returns the encoded time series representations.

#### Response Example
```
Training output shape: torch.Size([32, 100, 320])
Eval output shape: torch.Size([32, 100, 320])
```
```
Tokens:
Raw