ibm-granite/granite-timeseries-ensemble-r1

Granite Timeseries Ensemble R1

Granite Timeseries Ensemble R1 is an extensible framework for combining quantile forecasts from multiple pretrained time-series models. Its default configuration brings together four complementary, permissively licensed Granite checkpoints: PatchTST-FM-r1, PatchTST-FM-r2, FlowState-r1.1, and TTM-r3.

The ensemble is designed to improve overall forecasting performance and reduce the need to select a single model architecture in advance. It provides two aggregation methods: uniform probability pooling as the simple, recommended default, and adaptive interquartile-range (IQR) weighting as an alternative to evaluate on representative data.

This repository contains reusable ensemble recipes rather than merged model weights. Member checkpoints are downloaded from their own Hugging Face repositories at runtime, and the common forecasting interface can be extended with other compatible models and aggregation methods.

Why ensemble?

Forecasting models have different inductive biases, and no single architecture performs best across every dataset, context length, and forecast horizon. Granite Timeseries Ensemble combines forecasts from complementary model families, reducing reliance on the assumptions and failure modes of any one architecture.

The default Probabilistic Ensemble uses uniform aggregation: it requires no fitted combination weights or historical validation data. This makes the aggregation simple, reproducible, and less exposed to estimation error. Equal-weight combinations are often surprisingly competitive with combinations fitted to historical performance—a result known as the forecast combination puzzle and explained in part by the bias-variance trade-off in estimated weights.

Adding diverse, reasonably accurate members can dilute model-specific errors and improve robustness. Adding weak or highly correlated members is not guaranteed to help, so member selection should still be validated for the intended application. Learned aggregation may improve performance when representative training data are available. These recipes instead prioritize a strong accuracy-simplicity trade-off for zero-shot use.

Ensemble methods

Probabilistic Ensemble

The default linear_pool method gives each member equal influence, pools its quantile values in probability space, and extracts the requested empirical quantiles from the combined values. It does not learn ensemble weights.

Interquartile Range Ensemble

The iqr_weighted method estimates each member's dispersion from its interquartile range. Members with narrower intervals receive greater weight when corresponding quantiles are combined. It does not fit weights from historical forecast errors. Isotonic regression enforces nondecreasing output quantiles.

A narrower interval does not necessarily imply greater accuracy or better calibration. Validate both methods on representative application data.

Granite-only configuration

Both evaluated methods use the same four Granite checkpoints:

| Member | Family | Checkpoint | |---|---|---| | Granite PatchTST-FM-r1 | Transformer | `ibm-granite/granite-timeseries-patchtst-fm-r1` | | Granite PatchTST-FM-r2 | Conformer | `ibm-granite/granite-timeseries-patchtst-fm-r2` | | Granite FlowState-r1.1 | State-space model | `ibm-granite/granite-timeseries-flowstate-r1` | | Granite TTM-r3 | Lightweight mixer | `ibm-granite/granite-timeseries-ttm-r3` |

The root config.json is the recommended recipe. The root recipe returns nine quantiles: 0.1, 0.2, …, 0.9, and uses the 0.5 quantile as its point forecast. TTM revisions are selected dynamically from the requested context and forecast horizon.

Installation and usage

pip install "granite-tsfm>=0.3.10"

Minimal example: recommended defaults

import pandas as pd

from tsfm_public.models.ensemble.modeling_ensemble import QuantileEnsembleForecaster

df = pd.read_csv(
"https://raw.githubusercontent.com/zhouhaoyi/ETDataset/main/ETT-small/ETTh1.csv",
parse_dates=["date"],
)

ensemble = QuantileEnsembleForecaster.from_pretrained(
"ibm-granite/granite-timeseries-ensemble-r1",
)

result = ensemble(
df.tail(1024),
timestamp_column="date",
target_columns=["OT"],
context_length=1024,
prediction_length=24,
)

print(result.predicted) # Median forecasts
print(result.predicted_quantiles) # Quantile forecasts

Advanced example: user-guided configuration

Evaluated alternatives using different aggregation methods and model combinations are available as recipe subfolders in this repository. Pass the desired path through the subfolder argument.

| Subfolder | Members | Method | Intended use | |---|---|---|---| | recipes/granite-linear | Granite-only | Probabilistic Ensemble | Recommended default | | recipes/granite-iqr | Granite-only | Interquartile Range Ensemble | Permissively licensed alternative | | recipes/expanded-linear | Granite and IBM Research | Probabilistic Ensemble | Research comparison | | recipes/expanded-iqr | Granite and IBM Research | Interquartile Range Ensemble | Research comparison |

The optional expanded recipes reference IBM Research checkpoints with separate licensing and usage conditions, including non-commercial or research-use restrictions. Review each member model card before using these recipes.

Load an evaluated alternative with subfolder, or modify the configuration before model checkpoints are loaded:

from tsfm_public.models.ensemble.configuration_ensemble import ProbabilisticEnsembleConfig
from tsfm_public.models.ensemble.modeling_ensemble import QuantileEnsembleForecaster

config = ProbabilisticEnsembleConfig.from_pretrained(
"ibm-granite/granite-timeseries-ensemble-r1",
subfolder="recipes/granite-iqr",
)

# Optional advanced changes.
config.iqr_weighted_options = {
"temperature": 0.8,...