Universal Forecasting Library

The universal-forecasting-library is a unified, "zero-shot" forecasting framework designed to provide a seamless interface for multiple time-series forecasting architectures. It abstracts away the complexity of data preparation, feature engineering, and hyperparameter tuning.

Installation

You can install the package directly via pip. By default, this performs a lightweight installation (uses scikit-learn and lightgbm, avoiding heavy deep learning models or C++ compilation).

# Lightweight Install (Linear & Tree Ensemble)
pip install universal-forecasting-library

# Full Install (Includes TSFM and StatsForecast)
pip install universal-forecasting-library[tsfm,stats]

Available Forecasters

The library uses an orchestration layer (UniversalForecaster) to dispatch work to specific forecasting engines. Here is a quick summary of what each engine does:

• LinearForecaster (linear): Fast baseline. Uses scikit-learn (Ridge regression) coupled with automatic feature engineering. Installs flawlessly everywhere.
• StatsForecaster (stats): Fast, classical statistical models. It wraps StatsForecast (AutoARIMA, AutoETS, AutoTheta, and SeasonalNaive). Requires the [stats] installation.
• TreeEnsembleForecaster (tree_ensemble): Machine learning approach. Uses LightGBM wrapped in a multi-output RegressorChain. It automatically builds complex features (lags, rolling stats, holidays) and predicts the entire future horizon in one shot. Best for complex datasets where feature engineering shines.
• TSFMForecaster (tsfm): Deep learning approach. Wraps Hugging Face's Time Series Foundation Models (like TinyTimeMixer). Uses massive pre-trained neural networks to perform zero-shot forecasting on your data. Best for discovering complex patterns without manual feature tuning.

Usage Guide

Initialization

Import the orchestrator and initialize your forecasting session:

from universal_forecaster import UniversalForecaster

forecast = UniversalForecaster(
    input_windows=36,               # Lookback window (used primarily by TSFM)
    horizon=18,                     # The number of steps into the future to predict
    forecast_type='tree_ensemble',  # Choose from: 'linear', 'tree_ensemble', 'tsfm'
    test_type='model',              # (Optional) 'model' to test architectures, 'param' for hyperparameters
    tsfm_model_path="./local_ttm"   # Path to local foundation model weights (if using TSFM)
)

Data Format Requirements

The input data must be a Pandas DataFrame containing at minimum:

• ds: The datetime column.
• y: The numeric target variable to forecast.
• unique_id (Optional): An identifier for multi-series forecasting. If omitted, a dummy ID is injected automatically.

Training & Predicting

import pandas as pd

# Example Data
df_train = pd.DataFrame({
    'ds': pd.date_range('2023-01-01', periods=100),
    'y': range(100)
})

# 1. Fit the forecaster. 
# If test_type is set, this will automatically hold out 10% of data, evaluate configurations, and retrain on 100%.
forecast.fit(df_train)

# 2. Predict the horizon
# Returns a DataFrame with an 'Ensemble' column containing the predictions
predictions_df = forecast.predict()
print(predictions_df)

Advanced Features

1. Auto-Testing & Model Selection (test_type)

The framework can automatically evaluate multiple configurations on a chronologically held-out 10% validation set, pick the best one using Mean Absolute Error (MAE), and seamlessly retrain on the full dataset.

• test_type='model': Tests between different architectural families (e.g., linear vs tree_ensemble).
• test_type='param': Tests different hyperparameter grids for a specific architecture.

2. Automated Feature Engineering

When using non-linear models (like tree_ensemble), the UniversalForecaster automatically generates:

• Cyclical Calendar Features: Sine/Cosine transformations of day-of-week, month, and hour.
• Holiday Features: Automatic integration with holidays (currently configured for Indonesia).
• Lag Features: Auto-scaled lag features based on the detected frequency.
• Rolling Statistics: Rolling mean and standard deviation (volatility) to capture recent trends.