TimesFM2Forecaster

TimesFM2Forecaster

class TimesFM2Forecaster(model_path='google/timesfm-2.5-200m-transformers', config=None, device_map='cpu', dtype=None, quantization_config=None, forward_kwargs=None, peft_config=None, validation_split=0.2, training_args=None, compute_loss_func=None, compute_metrics=None, callbacks=None)[source]

TimesFM-2.x forecaster via Hugging Face transformers.

This forecaster wraps TimesFM-2 prediction models [1], [2] from Hugging Face and exposes them through the sktime forecasting interface.

Two primary workflows are supported:

1. fit for zero-shot inference setup (loads model and stores history).

2. pretrain for global fine-tuning on panel/hierarchical data.

Parameters:

model_pathstr, default=”google/timesfm-2.5-200m-transformers”

Hugging Face repository identifier or local path to a TimesFM checkpoint. Defaults to the TimesFM-2.5 checkpoint [3]; TimesFM-2.0 checkpoints are also supported [4]. If None, a model is created from config (or default transformers.TimesFmConfig).

configtransformers.PretrainedConfig or dict, optional (default=None)

Model configuration used for loading/initialization.

• If model_path is not None: passed to from_pretrained(..., config=config).

• If model_path is None: used to instantiate a model from configuration.

If provided as dict, the architecture entry (for example "TimesFmModelForPrediction" or "TimesFm2_5ModelForPrediction") is used to infer the config class.

device_mapstr, dict, int, or torch.device, default=”cpu”

Device placement following the transformers device_map naming convention, for example "cpu", "cuda", "cuda:0", or "auto".

dtypetorch.dtype or str, optional (default=None)

Data type used for model loading, following the transformers dtype convention, for example torch.float16, torch.bfloat16, or "auto".

quantization_configtransformers.quantizers.HfQuantizer, optional

Valid quantization configuration object compatible with pretrained loading through transformers.PreTrainedModel.from_pretrained [8]. Applied only when model_path is not None; ignored for config-only initialization with model_path=None.

forward_kwargsdict, optional (default=None)

Additional keyword arguments forwarded to model(...) during predict and predict_quantiles; see the TimesFM-2.0 [5] and TimesFM-2.5 [6] forward APIs.

peft_configpeft.PeftConfig, optional (default=None)

If provided, wraps the loaded pretrained base model with PEFT using peft.get_peft_model. Applied only when model_path is not None; ignored for config-only initialization with model_path=None.

validation_splitfloat or None, default=0.2

Fraction of data reserved for evaluation when pretrain is used. If None, no evaluation dataset is created.

training_argsdict, optional (default=None)

Keyword arguments used to construct transformers.TrainingArguments in pretrain [7].

compute_loss_funccallable, optional (default=None)

Optional custom loss function passed to transformers.Trainer [7].

compute_metricscallable or dict, optional (default=None)

Metrics callback(s) passed to transformers.Trainer [7].

callbackslist, optional (default=None)

Trainer callbacks passed to transformers.Trainer [7].

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

• Prediction is bounded by model.config.horizon_length. Requested forecast steps beyond this limit raise ValueError.

• Quantile prediction is only available for quantiles present in model.config.quantiles.

• device_map and dtype are supported for both pretrained loading and config-only initialization. For pretrained loading, they are passed to from_pretrained; for config-only initialization, they are applied after model construction.

• quantization_config and peft_config are applied only when loading a pretrained model from model_path. They are not used for config-only initialization with model_path=None.

• Loaded models are cached via a multiton helper keyed by model-loading inputs to avoid repeated model instantiation.

References

[1]

Das, A., Kong, W., Sen, R., and Zhou, Y. (2024). A Decoder-only Foundation Model for Time-series Forecasting. CoRR. https://arxiv.org/abs/2310.10688

[2]

Google Research TimesFM repository: https://github.com/google-research/timesfm

[3]

TimesFM-2.5 model card: https://huggingface.co/google/timesfm-2.5-200m-transformers

[4]

TimesFM-2.0 model card: https://huggingface.co/google/timesfm-2.0-500m-pytorch

[5]

TimesFM-2.0 forward API: https://huggingface.co/docs/transformers/en/model_doc/timesfm#transformers.TimesFmModelForPrediction.forward

[6]

TimesFM-2.5 forward API: https://huggingface.co/docs/transformers/en/model_doc/timesfm2_5#transformers.TimesFm2_5ModelForPrediction.forward

[7] (1,2,3,4)

Trainer/TrainingArguments docs: https://huggingface.co/docs/transformers/en/main_classes/trainer

[8]

Quantization docs: https://huggingface.co/docs/transformers/en/main_classes/quantization

Examples

Simple zero-shot forecasting with TimesFM-2.5:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2 import TimesFM2Forecaster
>>> y = load_airline()
>>> # By default, loads google/timesfm-2.5-200m-transformers.
>>> forecaster = TimesFM2Forecaster()
>>> # fit loads the model weights and stores the forecasting context.
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Simple zero-shot forecasting with TimesFM-2.0:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2 import TimesFM2Forecaster
>>> y = load_airline()
>>> # Loads google/timesfm-2.0-500m-pytorch.
>>> forecaster = TimesFM2Forecaster(
...     model_path="google/timesfm-2.0-500m-pytorch",
...     forward_kwargs={"forecast_context_len": 1024},
... )
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Quantile prediction:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2 import TimesFM2Forecaster
>>> y = load_airline()
>>> forecaster = TimesFM2Forecaster()
>>> forecaster.fit(y)
>>> # Select only quantiles available in the model config.
>>> y_pred = forecaster.predict_quantiles(
...     fh=[1, 2, 3],
...     alpha=[0.1, 0.5, 0.9],
... )

Reduced-memory inference with device placement, dtype, and quantization:

>>> import torch
>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2 import TimesFM2Forecaster
>>> from transformers import QuantoConfig
>>> y = load_airline()
>>> forecaster = TimesFM2Forecaster(
...     model_path="google/timesfm-2.5-200m-transformers",
...     device_map="auto",
...     dtype=torch.bfloat16,
...     quantization_config=QuantoConfig(weights="int8"),
... )
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Global training with a PEFT-wrapped pretrained model:

>>> from peft import LoraConfig
>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2 import TimesFM2Forecaster
>>> from sktime.utils._testing.hierarchical import _make_hierarchical
>>> y_panel = _make_hierarchical(
...     hierarchy_levels=(3,),
...     min_timepoints=128,
...     max_timepoints=400,
... )
>>> y = load_airline()
>>> forecaster = TimesFM2Forecaster(
...     model_path="google/timesfm-2.5-200m-transformers",
...     peft_config=LoraConfig(
...         r=8,
...         lora_alpha=32,
...         target_modules=["q_proj", "v_proj"],
...         lora_dropout=0.01,
...     ),
... )
>>> # Training happens on hierarchical data.
>>> forecaster.pretrain(y_panel)
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Global training on a randomly initialized model with custom config: device_map and dtype can still be applied in this path, but quantization_config and peft_config require a pretrained model_path and are ignored when model_path=None.

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2 import TimesFM2Forecaster
>>> from sktime.utils._testing.hierarchical import _make_hierarchical
>>> y_panel = _make_hierarchical(
...     hierarchy_levels=(3,),
...     min_timepoints=128,
...     max_timepoints=400,
... )
>>> y = load_airline()
>>> forecaster = TimesFM2Forecaster(
...     model_path=None,
...     config={
...         "architectures": ["TimesFmModelForPrediction"],
...         "num_hidden_layers": 1,
...         "hidden_size": 16,
...         "intermediate_size": 16,
...         "head_dim": 8,
...         "num_attention_heads": 4,
...         "context_length": 8,
...         "horizon_length": 6,
...         "patch_length": 2,
...         "quantiles": [0.25, 0.5, 0.75],
...     },
...     validation_split=0.1,
...     training_args={
...         "max_steps": 1,
...         "eval_steps": 1,
...     },
... )
>>> forecaster.pretrain(y_panel)
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

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.