DOCSEARCHbyAlgolia
Submit Docs

TS2Vec Documentation

repository·main·Indexed 21 days ago

https://github.com/zhihanyue/ts2vec

An implementation of the TS2Vec paper providing a universal representation learning framework for time series data. It enables the extraction of timestamp-level and instance-level embeddings via a Python API or CLI. The library supports various datasets including UCR, UEA, ETT, Electricity, Yahoo, and KPI, and offers three encoding modes: timestamp-level, instance-level (full series), and causal sliding inference.

Tokens
1K
Snippets
3
Records
5
Agent score
25%

What's inside TS2Vec

  1. How TS2Vec encoding modes work

    main

    The .encode() method supports three primary modes for generating representations from time series data:

    1. Timestamp-level: The default mode. Returns a representation for every timestamp in the series. Shape: (n_instances, n_timestamps, output_dims).
    2. Instance-level: Set encoding_window='full_series'. Returns a single representation vector for the entire time series instance. Shape: (n_instances, output_dims).
    3. Sliding Inference (Causal): Set causal=True, sliding_length, and sliding_padding. This allows for real-time style inference where the representation at timestamp t is computed using only observations in the window [t - sliding_padding, t]. Shape: (n_instances, n_timestamps, output_dims).

  2. Install TS2Vec requirements

    main

    Install the necessary dependencies for TS2Vec using the provided requirements file. The recommended environment uses Python 3.8 and specific versions of torch, scipy, numpy, pandas, scikit_learn, statsmodels, and Bottleneck.

    pip install -r requirements.txt

  3. Organize datasets for TS2Vec

    main

    Datasets must be placed in a datasets/ folder following specific directory structures depending on the source:

    • UCR (128 datasets): Place in datasets/UCR/<dataset_name>/ with files named <dataset_name>_*.csv.
    • UEA (30 datasets): Place in datasets/UEA/<dataset_name>/ with files named <dataset_name>_*.arff.
    • ETT (3 datasets): Place directly at datasets/ETTh1.csv, datasets/ETTh2.csv, and datasets/ETTm1.csv.
    • Electricity: Preprocess with datasets/preprocess_electricity.py and place at datasets/electricity.csv.
    • Yahoo: Preprocess with datasets/preprocess_yahoo.py and place at datasets/yahoo.pkl.
    • KPI: Preprocess with datasets/preprocess_kpi.py and place at datasets/kpi.pkl.

  4. Use the TS2Vec Python API

    main

    You can use TS2Vec programmatically by importing the TS2Vec class. The workflow involves initializing the model with input/output dimensions, calling .fit() on training data, and using .encode() to generate representations at different granularities (timestamp-level, instance-level, or sliding inference).

    from ts2vec import TS2Vec
import datautils

# Load data (shape: n_instances x n_timestamps x n_features)
train_data, train_labels, test_data, test_labels = datautils.load_UCR('ECG200')

# Initialize and train
model = TS2Vec(
    input_dims=1,
    device=0,
    output_dims=320
)
loss_log = model.fit(train_data, verbose=True)

# 1. Timestamp-level representations
test_repr_ts = model.encode(test_data)  # n_instances x n_timestamps x output_dims

# 2. Instance-level representations
test_repr_inst = model.encode(test_data, encoding_window='full_series')  # n_instances x output_dims

# 3. Sliding inference (causal)
test_repr_sliding = model.encode(
    test_data,
    causal=True,
    sliding_length=1,
    sliding_padding=50
)  # n_instances x n_timestamps x output_dims

  5. Train and evaluate TS2Vec via CLI

    main

    Run the train.py script to train and optionally evaluate the model on a specific dataset. Results (encoder, output, and metrics) are saved in training/DatasetName__RunName_Date_Time/.

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