Forecaster

TimesFMForecaster

TimesFM (Time Series Foundation Model) for Zero-Shot Forecasting.

Quickstart

python

from sktime.forecasting.timesfm import TimesFMForecaster

estimator = TimesFMForecaster(context_len=None, horizon_len=128, freq=0, repo_id='google/timesfm-1.0-200m', input_patch_len=32, output_patch_len=128, num_layers=20, model_dims=1280, per_core_batch_size=32, backend='cpu', verbose=False, broadcasting=False, use_source_package=False, ignore_deps=False)

Parameters(14)

context_lenint, optional (default=None)

The length of the input context sequence. If set to None, the context length is automatically computed as the smallest multiple of input_patch_len that is larger than the length of the input time series y. It should be a multiple of input_patch_len (32). The maximum context length currently supported is 512, but this can be increased in future releases. The input time series can have any context length, and padding or truncation will be handled by the model’s inference code if necessary.

horizon_lenint, optional (default=128)

The length of the forecast horizon. If set to None, the forecast horizon is dynamically determined based on the provided forecasting horizon fh, if available. This can be set to any value, although it is generally recommended to keep it less than or equal to context_len for optimal performance. The model will still function if horizon_len exceeds context_len.

freqint, optional (default=0)

The frequency category of the input time series.

0: High frequency, long horizon time series (e.g., daily data and above).
1: Medium frequency time series (e.g., weekly, monthly data).
2: Low frequency, short horizon time series (e.g., quarterly, yearly data).

You can treat this parameter as a free parameter depending on your specific use case, although it is recommended to follow these guidelines for optimal results.

repo_idstr or None, optional (default=”google/timesfm-1.0-200m”)

The identifier for the model repository. The default model is the 200M parameter version. If None, the model is initialized from random weights and no checkpoint is downloaded or restored. Random initialization is supported for the vendored sktime TimesFM implementation, i.e. when use_source_package=False.

input_patch_lenint, optional (default=32)

The fixed length of input patches that the model processes. This parameter is fixed to 1280 for the 200M model and should not be changed.

output_patch_lenint, optional (default=128)

The fixed length of output patches that the model generates. This parameter is fixed to 1280 for the 200M model and should not be changed.

num_layersint, optional (default=20)

The number of layers in the model architecture. This parameter is fixed to 1280 for the 200M model and should not be changed.

model_dimsint, optional (default=1280)

The dimensionality of the model. This parameter is fixed to 1280 for the 200M model and should not be changed.

per_core_batch_sizeint, optional (default=32)

The batch size to be used per core during model inference.

backendstr, optional (default=”cpu”)

The computational backend to be used, which can be one of “cpu”, “gpu”, or “tpu”. This setting is case-sensitive.

verbosebool, optional (default=False)

Whether to print detailed logs during execution.

broadcastingbool, default=False

if True, multiindex data input will be broadcasted to single series. For each single series, one copy of this forecaster will try to fit and predict on it. The broadcasting is happening inside automatically, from the outerside api perspective, the input and output are the same, only one multiindex output from predict.

use_source_packagebool, default=False

If True, the model will be loaded directly from the source package timesfm. This also enforces a version bound for timesfm to be <1.2.0. This setting is useful if the latest updates from the source package are needed, bypassing the local version of the package.

ignore_depsbool, default=False

If True, dependency checks will be ignored, and the user is expected to handle the installation of required packages manually. If False, the class will enforce the default dependencies required for the vendor library or the pypi package, as described above, via use_source_package.

Examples

>>> from sktime.forecasting.timesfm import TimesFMForecaster
>>> from sktime.datasets import load_airline
>>> y = load_airline ()
>>> forecaster = TimesFMForecaster (
... context_len = 32,
... horizon_len = 8,
... )
>>> forecaster. fit (y, fh = [1, 2, 3 ])
>>> y_pred = forecaster. predict ()
>>> from sktime.forecasting.timesfm import TimesFMForecaster
>>> from sktime.datasets import load_tecator
>>> 
>>> # load multi-index dataset
>>> y = load_tecator (
... return_type = "pd-multiindex",
... return_X_y = False
... )
>>> y. drop (['class_val' ], axis = 1, inplace = True)
>>> 
>>> # global forecasting on multi-index dataset
>>> forecaster = TimesFMForecaster (
... context_len = 32,
... horizon_len = 8,
... )
>>> 
>>> # fit sets the context, predict uses it
>>> forecaster. fit (y, fh = [1, 2, 3 ])
>>> y_pred = forecaster. predict ()

References

[1 ] https://github.com/google-research/timesfm [2 ] Das, A., Kong, W., Sen, R., & Zhou, Y. (2024). A decoder-only foundation model for time-series forecasting. CoRR.