TimesFM3Forecaster

class 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)[source]

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.

Parameters:

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

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.

References

[1]

https://github.com/google-research/timesfm/

[2]

https://research.google/blog/timesfm-3-a-zero-shot-foundation-model-for-multivariate-forecasting/

[3] (1,2,3)

ModelConfig fields (upstream source): https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/timesfm3_forecaster.py

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

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 license information for TimesFM 3.0 pretrained weights.
`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.