TimesFM2Forecaster

TimesFM-2.x forecaster via Hugging Face transformers.

Quickstart

from sktime.forecasting.timesfm2_forecaster import TimesFM2Forecaster

estimator = 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)

Parameters(12)

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

Examples

Simple zero-shot forecasting with TimesFM-2.5:
>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timesfm2_forecaster 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_forecaster 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_forecaster 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_forecaster 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_forecaster 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_forecaster 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 ])

References

1. [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