Granite Time Series Foundation Models (TSFM)

TinyTimeMixer (TTM) are compact, pre-trained foundation models for Time-Series Forecasting developed by IBM Research. With fewer than 1 million parameters, they are designed to be extremely efficient, outperforming much larger models (with billions of parameters) in both zero-shot and few-shot forecasting tasks.

Key characteristics:

• Efficiency: Can be executed on a single GPU or even a laptop.
• Speed: Inference/zero-shot takes seconds; fine-tuning takes minutes.
• Versatility: Supports forecasting resolutions from minutely to hourly.
• Modes: Supports Zeroshot forecasting (direct application) and Finetuned forecasting (training on a subset of target data).
• Multivariate Support: Supports both channel independence and channel-mixing approaches.

TTM supports two primary forecasting workflows:

1. Zeroshot forecasting: Apply the pre-trained model directly to your target data to obtain an initial forecast without any additional training.
2. Finetuned forecasting: Fine-tune the pre-trained model using a subset of your specific target data to improve accuracy for your unique time-series patterns.

Capabilities & Constraints:

• Multivariate Forecasting: You can enable Decoder Channel-Mixing during fine-tuning to capture strong correlation patterns across different time-series variates.
• Data Preparation: You must externally standard scale your data before feeding it to the model. It is recommended to use the TSP data processing utility for this.
• Avoid: Do not use upsampling or prepend zeros to artificially increase context length, as this negatively impacts model performance.

When deciding how to allow custom code, use the following comparison to guide your choice. TSFM_ADDITIONAL_HANDLER_MODULES is the recommended approach for production.

Results are automatically saved in a hierarchical directory structure under output/. The path follows the pattern: output/{dataset_name}/{model_name}_{context_length}_{prediction_length}/W1ACAS_{nonconformity_score}_{aggregation_features}/.

Each results folder contains:

• p_values.csv: P-values and predictions
• evaluation.json: Standard evaluation metrics
• anomaly_detection_visualization.png: Visualization plot

Example path: output/672_YAHOO_id_122_WebService_tr_500_1st_857/ttm_90_15/W1ACAS_absolute_error_Cauchy/

When evaluating TTM (TinyTimeMixer) using the FoundTS framework, observe the following constraints and data exclusions:

Context Length Constraints

TTM requires a minimum context length of 512 time-points. Consequently, datasets with short context lengths such as ILI, NASDAQ, NN5, and Wike2000 are ignored and cannot be applied with current TTM implementations.

Zero-shot Evaluation Exclusions

To ensure a fair zero-shot comparison, exclude datasets that were part of the model's pretraining data:

• Solar: Used in TTM pretraining (results will be artificially high).
• Weather and Electricity: Part of TimesFM pretraining.
• Traffic: Part of both TimesFM and Moirai pretraining.

The benchmarking scripts expect the TSB UAD Benchmark Datasets to follow a specific directory architecture. Ensure your datasets are organized as follows:

Datasets
 ├── TSB-AD-U
 │    ├── Univariates CSVs  
 ├── TSB-AD-M
 │     ├── Multi-variate CSVs
 ├── File_List
 │     ├── Resource file list 

When implementing custom handlers in modules added via TSFM_ADDITIONAL_HANDLER_MODULES, your classes must adhere to specific naming and security requirements to be successfully loaded:

1. Naming Convention: The class name must end with either Handler or ServiceHandler.
2. Security: Classes must follow secure coding practices and avoid exposing dangerous functionality.

Example of a valid handler class:

class CustomForecastingHandler:  # ✅ Ends with 'Handler'
    def __init__(self, model_id, model_path, handler_config):
        self.model_id = model_id
        self.model_path = model_path
        self.handler_config = handler_config
    
    def prepare(self, data, schema=None, parameters=None, **kwargs):
        pass

Execute the zero-shot imputation experiments for all datasets, mask types, and mask ratios by running the provided bash script. The results will be saved to tspulse_zeroshot_imputation_results.csv.

bash imputation_zeroshot.sh

The search benchmarking process requires the faiss library. If it is not already present in your environment, install the CPU version using pip.

pip install faiss-cpu

To run imputation experiments, you must organize your datasets in a specific directory structure.

1. ETT datasets (ETTh1, ETTh2, ETTm1, and ETTm2): These are automatically downloaded using the dataset_path specified in the notebooks.
2. Weather and Electricity datasets:
   • Download weather.zip and electricity.zip from this Google Drive folder.
   • Create a directory named datasets inside your imputation folder.
   • Extract the zip files into the datasets folder.

Required Directory Structure:

<imputation_folder>
└── datasets
    ├── electricity
    │   └── electricity.csv
    └── weather
        └── weather.csv

To set up the development environment for the TSFM Finetuning image, ensure you have the following prerequisites installed:

• GNU make
• git and git-lfs
• Python >=3.10, <3.13
• uv (package manager)
• zsh or bash
• docker or podman
• kubectl (only if deploying to a local Kubernetes cluster)

Install the dependencies using uv:

uv sync --locked --extra dev --editable