etna.models.nn.TimesFMModel#

class TimesFMModel(path_or_url: str, encoder_length: int = 512, num_layers: int = 20, use_positional_embedding: bool = True, normalize_target: bool = False, device: Literal['cpu', 'gpu'] = 'cpu', batch_size: int = 128, static_reals: List[str] | None = None, static_categoricals: List[str] | None = None, time_varying_reals: List[str] | None = None, time_varying_categoricals: List[str] | None = None, normalize_exog: bool = True, forecast_with_exog_mode: Literal['timesfm + xreg', 'xreg + timesfm'] = 'xreg + timesfm', cache_dir: str = '/home/runner/.etna/timesfm')[source]#

Bases: NonPredictionIntervalContextRequiredAbstractModel

Class for pretrained timesfm models.

This model is only for zero-shot forecasting: it doesn’t support training on data during fit.

This model doesn’t support NaN in the middle or at the end of target and exogenous features. Use TimeSeriesImputerTransform to fill them.

Official implementation: google-research/timesfm

Note

This model requires timesfm extension to be installed. Read more about this at installation page.

Init TimesFM model.

Parameters:

path_or_url (str) –
Path to the model. It can be huggingface repository, local path or external url.
- If huggingface repository, the available models are:
  - ’google/timesfm-1.0-200m-pytorch’.
  During the first initialization model is downloaded from huggingface and saved to local cache_dir. All following initializations model will be loaded from cache_dir.
- If local path, it should be a file with model weights, that can be loaded by torch.load().
- If external url, it must be a file with model weights, that can be loaded by torch.load(). Model will be downloaded to cache_dir.
device (Literal['cpu', 'gpu']) – Device type. Can be “cpu” or “gpu”.
encoder_length (int) – Number of last timestamps to use as a context. It needs to be a multiplier of 32.
num_layers (int) – Number of layers. For 200m model set num_layers=20 and for 500m num_layers=50.
use_positional_embedding (bool) – Whether to use positional embeddings. For 200m model set use_positional_embedding=True and for 500m use_positional_embedding=False.
normalize_target (bool) – Whether to normalize target before forecasting. Is used only for forecasting without exogenous features.
batch_size (int) – Batch size. It can be useful when inference is done on gpu.
static_reals (List[str] | None) – Continuous features that have one unique feature value for the whole series. The first value in the series will be used for each feature.
static_categoricals (List[str] | None) – Categorical features that have one unique feature value for the whole series. The first value in the series will be used for each feature.
time_varying_reals (List[str] | None) – Time varying continuous features known for future.
time_varying_categoricals (List[str] | None) – Time varying categorical features known for future.
normalize_exog (bool) – Whether to normalize exogenous features before forecasting. Is used only for forecasting with exogenous features.
forecast_with_exog_mode (Literal['timesfm + xreg', 'xreg + timesfm']) –
Mode of forecasting with exogenous features.
- ”xreg + timesfm” fits TimesFM on the residuals of a linear model forecast.
- ”timesfm + xreg” fits a linear model on the residuals of the TimesFM forecast.
cache_dir (str) – Local path to save model from huggingface during first model initialization. All following class initializations appropriate model version will be downloaded from this path.

Methods

`fit`(ts)	Fit model.
`forecast`(ts, prediction_size[, ...])	Make autoregressive forecasts.
`get_model`()	Get model.
`list_models`()	Return a list of available pretrained timesfm models.
`load`(path)	Load the model.
`params_to_tune`()	Get default grid for tuning hyperparameters.
`predict`(ts, prediction_size[, return_components])	Make predictions using true values as autoregression context (teacher forcing).
`save`(path)	Save the model.
`set_params`(**params)	Return new object instance with modified parameters.
`to_dict`()	Collect all information about etna object in dict.

Attributes

This class stores its __init__ parameters as attributes.

context_size

Context size for model.

fit(ts: TSDataset)[source]#

Fit model.

For this model, fit does nothing.

Parameters:: ts (TSDataset) – Dataset with features.
Returns:: Model after fit

forecast(ts: TSDataset, prediction_size: int, return_components: bool = False) → TSDataset[source]#

Make autoregressive forecasts.

Parameters:

ts (TSDataset) – Dataset with features.
prediction_size (int) – Number of last timestamps to leave after making prediction. Previous timestamps will be used as a context.
return_components (bool) – If True additionally returns forecast components.

Returns:

Dataset with predictions.

Raises:

NotImplementedError: – if return_components mode is used.
ValueError: – if dataset doesn’t have any context timestamps.
ValueError: – if there are NaNs in the middle or end of the time series.

Return type:

TSDataset

get_model() → TimesFmTorch[source]#

Get model.

Return type:: TimesFmTorch

static list_models() → List[str][source]#

Return a list of available pretrained timesfm models.

Returns:: List of available pretrained timesfm models.
Return type:: List[str]

classmethod load(path: Path)[source]#

Load the model.

Parameters:: path (Path) – Path to load object from.

params_to_tune() → Dict[str, BaseDistribution][source]#

Get default grid for tuning hyperparameters.

This grid is empty.

Returns:: Grid to tune.
Return type:: Dict[str, BaseDistribution]

predict(ts: TSDataset, prediction_size: int, return_components: bool = False) → TSDataset[source]#

Make predictions using true values as autoregression context (teacher forcing).

Parameters:

ts (TSDataset) – Dataset with features.
prediction_size (int) – Number of last timestamps to leave after making prediction. Previous timestamps will be used as a context.
return_components (bool) – If True additionally returns forecast components.

Returns:

Dataset with predictions.

Return type:

TSDataset

save(path: Path)[source]#

Save the model. This method doesn’t save model’s weights.

During load weights are loaded from the path where they were saved during init

Parameters:: path (Path) – Path to save object to.

set_params(**params: dict) → Self[source]#

Return new object instance with modified parameters.

Method also allows to change parameters of nested objects within the current object. For example, it is possible to change parameters of a model in a Pipeline.

Nested parameters are expected to be in a <component_1>.<...>.<parameter> form, where components are separated by a dot.

Parameters:: **params (dict) – Estimator parameters
Returns:: New instance with changed parameters
Return type:: Self

Examples

>>> from etna.pipeline import Pipeline
>>> from etna.models import NaiveModel
>>> from etna.transforms import AddConstTransform
>>> model = NaiveModel(lag=1)
>>> transforms = [AddConstTransform(in_column="target", value=1)]
>>> pipeline = Pipeline(model, transforms=transforms, horizon=3)
>>> pipeline.set_params(**{"model.lag": 3, "transforms.0.value": 2})
Pipeline(model = NaiveModel(lag = 3, ), transforms = [AddConstTransform(in_column = 'target', value = 2, inplace = True, out_column = None, )], horizon = 3, )

to_dict()[source]#: Collect all information about etna object in dict.

property context_size: int[source]#: Context size for model.