PatchTSMixerForecaster

class PatchTSMixerForecaster(model_path: str | None = 'ibm-granite/granite-timeseries-patchtsmixer', revision: str = 'main', config: dict | None = None, context_length: int | None = None, prediction_length: int | None = None, validation_split: float = 0.2, train_model: bool = True, scaling: bool = True, training_args: dict | None = None, callbacks: list | None = None, num_parallel_samples: int | None = None, device: str | None = None)[source]

Forecaster wrapping IBM PatchTSMixer (granite-tsfm / Hugging Face).

PatchTSMixer, developed by IBM, is a Lightweight MLP-Mixer Model for Multivariate Time Series Forecasting. Implementation inspired by [1].

y should use a DatetimeIndex (or PeriodIndex). Endogenous columns in y are forecast jointly; there is no exogenous X support. If y has no time index, index is reset, and a synthetic daily timestamp column is used instead.

Parameters:

model_pathstr, optional, default=”ibm-granite/granite-timeseries-patchtsmixer”

Hugging Face model id or local checkpoint path. If None, the model is initialized from config only (train from scratch).

revisionstr, default=”main”

Hub revision for from_pretrained.

configdict, optional, default=None

Extra fields for PatchTSMixerConfig (e.g. d_model, patch_length). Valid keys include:

context_lengthint, optional, default=32: The context/history length for the input sequence.
patch_lengthint, optional, default=8: The patch length for the input sequence.
num_input_channelsint, optional, default=1: The number of input channels.
patch_strideint, optional, default=8: Determines the overlap between two consecutive patches. Set it to patch_length (or greater) for non-overlapping patches.
num_parallel_samplesint, optional, default=100: The number of samples to generate in parallel for probabilistic forecast.
d_modelint, optional, default=8: Size of the encoder layers and the pooler layer.
expansion_factorint, optional, default=2: Expansion factor to use inside MLP. Recommended range is 2-5. Larger value indicates more complex model.
num_layersint, optional, default=3: Number of hidden layers in the Transformer decoder.
dropoutfloat or int, optional, default=0.2: The ratio for all dropout layers.
modestr, optional, default=”common_channel”: Mixer mode. Determines how to process the channels. Allowed values: "common_channel", "mix_channel". In "common_channel" mode, channel-independent modelling is used with no explicit channel-mixing; channel mixing happens implicitly via shared weights across channels (preferred first approach). In "mix_channel" mode, explicit channel-mixing is used in addition to patch and feature mixer (preferred when channel correlations are very important to model).
gated_attnbool, optional, default=True: Enable gated attention.
norm_mlpstr, optional, default=”LayerNorm”: Normalization layer (BatchNorm or LayerNorm).
self_attnbool, optional, default=False: Enable tiny self-attention across patches. This can be enabled when the output of vanilla PatchTSMixer with gated attention is not satisfactory. Enabling this leads to explicit pair-wise attention and modelling across patches.
self_attn_headsint, optional, default=1: Number of self-attention heads. Works only when self_attn is set to True.
use_positional_encodingbool, optional, default=False: Enable the use of positional embedding for the tiny self-attention layers. Works only when self_attn is set to True.
positional_encoding_typestr, optional, default=”sincos”: Positional encodings. Options "random" and "sincos" are supported. Works only when use_positional_encoding is set to True.
scalingstr or bool, optional, default=”std”: Whether to scale the input targets via "mean" scaler, "std" scaler or no scaler if None. If True, the scaler is set to "mean".
lossstr, optional, default=”mse”: The loss function for the model corresponding to the distribution_output head. For parametric distributions it is the negative log likelihood ("nll") and for point estimates it is the mean squared error "mse".
init_stdfloat, optional, default=0.02: The standard deviation of the truncated_normal_initializer for initializing all weight matrices.
norm_epsfloat, optional, default=1e-05: A value added to the denominator for numerical stability of normalization.
mask_typestr, optional, default=”random”: Type of masking to use for masked pretraining mode. Allowed values are "random", "forecast". In random masking, points are masked randomly. In forecast masking, points are masked towards the end.
random_mask_ratiofloat, optional, default=0.5: Masking ratio to use when mask_type is "random". Higher value indicates more masking.
num_forecast_mask_patchesint or list, optional, default=[2]: Number of patches to be masked at the end of each batch sample. If it is an integer, all the samples in the batch will have the same number of masked patches. If it is a list, samples in the batch will be randomly masked by numbers defined in the list. This argument is only used for forecast pretraining.
mask_valuefloat, optional, default=0.0: Mask value to use.
masked_lossbool, optional, default=True: Whether to compute pretraining loss only at the masked portions, or on the entire output.
channel_consistent_maskingbool, optional, default=True: When True, masking will be the same across all channels of a timeseries. Otherwise, masking positions will vary across channels.
unmasked_channel_indiceslist, optional: Channels that are not masked during pretraining.
head_dropoutfloat, optional, default=0.2: The dropout probability for the PatchTSMixer head.
distribution_outputstr, optional, default=”student_t”: The distribution emission head for the model when loss is "nll". Could be either "student_t", "normal" or "negative_binomial".
prediction_lengthint, optional, default=16: Number of time steps to forecast for a forecasting task. Also known as the forecast horizon.
prediction_channel_indiceslist, optional: List of channel indices to forecast. If None, forecast all channels. Target data is expected to have all channels and we explicitly filter the channels in prediction and target before loss computation.
num_targetsint, optional, default=3: Number of targets (dimensionality of the regressed variable) for a regression task.
output_rangelist, optional: Output range to restrict for the regression task. Defaults to None.
head_aggregationstr, optional, default=”max_pool”: Aggregation mode to enable for classification or regression task. Allowed values are None, "use_last", "max_pool", "avg_pool".

context_lengthint, optional, default=None

Input history length for sliding windows. If None, taken from the loaded config or defaults to 512 when training from scratch.

prediction_lengthint, optional, default=None

Forecast horizon length for the model head. If None, uses max(fh) when fh is passed to fit, else the loaded config default.

validation_splitfloat, optional, default=0.2

Fraction of y held out for validation during Trainer training.

train_modelbool, default=True

If True, run Trainer.train() on y. If False, only fit the preprocessor and load weights (pretrained model evaluate path).

scalingbool, default=True

Whether TimeSeriesPreprocessor standardizes targets.

training_argsdict, optional, default=None

Passed to TrainingArguments (label_names=["future_values"] is set if missing). See [3] for details.

callbackslist, optional, default=None

Hugging Face Trainer callbacks (e.g. EarlyStoppingCallback).

num_parallel_samplesint, optional, default=None

Override num_parallel_samples on the model for generate.

devicestr, optional (default=None)

Device on which to run the model. "auto" is passed to transformers device_map and selects an available accelerator. If None, existing model and Trainer placement behavior is preserved.

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/ibm-granite/granite-tsfm/blob/main/notebooks/hfdemo/patch_tsmixer_getting_started.ipynb

[2]

Ekambaram et al., TSMixer: Lightweight MLP-Mixer Model for Multivariate Time Series Forecasting, arXiv:2306.09364

[3]

https://huggingface.co/docs/transformers/v5.14.0/en/main_classes/trainer#transformers.TrainingArguments

Examples

>>> from sktime.datasets import load_airline
>>> from sktime.forecasting.patch_tsmixer import PatchTSMixerForecaster
>>> from sktime.split import temporal_train_test_split
>>> y = load_airline()
>>> y_train, _ = temporal_train_test_split(y)
>>> f = PatchTSMixerForecaster(
...     model_path=None,
...     config={
...         "context_length": 8,
...         "prediction_length": 3,
...         "patch_length": 2,
...         "patch_stride": 2,
...         "num_input_channels": 1,
...         "d_model": 16,
...         "num_layers": 1,
...     },
...     training_args={
...         "output_dir": "test_output",
...         "max_steps": 2,
...         "per_device_train_batch_size": 4,
...         "report_to": "none",
...     },
... )
>>> f.fit(y_train, fh=[1, 2, 3])
>>> y_pred = f.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.