Forecasting Library Documentation

The forecastingLibrary 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.

Core Architecture

The library is built around an orchestration layer (UniversalForecaster) that delegates tasks to specific forecasting engines that all inherit from a common interface (BaseForecaster).

• UniversalForecaster: The main entry point. It handles data validation, extensive automated feature engineering, train/test splitting for evaluation, and engine dispatch.
• BaseForecaster: The abstract base class that defines the fit() and predict() contract for all engines.
• Engines:
  • LinearForecaster: Wraps Nixtla's StatsForecast (AutoARIMA, AutoETS, AutoTheta, SeasonalNaive). Extremely fast and parallelized.
  • TreeEnsembleForecaster: A multi-output tree-based model using LightGBM wrapped in a RegressorChain. Uses shifted targets to predict the entire horizon in one shot without recursive loops.
  • TSFMForecaster: Wraps Hugging Face's Time Series Foundation Models (e.g., TinyTimeMixer) for deep learning-based forecasting.

Key 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 100% 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 (e.g., different n_estimators for tree_ensemble).

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 (Daily, Weekly, Monthly, Hourly).
• Rolling Statistics: Rolling mean and standard deviation (volatility) to capture recent trends.

Usage Guide

Initialization

from lib.forecastingLibrary.UniversalForecaster 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',  # 'linear', 'tree_ensemble', 'tsfm' (or None to let test_type decide)
    test_type='model',              # 'model' to test architectures, 'param' to test 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, the LinearForecaster will automatically inject a dummy ID.

Training & Predicting

# 1. Fit the forecaster. 
# If test_type is set, this will automatically hold out 10% of data, test, 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()

Adding New Engines

To add a new forecasting engine:

1. Create a new class inheriting from BaseForecaster.
2. Implement the fit(self, df) method. Ensure it does not modify the original df directly (use .copy()).
3. Implement the predict(self) method to return a DataFrame containing at least an 'Ensemble' column.
4. Add the new engine to the _available_forecast_types and _init_engine dispatch dictionary in UniversalForecaster.