ProbTS: Benchmarking Point and Distributional Forecasting across Diverse Prediction Horizons

[ Paper | Benchmarking | Documentation ]

A wide range of industrial applications desire precise point and distributional forecasting for diverse prediction horizons. ProbTS serves as a benchmarking tool to aid in understanding how advanced time-series models fulfill these essential forecasting needs. It also sheds light on their advantages and disadvantages in addressing different challenges and unveil the possibilities for future research.

To achieve these objectives, ProbTS provides a unified pipeline that implements cutting-edge models from different research threads, including:

• Long-term point forecasting approaches, such as PatchTST, iTransformer, etc.
• Short-term probabilistic forecasting methods, such as TimeGrad, CSDI, etc.
• Recent time-series foundation models for universal forecasting, such as TimesFM, MOIRAI, etc.

Specifically, ProbTS emphasizes the differences in their primary methodological designs, including:

• Supporting point or distributional forecasts
• Using autoregressive or non-autoregressive decoding schemes for multi-step outputs

Available Models 🧩

ProbTS includes both classical time-series models, specializing in long-term point forecasting or short-term distributional forecasting, and recent time-series foundation models that offer zero-shot and arbitrary-horizon forecasting capabilities for new time series.

Classical Time-series Models

Fundation Models

Stay tuned for more models to be added in the future.

Setup :wrench:

Environment

ProbTS is developed with Python 3.10 and relies on PyTorch Lightning. To set up the environment:

# Create a new conda environment
conda create -n probts python=3.10
conda activate probts

# Install required packages
pip install .
pip uninstall -y probts # recommended to uninstall the root package (optional)

[Optional] For time-series foundation models, you need to install basic packages and additional dependencies:

# Create a new conda environment
conda create -n probts_fm python=3.10
conda activate probts_fm

# Git submodule
git submodule update --init --recursive

# Install additional packages for foundation models
pip install ".[tsfm]"
pip uninstall -y probts # recommended to uninstall the root package (optional)

# For MOIRAI, we fix the version of the package for better performance
cd submodules/uni2ts
git reset --hard fce6a6f57bc3bc1a57c7feb3abc6c7eb2f264301

Datasets

• Short-Term Forecasting: We use datasets from GluonTS. Configure the datasets using --data.data_manager.init_args.dataset {DATASET_NAME}. You can choose from multivariate or univariate datasets as per your requirement.

  # Multivariate Datasets
  ['exchange_rate_nips', 'electricity_nips', 'traffic_nips', 'solar_nips', 'wiki2000_nips']
  
  # Univariate Datasets
  ['tourism_monthly', 'tourism_quarterly', 'tourism_yearly', 'm4_hourly', 'm4_daily', 'm4_weekly', 'm4_monthly', 'm4_quarterly', 'm4_yearly', 'm5']

• Long-Term Forecasting: To download the long-term forecasting datasets, please follow these steps:

  bash scripts/prepare_datasets.sh "./datasets"

  Configure the datasets using --data.data_manager.init_args.dataset {DATASET_NAME} with the following list of available datasets:

  # Long-term Forecasting
  ['etth1', 'etth2','ettm1','ettm2','traffic_ltsf', 'electricity_ltsf', 'exchange_ltsf', 'illness_ltsf', 'weather_ltsf', 'caiso', 'nordpool']

  Note: When utilizing long-term forecasting datasets, you must explicitly specify the context_length and prediction_length parameters. For example, to set a context length of 96 and a prediction length of 192, use the following command-line arguments:

  --data.data_manager.init_args.context_length 96 \
  --data.data_manager.init_args.prediction_length 192 \

• Using Datasets from Monash Time Series Forecasting Repository: To use datasets from the Monash Time Series Forecasting Repository, follow these steps:

  1. Download the Dataset:

     • Navigate to the target dataset, such as the Electricity Hourly Dataset.
     • Download the .tsf file and place it in your local datasets directory (e.g., ./datasets).

  2. Configure the Dataset:

     • Use the following configuration to specify the dataset, file path, and frequency:

       --data.data_manager.init_args.dataset {DATASET_NAME} \
       --data.data_manager.init_args.data_path /path/to/data_file.tsf \
       --data.data_manager.init_args.freq {FREQ} 

  • Example Configuration:

    --data.data_manager.init_args.dataset monash_electricity_hourly \
    --data.data_manager.init_args.data_path ./datasets/electricity_hourly_dataset.tsf \
    --data.data_manager.init_args.freq H \
    --data.data_manager.init_args.context_length 96 \
    --data.data_manager.init_args.prediction_length 96 \
    --data.data_manager.init_args.multivariate true

  Note 1: Refer to the Pandas Time Series Offset Aliases for the correct frequency values ({FREQ}) to use in your configuration.

  Note 2: You can adjust the test instance sampling using the --data.data_manager.init_args.test_rolling_length parameter. The default value is 96.

Checkpoints for Foundation Models

Download the checkpoints with the following command (details can be found here):

bash scripts/prepare_tsfm_checkpoints.sh # By downloading, you agree to the original licenses

Quick Start :rocket:

Specify --config with a specific configuration file to reproduce results of point or probabilistic models on commonly used long- and short-term forecasting datasets. Configuration files are included in the config folder.

To run models:

bash run.sh

Experimental results reproduction:

• Long-term Forecasting:

  bash scripts/reproduce_ltsf_results.sh

• Short-term Forecasting:

  bash scripts/reproduce_stsf_results.sh

• Time Series Foundation Models:

  bash scripts/reproduce_tsfm_results.sh

Short-term Forecasting Configuration

For short-term forecasting scenarios, datasets and corresponding context_length and prediction_length are automatically obtained from GluonTS. Use the following command:

python run.py --config config/path/to/model.yaml \
                --data.data_manager.init_args.path /path/to/datasets/ \
                --trainer.default_root_dir /path/to/log_dir/ \
                --data.data_manager.init_args.dataset {DATASET_NAME}

See full DATASET_NAME list:

from gluonts.dataset.repository import dataset_names
print(dataset_names)

Long-term Forecasting Configuration

For long-term forecasting scenarios, context_length and prediction_length must be explicitly assigned:

python run.py --config config/path/to/model.yaml \
                --data.data_manager.init_args.path /path/to/datasets/ \
                --trainer.default_root_dir /path/to/log_dir/ \
                --data.data_manager.init_args.dataset {DATASET_NAME} \
                --data.data_manager.init_args.context_length {CTX_LEN} \
                --data.data_manager.init_args.prediction_length {PRED_LEN} 

DATASET_NAME options:

['etth1', 'etth2','ettm1','ettm2','traffic_ltsf', 'electricity_ltsf', 'exchange_ltsf', 'illness_ltsf', 'weather_ltsf', 'caiso', 'nordpool']

Benchmarking :balance_scale:

By utilizing ProbTS, we conduct a systematic comparison between studies that focus on point forecasting and those aimed at distributional estimation, employing various forecasting horizons and evaluation metrics. For more details

• Short-term & Long-term Forecasting Benchmarking
• Evaluating Time Series Foundation Models

Documentation :open_book:

For detailed information on configuration parameters and model customization, please refer to the documentation.

Key Configuration Parameters

• Adjust model and data parameters in run.sh. Key parameters include:

• To print the full pipeline configuration to a file:

  python run.py --print_config > config/pipeline_config.yaml

Acknowledgement 🌟

Special thanks to the following repositories for their open-sourced code bases and datasets.

Tools/Packages

• GluonTS
• PyTorch-TS
• TSLib
• NeuralForecast

Official Implementations

Classical Time-series Models

• Autoformer
• N-HiTS
• NLinear, DLinear
• TimesNet
• RevIN
• PatchTST
• iTransformer
• GRU NVP, GRU MAF, Trans MAF, TimeGrad
• CSDI
• TSDiff

Time-series Foundation Models

• MOIRAI
• Chronos
• Lag-Llama
• TimesFM
• Timer
• UniTS
• ForecastPFN
• TTM

Citing ProbTS 🌟

If you have used ProbTS for research or production, please cite it as follows.

@article{zhang2023probts,
  title={{ProbTS}: Benchmarking Point and Distributional Forecasting across Diverse Prediction Horizons},
  author={Zhang, Jiawen and Wen, Xumeng and Zhang, Zhenwei and Zheng, Shun and Li, Jia and Bian, Jiang},
  journal={arXiv preprint arXiv:2310.07446},
  year={2023}
}