TimesFMForecaster

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

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

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting. This method has been proposed in [2] and official code is given at [1].

TimesFM can be used either as a locally maintained package in sktime or directly from the source package, allowing users to leverage either their own environment or the latest updates from the source package timesfm.

The class offers two flags for handling dependencies and source package behavior:

use_source_package: Determines the source of the package code: False for the vendor fork in sktime with its default dependencies. True for the source package timesfm.
ignore_deps: If set, bypasses dependency checks entirely. This is for users who want to manage their environment manually.

Parameters:

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.

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]

Das, A., Kong, W., Sen, R., & Zhou, Y. (2024).

A decoder-only foundation model for time-series forecasting. CoRR.

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

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.