T0Forecaster

class T0Forecaster(model_path: str | None = 'theforecastingcompany/t0-alpha', device: str | None = None, context_length: int | None = None, random_state=None, license_accepted: bool = False, ignore_deps: bool = False)[source]

Interface to the T0 zero-shot forecaster by The Forecasting Company.

T0 is a pretrained time series foundation model for zero-shot forecasting, released by The Forecasting Company [1], [2]. The model is loaded from a pretrained checkpoint and applied without task-specific training: the context is stored in fit and forecasts are produced zero-shot in predict.

T0 natively supports known-future covariates (exogenous data), passed to the underlying model via its future_covariates argument. These covariates must span the context window and the forecast horizon, so exogenous data must be provided both in fit (past values) and predict (future values).

Capabilities and behaviour:

Multivariate - a multi-column y is forecast column-by-column, each as an independent series (capability:multivariate=True).
Probabilistic - T0 returns quantiles natively, so predict_quantiles, predict_interval and (by default) predict_var are available (capability:pred_int=True); predict returns the median (0.5 quantile).
Exogenous - known-future covariates are conditioned on, but must cover every step 1..max(fh), so a non-contiguous fh requires contiguous X (capability:non_contiguous_X=False).
Missing values - NaN entries in the context are treated as missing (capability:missing_values=True).
In-sample - not supported; fh must be strictly in the future (capability:insample=False).

Parameters:

model_pathstr or None, default=”theforecastingcompany/t0-alpha”: Path to the T0 HuggingFace model checkpoint. The default checkpoint is a gated model on the HuggingFace Hub, so downloading it requires accepting the vendor’s terms on the model page and authenticating with a HuggingFace token. If None, a small randomly-initialized T0 model is built locally (from the tfc-t0 model code) instead of downloading any checkpoint - this produces untrained (meaningless) forecasts and is intended only for testing or offline use.
devicestr or None, default=None: Device for inference, e.g., “cpu”, “cuda”, or “mps”. If None, uses “cuda” when a CUDA device is available, otherwise “cpu”.
context_lengthint or None, default=None: Maximum context length for inference. If None, the full context is used.
random_stateint, RandomState instance or None, optional, default=None: Random seed for reproducibility, sklearn-compatible. If None, no seeding is applied and the ambient random state is used. If set, inference runs in a forked RNG seeded from random_state, leaving the global RNG untouched. T0’s inference is deterministic, so this does not change the forecast; it is accepted for interface consistency.
license_acceptedbool, optional, default=False: Whether the user has read and accepted the license terms of the tfc-t0 package and the T0 models, licensed by The Forecasting Company. Must be set to True to use T0Forecaster; otherwise fit raises. To view the license, call T0Forecaster.print_license(); the model card and gated-access terms are at https://huggingface.co/theforecastingcompany/t0-alpha.
ignore_depsbool, optional, default=False: If True, dependency checks are skipped.

Attributes:

model_t0.T0Forecaster: The underlying T0 model used for forecasting.

References

[1]

https://github.com/theforecastingcompany/tfc-t0

[2]

https://huggingface.co/theforecastingcompany/t0-alpha

Examples

Univariate point forecast (zero-shot):

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.t0 import T0Forecaster
>>> from sktime.split import temporal_train_test_split
>>> y = load_airline()
>>> y_train, y_test = temporal_train_test_split(y, test_size=12)
>>> forecaster = T0Forecaster(license_accepted=True)
>>> forecaster.fit(y_train)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Probabilistic forecast (T0 returns quantiles natively):

>>> y_quantiles = forecaster.predict_quantiles(
...     fh=[1, 2, 3], alpha=[0.1, 0.5, 0.9]
... )
>>> y_interval = forecaster.predict_interval(
...     fh=[1, 2, 3], coverage=0.9
... )

Forecast with known-future exogenous data (X in both fit and predict):

>>> from sktime.datasets import load_longley
>>> y, X = load_longley()
>>> y_tr, y_te, X_tr, X_te = temporal_train_test_split(y, X, test_size=3)
>>> forecaster = T0Forecaster(license_accepted=True)
>>> forecaster.fit(y_tr, X=X_tr)
>>> y_pred = forecaster.predict(fh=[1, 2, 3], X=X_te)

Multivariate forecast on a real dataset (each column forecast independently):

>>> from sktime.datasets import load_longley
>>> _, y_multi = load_longley()  # 5-column economic indicators frame
>>> y_multi_train = y_multi.iloc[:-3]
>>> forecaster = T0Forecaster(license_accepted=True)
>>> forecaster.fit(y_multi_train)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Methods

`check_is_fitted`([method_name])	Check if the estimator has been fitted.
`clone`()	Obtain a clone of the object with same hyper-parameters and config.
`clone_tags`(estimator[, tag_names])	Clone tags from another object as dynamic override.
`create_test_instance`([parameter_set])	Construct an instance of the class, using first test parameter set.
`create_test_instances_and_names`([parameter_set])	Create list of all test instances and a list of names for them.
`fit`(y[, X, fh])	Fit forecaster to training data.
`fit_predict`(y[, X, fh, X_pred])	Fit and forecast time series at future horizon.
`get_class_tag`(tag_name[, tag_value_default])	Get class tag value from class, with tag level inheritance from parents.
`get_class_tags`()	Get class tags from class, with tag level inheritance from parent classes.
`get_config`()	Get config flags for self.
`get_fitted_params`([deep])	Get fitted parameters.
`get_param_defaults`()	Get object's parameter defaults.
`get_param_names`([sort])	Get object's parameter names.
`get_params`([deep])	Get a dict of parameters values for this object.
`get_pretrained_params`([deep])	Get pretrained parameters of this estimator.
`get_tag`(tag_name[, tag_value_default, ...])	Get tag value from instance, with tag level inheritance and overrides.
`get_tags`()	Get tags from instance, with tag level inheritance and overrides.
`get_test_params`([parameter_set])	Return testing parameter settings for the estimator.
`is_composite`()	Check if the object is composed of other BaseObjects.
`load_from_path`(serial)	Load object from file location.
`load_from_serial`(serial)	Load object from serialized memory container.
`predict`([fh, X])	Forecast time series at future horizon.
`predict_interval`([fh, X, coverage])	Compute/return prediction interval forecasts.
`predict_proba`([fh, X, marginal])	Compute/return fully probabilistic forecasts.
`predict_quantiles`([fh, X, alpha])	Compute/return quantile forecasts.
`predict_residuals`([y, X])	Return residuals of time series forecasts.
`predict_var`([fh, X, cov])	Compute/return variance forecasts.
`pretrain`(y[, X, fh])	Pre-train forecaster on panel (global) data.
`print_license`()	Print the license and notice shipped with the `tfc-t0` package.
`reset`()	Reset the object to a clean post-init state.
`save`([path, serialization_format])	Save serialized self to bytes-like object or to (.zip) file.
`score`(y[, X, fh])	Scores forecast against ground truth, using MAPE (non-symmetric).
`set_config`(**config_dict)	Set config flags to given values.
`set_params`(**params)	Set the parameters of this object.
`set_random_state`([random_state, deep, ...])	Set random_state pseudo-random seed parameters for self.
`set_tags`(**tag_dict)	Set instance level tag overrides to given values.
`update`(y[, X, update_params])	Update cutoff value and, optionally, fitted parameters.
`update_predict`(y[, cv, X, update_params, ...])	Make predictions and update model iteratively over the test set.
`update_predict_single`([y, fh, X, update_params])	Update model with new data and make forecasts.