TimerS1Forecaster

class TimerS1Forecaster(model_path='bytedance-research/Timer-S1', config=None, device_map='cpu', dtype=None, quantization_config=None, forward_kwargs=None, deterministic=False)[source]

Timer-S1 forecaster via Hugging Face transformers.

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

The primary workflow is fit for zero-shot inference setup, which loads the model and stores history. It does not train or fine-tune model weights. Passing model_path=None initializes a Timer-S1 model from config instead of loading pretrained weights. These random weights cannot be trained through this estimator at the moment and are mainly useful for tests or local experimentation.

Parameters:

model_pathstr, default=”bytedance-research/Timer-S1”: Hugging Face repository identifier or local path to a Timer-S1 checkpoint. If None, a model is created from config.
configTimerS1Config or dict, optional (default=None): Model configuration used when model_path=None. If provided as a dict, it is converted with TimerS1Config.from_dict. If None and model_path=None, the default TimerS1Config is used. This path creates random weights; the estimator does not currently provide training for those weights.
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 transformers.PreTrainedModel.from_pretrained [3].
forward_kwargsdict, optional (default=None): Additional keyword arguments forwarded to model.generate(...) during predict and predict_quantiles.
deterministicbool, default=False: Whether point predictions should reset the transformers random seed before generation. Currently this is applied in predict methods.

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

Timer-S1 training is currently not supported, but may be added in future. The estimator performs only zero-shot forecasting from a loaded or randomly initialized model.
Quantile prediction via predict_quantiles is only available for quantiles present in model.config.quantiles.
Distributional prediction via predict_proba returns a skpro HistogramQPD parameterized by the native quantile grid model.config.quantiles: it interpolates linearly between adjacent native quantiles, and (via tails="mass") clamps levels outside the native grid to the nearest native quantile.
Loaded models are cached via a multiton helper keyed by model-loading inputs to avoid repeated model instantiation.
The default Timer-S1 checkpoint has 8 billion parameters. For most hardware, reduced-memory loading with dtype and quantization_config, or a pre-quantized checkpoint, is recommended.

References

[1]

Liu, Y., Su, X., Wang, S., Zhang, H., Liu, H., Wang, Y., Ye, Z., Xiang, Y., Wang, J., and Long, M. (2026). Timer-S1: A Billion-Scale Time Series Foundation Model with Serial Scaling. arXiv. https://arxiv.org/abs/2603.04791

[2]

Timer-S1 model card: https://huggingface.co/bytedance-research/Timer-S1

[3]

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

Examples

Simple zero-shot forecasting with the default Timer-S1 checkpoint:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timer_s1 import TimerS1Forecaster
>>> y = load_airline()
>>> # By default, loads bytedance-research/Timer-S1.
>>> forecaster = TimerS1Forecaster()
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Reduced-memory inference for the 8-billion-parameter model:

>>> import torch
>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timer_s1 import TimerS1Forecaster
>>> from transformers import BitsAndBytesConfig
>>> y = load_airline()
>>> forecaster = TimerS1Forecaster(
...     model_path="bytedance-research/Timer-S1",
...     forward_kwargs={"revin": True},
...     device_map="auto",
...     dtype=torch.bfloat16,
...     quantization_config=BitsAndBytesConfig(load_in_8bit=True),
... )
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Loading a quantized smaller model directly:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timer_s1 import TimerS1Forecaster
>>> y = load_airline()
>>> forecaster = TimerS1Forecaster(
...     model_path="geetu040/Timer-S1-quantized-4bit",
... )
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict(fh=[1, 2, 3])

Randomly initialized local model, useful for tests or local experimentation. This model is not trained by fit; the weights stay random and should not be used as a trained forecaster:

>>> from sktime.forecasting.timer_s1 import TimerS1Forecaster
>>> forecaster = TimerS1Forecaster(
...     model_path=None,
...     config={
...         "hidden_size": 16,
...         "intermediate_size": 16,
...         "num_attention_heads": 4,
...         "num_experts": 4,
...         "num_hidden_layers": 1,
...         "num_mtp_tokens": 1,
...     },
...     deterministic=True,
... )

Quantile prediction:

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.timer_s1 import TimerS1Forecaster
>>> y = load_airline()
>>> forecaster = TimerS1Forecaster(
...     model_path="geetu040/Timer-S1-quantized-4bit",
... )
>>> forecaster.fit(y)
>>> y_pred = forecaster.predict_quantiles(
...     fh=[1, 2, 3],
...     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.
`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.