Back to models
Forecaster

TimesFM3Forecaster

API referenceSource
Pred intMissing valuesExogenousMultivariate

Interface to Google TimesFM 3 zero-shot forecaster.

TimesFM 3 is a pretrained multivariate time series foundation model supporting native joint forecasting of multiple targets with past-only and past-and-future covariates. See [1] and [2] for details.

Exogenous variables are supplied via X in fit and predict. The split between past-only and past-and-future covariates is inferred from the data: fit-time X columns that are also present in the predict-time X are treated as past-and-future covariates (their future values are read from the predict-time X for every step 1 .. max(fh) ahead of the cutoff); fit-time X columns absent from the predict-time X are treated as past-only covariates.

Point forecasts use the upstream median quantile. Probabilistic forecasts are available through predict_quantiles. Native checkpoint levels 0.1, 0.2, ..., 0.9 are returned exactly; intermediate levels are linearly interpolated, and levels outside that range are clamped to the nearest native quantile.

Quickstart

python
from sktime.forecasting.timesfm3 import TimesFM3Forecaster

estimator = TimesFM3Forecaster(model_path: str='google/timesfm-3.0-pytorch', device: str | None=None, batch_size: int=4, config: dict | None=None, use_symmetric_averaging: bool=False, make_positive: bool=False, use_znorm: bool=False, padding_mode: str='none', license_accepted: bool=False, ignore_deps: bool=False)

Parameters(10)

model_pathstr, default=”google/timesfm-3.0-pytorch”
Hugging Face repository id or local checkpoint path for TimesFM 3.
devicestr or None, default=None

PyTorch device string, e.g. "cpu" or "cuda". If None, upstream selects CUDA when available, otherwise CPU.

batch_sizeint, default=4

Batch size passed to upstream ModelConfig.per_core_batch_size [3].

configdict or None, default=None

Additional keyword arguments forwarded to upstream ModelConfig [3]. Commonly useful keys include input_patch_length (int), output_patch_length (int), quantiles (list of float), use_stitching (bool), use_linear_detrending (bool), linear_detrending_threshold (float), use_iterative_cpm_revin (bool), use_variate_attention (bool), use_sdpa (bool), and the Hugging Face Hub download keys cache_dir, force_download, token, revision and local_files_only. See [3] for the full list. The reserved keys checkpoint_path, device and per_core_batch_size are set via the model_path, device and batch_size parameters and must not appear here.

use_symmetric_averagingbool, default=False
Whether to enable upstream symmetric averaging during inference.
make_positivebool, default=False
Whether to clip forecasts to be non-negative when the context is non-negative.
use_znormbool, default=False
Whether to apply per-variate z-normalization upstream during inference.
padding_modestr, default=”none”

Upstream padding mode for past-and-future covariates. Supported values are "none" and "edge".

license_acceptedbool, default=False

Must be True to use the default pretrained weights, which are distributed under the TimesFM non-commercial license. Call TimesFM3Forecaster.print_license() for details.

ignore_depsbool, default=False

If True, skip soft-dependency checks (for testing).

Examples

Univariate point forecast:
>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm3 import TimesFM3Forecaster
>>> from sktime.split import temporal_train_test_split
>>> y = load_airline ()
>>> y_train, y_test = temporal_train_test_split (y, test_size = 12)
>>> forecaster = TimesFM3Forecaster (license_accepted = True)
>>> forecaster. fit (y_train)
>>> y_pred = forecaster. predict (fh = [1, 2, 3 ]) Multivariate forecast:
>>> import pandas as pd
>>> y_multi = pd. DataFrame ({ "a": [1, 2, 3, 4 ], "b": [4, 3, 2, 1 ]})
>>> forecaster = TimesFM3Forecaster (license_accepted = True)
>>> forecaster. fit (y_multi)
>>> y_pred = forecaster. predict (fh = [1, 2 ]) Forecast with mixed past-only and past-and-future covariates. The split is inferred from the data: past_only appears only in the fit-time X, while future_known appears in both the fit-time and predict-time X:
>>> y = pd. Series ([1.0, 2.0, 3.0, 4.0 ])
>>> X = pd. DataFrame ({ "past_only": [0.1, 0.2, 0.3, 0.4 ],
... "future_known": [1.0, 1.0, 1.0, 1.0 ]})
>>> forecaster = TimesFM3Forecaster (license_accepted = True)
>>> forecaster. fit (y, X = X)
>>> X_future = pd. DataFrame ({ "future_known": [2.0, 2.0 ]})
>>> y_pred = forecaster. predict (fh = [1, 2 ], X = X_future) Quantile forecast:
>>> y_quantiles = forecaster. predict_quantiles (
... fh = [1, 2 ], alpha = [0.1, 0.5, 0.9 ]
... )

References