tsfmx 1.0.1

Multimodal extension for time series foundation models

TSFMx

TSFMx (TSFMx Standardizes Fusion of Multimodal exogenous features) is a framework for extending TSFMs (including TimesFM and Chronos) with multimodal inputs such as text.

Installation

pip install tsfmx[all]

Quick Start

1. Setup

Clone the Time-MMD dataset:

./scripts/clone_time_mmd.sh

Split the dataset into train / val / test:

PYTHONPATH=. uv run python scripts/split_time_mmd_datasets.py \
    --train-ratio 0.6 \
    --val-ratio 0.2

2. Pre-compute Text Embeddings

TimesFM:

PYTHONPATH=. uv run python scripts/cache_time_mmd_datasets.py \
    --model-config examples/time_mmd/configs/models/timesfm.yml \
    --text-encoder-type english
PYTHONPATH=. uv run python scripts/cache_time_mmd_datasets.py \
    --model-config examples/time_mmd/configs/models/timesfm.yml \
    --text-encoder-type english --augment

Chronos:

PYTHONPATH=. uv run python scripts/cache_time_mmd_datasets.py \
    --model-config examples/time_mmd/configs/models/chronos.yml \
    --text-encoder-type english
PYTHONPATH=. uv run python scripts/cache_time_mmd_datasets.py \
    --model-config examples/time_mmd/configs/models/chronos.yml \
    --text-encoder-type english --augment

3. Hyperparameter Tuning

Run a W&B Sweeps search for the multimodal model:

TimesFM:

PYTHONPATH=. uv run python scripts/tune_time_mmd_sweep.py \
    --model-config examples/time_mmd/configs/models/timesfm.yml \
    --sweep-config examples/time_mmd/configs/sweeps/multimodal_1layer.yml

Chronos:

PYTHONPATH=. uv run python scripts/tune_time_mmd_sweep.py \
    --model-config examples/time_mmd/configs/models/chronos.yml \
    --sweep-config examples/time_mmd/configs/sweeps/multimodal_1layer.yml

To compare against a fine-tuned baseline:

TimesFM:

PYTHONPATH=. uv run python scripts/tune_baseline_sweep.py \
    --model-config examples/time_mmd/configs/models/timesfm.yml \
    --sweep-config examples/time_mmd/configs/sweeps/baseline.yml

Chronos:

PYTHONPATH=. uv run python scripts/tune_baseline_sweep.py \
    --model-config examples/time_mmd/configs/models/chronos.yml \
    --sweep-config examples/time_mmd/configs/sweeps/baseline.yml

Acknowledgments

We thank the Time-MMD team for providing the multimodal time series dataset used in our examples and experiments.

License

MIT