Toto2Forecaster

Toto2Forecaster

class Toto2Forecaster(model_path: str = 'Datadog/Toto-2.0-22m', decode_block_size: int | None = None, device: str | None = None, seed: int | None = None)[source]

Toto 2.0 foundation model forecaster for zero-shot forecasting.

Direct interface to the forecaster from DataDog/toto [1].

Toto 2.0 is the latest generation, featuring a u-μP-scaled transformer with alternating time/variate attention and quantile-based probabilistic forecasting. It supports zero-shot forecasting and can process multiple variables, generating both point forecasts and uncertainty estimates via a quantile head. It supports variable prediction horizons and context lengths.

Parameters:

model_pathstr, optional (default=”Datadog/Toto-2.0-22m”)

Path to the Toto 2.0 HuggingFace model. Available checkpoints include “Datadog/Toto-2.0-4m”, “Datadog/Toto-2.0-22m”, “Datadog/Toto-2.0-313m”, “Datadog/Toto-2.0-1B”, and “Datadog/Toto-2.0-2.5B”.

decode_block_sizeint or None, optional (default=None)

Decoding strategy. None (single forward pass) is faster and best for short horizons (used for all leaderboard results). A value such as 768 (block decode) gives better long-term stability for horizons >~1000. If set, must be a multiple of the model’s patch size.

devicestr or None, optional (default=None)

Device on which to run the model (‘cpu’ or ‘cuda’). If None, uses ‘cuda’ when available, otherwise ‘cpu’.

seedint or None, optional (default=None)

Random seed for reproducibility; if None, a random seed is drawn.

Attributes:

cutoff

Cut-off = “present time” state of forecaster.

fh

Forecasting horizon that was passed.

is_fitted

Whether fit has been called.

state

State of the estimator.

Notes

Toto-2 emits forecasts at a fixed grid of quantile levels (0.1, 0.2, …, 0.9). predict_proba returns a skpro HistogramQPD built from this grid: it interpolates linearly between adjacent grid quantiles, and (via tails="mass") clamps levels outside [0.1, 0.9] to the nearest grid quantile (e.g. a 0.05 request returns the 0.1 quantile, so intervals wider than 80% coverage saturate). Interpolation assumes the grid quantiles are monotone in the level.

References

[1]

https://github.com/DataDog/toto

Examples

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.toto2 import Toto2Forecaster
>>> y = load_airline()

Zero-shot forecasting with the default model:

>>> forecaster = Toto2Forecaster()
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Probabilistic forecasting. Toto-2 emits a fixed quantile grid (0.1, …, 0.9); other levels come from a HistogramQPD (linear interpolation, clamped tails):

>>> forecaster = Toto2Forecaster(
...     model_path="Datadog/Toto-2.0-4m"
... )
>>> forecaster.fit(y)
>>> intervals = forecaster.predict_interval(
...     fh=[1, 2, 3], coverage=0.9
... )

Long-horizon forecasting with block decoding. Block decoding only engages when the horizon spans multiple patches (i.e. exceeds decode_block_size):

>>> forecaster = Toto2Forecaster(
...     model_path="Datadog/Toto-2.0-22m", decode_block_size=768
... )
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=list(range(1, 1001)))

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