Docs /Templates/ sinapsis-darts-forecasting

RNNModelWrapper

sinapsis-darts-forecastingDartsdartsdynamicforecastingmodels

Python template · sinapsis_darts_forecasting.templates.time_series_model

Overview

Base Template for Darts Time Series forecasting models.

RNNModel — inherited documentation

The base class for "global" forecasting models, handling several time series and optional covariates.

Global forecasting models expand upon the functionality of `ForecastingModel` in 4 ways: 1. Models can be fitted on many series (multivariate or univariate) with different indices. 2. The input series used by :func:`predict()` can be different from the series used to fit the model. 3. Covariates can be supported (multivariate or univariate). 4. They can allow for multivariate target series and covariates.

The name "global" stems from the fact that a training set of a forecasting model of this class is not constrained to a temporally contiguous, "local", time series.

All implementations must implement the :func:`fit()` and :func:`predict()` methods. The :func:`fit()` method is meant to train the model on one or several training time series, along with optional covariates.

If :func:`fit()` has been called with only one training and covariate series as argument, then calling :func:`predict()` will forecast the future of this series. Otherwise, the user has to provide to :func:`predict()` the series they want to forecast, as well as covariates, if needed.Recurrent Neural Network Model (RNNs).

This class provides three variants of RNNs:

* Vanilla RNN

* LSTM

* GRU

RNNModel is fully recurrent in the sense that, at prediction time, an output is computed using these inputs:

- previous target value, which will be set to the last known target value for the first prediction, and for all other predictions it will be set to the previous prediction (in an autoregressive fashion), - the previous hidden state, - the covariates at time `t` for forecasting the target at time `t` (if the model was trained with covariates),

This model supports future covariates; and it requires these covariates to extend far enough in the past and the future (it's a so-called "dual covariates" model as the future covariates have to be provided both in the past and the future). The model will complain if the provided `future_covariates` series doesn't have an appropriate time span.

For a block version using an RNN model as an encoder only and supporting past covariates, checkout `BlockRNNModel`.

Parameters ---------- input_chunk_length Number of past time steps that are fed to the forecasting module at prediction time. model Either a string specifying the RNN module type ("RNN", "LSTM" or "GRU"), or a subclass of :class:`CustomRNNModule` (the class itself, not an object of the class) with a custom logic. hidden_dim Size for feature maps for each hidden RNN layer (:math:`h_n`). n_rnn_layers The number of recurrent layers. dropout Fraction of neurons affected by Dropout. training_length The length of both input (target and covariates) and output (target) time series used during training. Must be `>input_chunk_length`, because otherwise during training the RNN is never run for as many iterations as it will during inference. For training, a :class:`~darts.utils.data.torch_datasets.training_dataset.ShiftedTorchTrainingDataset` is used with parameters `input_chunk_length=output_chunk_length=training_length` and `shift=1`. **kwargs Optional arguments to initialize the pytorch_lightning.Module, pytorch_lightning.Trainer, and Darts' :class:`TorchForecastingModel`.

loss_fn PyTorch loss function used for training. This parameter will be ignored for probabilistic models if the ``likelihood`` parameter is specified. Default: ``torch.nn.MSELoss()``. likelihood One of Darts' :meth:`Likelihood <darts.utils.likelihood_models.torch.TorchLikelihood>` models to be used for probabilistic forecasts. Default: ``None``. torch_metrics A torch metric or a ``MetricCollection`` used for evaluation. A full list of available metrics can be found at https://torchmetrics.readthedocs.io/en/latest/. Default: ``None``. optimizer_cls The PyTorch optimizer class to be used. Default: ``torch.optim.Adam``. optimizer_kwargs Optionally, some keyword arguments for the PyTorch optimizer (e.g., ``{'lr': 1e-3}`` for specifying a learning rate). Otherwise the default values of the selected ``optimizer_cls`` will be used. Default: ``None``. lr_scheduler_cls Optionally, the PyTorch learning rate scheduler class to be used. Specifying ``None`` corresponds to using a constant learning rate. Default: ``None``. lr_scheduler_kwargs Optionally, some keyword arguments for the PyTorch learning rate scheduler. Default: ``None``. batch_size Number of time series (input and output sequences) used in each training pass. Default: ``32``. n_epochs Number of epochs over which to train the model. Default: ``100``. model_name Name of the model. Used for creating checkpoints and saving tensorboard data. If not specified, defaults to the following string ``"YYYY-mm-dd_HH_MM_SS_torch_model_run_PID"``, where the initial part of the name is formatted with the local date and time, while PID is the processed ID (preventing models spawned at the same time by different processes to share the same model_name). E.g., ``"2021-06-14_09_53_32_torch_model_run_44607"``. work_dir Path of the working directory, where to save checkpoints and Tensorboard summaries. Default: current working directory. log_tensorboard If set, use Tensorboard to log the different parameters. The logs will be located in: ``"{work_dir}/darts_logs/{model_name}/logs/"``. Default: ``False``. nr_epochs_val_period Number of epochs to wait before evaluating the validation loss (if a validation ``TimeSeries`` is passed to the :func:`fit()` method). Default: ``1``. force_reset If set to ``True``, any previously-existing model with the same name will be reset (all checkpoints will be discarded). Default: ``False``. save_checkpoints Whether to automatically save the untrained model and checkpoints from training. To load the model from checkpoint, call :func:`MyModelClass.load_from_checkpoint()`, where :class:`MyModelClass` is the :class:`TorchForecastingModel` class that was used (such as :class:`TFTModel`, :class:`NBEATSModel`, etc.). If set to ``False``, the model can still be manually saved using :func:`save()` and loaded using :func:`load()`. Default: ``False``. add_encoders A large number of past and future covariates can be automatically generated with `add_encoders`. This can be done by adding multiple pre-defined index encoders and/or custom user-made functions that will be used as index encoders. Additionally, a transformer such as Darts' :class:`Scaler` can be added to transform the generated covariates. This happens all under one hood and only needs to be specified at model creation. Read :meth:`SequentialEncoder <darts.dataprocessing.encoders.SequentialEncoder>` to find out more about ``add_encoders``. Default: ``None``. An example showing some of ``add_encoders`` features:

.. highlight:: python .. code-block:: python

def encode_year(idx): return (idx.year - 1950) / 50

add_encoders={ 'cyclic': {'future': ['month']}, 'datetime_attribute': {'future': ['hour', 'dayofweek']}, 'position': {'past': ['relative'], 'future': ['relative']}, 'custom': {'past': [encode_year]}, 'transformer': Scaler(), 'tz': 'CET' } .. random_state Controls the randomness of the weights initialization and reproducible forecasting. pl_trainer_kwargs By default :class:`TorchForecastingModel` creates a PyTorch Lightning Trainer with several useful presets that performs the training, validation and prediction processes. These presets include automatic checkpointing, tensorboard logging, setting the torch device and more. With ``pl_trainer_kwargs`` you can add additional kwargs to instantiate the PyTorch Lightning trainer object. Check the `PL Trainer documentation <https://pytorch-lightning.readthedocs.io/en/stable/common/trainer.html>`__ for more information about the supported kwargs. Default: ``None``. Running on GPU(s) is also possible using ``pl_trainer_kwargs`` by specifying keys ``"accelerator", "devices", and "auto_select_gpus"``. Some examples for setting the devices inside the ``pl_trainer_kwargs`` dict:

- ``{"accelerator": "cpu"}`` for CPU, - ``{"accelerator": "gpu", "devices": [i]}`` to use only GPU ``i`` (``i`` must be an integer), - ``{"accelerator": "gpu", "devices": -1, "auto_select_gpus": True}`` to use all available GPUS.

For more info, see here: https://pytorch-lightning.readthedocs.io/en/stable/common/trainer.html#trainer-flags , and https://pytorch-lightning.readthedocs.io/en/stable/accelerators/gpu_basic.html#train-on-multiple-gpus

With parameter ``"callbacks"`` you can add custom or PyTorch-Lightning built-in callbacks to Darts' :class:`TorchForecastingModel`. Below is an example for adding EarlyStopping to the training process. The model will stop training early if the validation loss `val_loss` does not improve beyond specifications. For more information on callbacks, visit: `PyTorch Lightning Callbacks <https://pytorch-lightning.readthedocs.io/en/stable/extensions/callbacks.html>`__

.. highlight:: python .. code-block:: python

from pytorch_lightning.callbacks.early_stopping import EarlyStopping

# stop training when validation loss does not decrease more than 0.05 (`min_delta`) over # a period of 5 epochs (`patience`) my_stopper = EarlyStopping( monitor="val_loss", patience=5, min_delta=0.05, mode='min', )

pl_trainer_kwargs={"callbacks": [my_stopper]} ..

Note that you can also use a custom PyTorch Lightning Trainer for training and prediction with optional parameter ``trainer`` in :func:`fit()` and :func:`predict()`. show_warnings whether to show warnings raised from PyTorch Lightning. Useful to detect potential issues of your forecasting use case. Default: ``False``.

Examples -------- >>> from darts.datasets import WeatherDataset >>> from darts.models import RNNModel >>> series = WeatherDataset().load() >>> # predicting atmospheric pressure >>> target = series['p (mbar)'][:100] >>> # optionally, use future temperatures (pretending this component is a forecast) >>> future_cov = series['T (degC)'][:106] >>> # `training_length` > `input_chunk_length` to mimic inference constraints >>> model = RNNModel( >>> model="RNN", >>> input_chunk_length=6, >>> training_length=18, >>> n_epochs=20, >>> ) >>> model.fit(target, future_covariates=future_cov) >>> pred = model.predict(6) >>> print(pred.values()) [[ 3.18922903] [ 1.17791019] [ 0.39992814] [ 0.13277921] [ 0.02523252] [-0.01829086]]

.. note:: `RNN example notebook <https://unit8co.github.io/darts/examples/04-RNN-examples.html>`__ presents techniques that can be used to improve the forecasts quality compared to this simple usage example.

Capabilities

Capabilities: not set

Installation

Install the published package using pip or uv.

Terminalbash
pip install sinapsis-darts-forecasting==1.0.0
uv pip install sinapsis-darts-forecasting==1.0.0
uv add sinapsis-darts-forecasting==1.0.0

Configuration

Effective fields from the inspector schema, including nested Pydantic model fields.

metadata
sinapsis_core.template_base.base_models.TemplateMetadata | None
Optional
Default: null
rnnmodel_initRequired
BaseModel
Required
Default: null
validation_mode
bool
Optional
Default: false
forecast_horizon
int
Optional
Default: 10

Configuration example

Generated from documented defaults. Replace any placeholders and complete required nested settings before running.

yaml
templates:
  - template_name: "RNNModelWrapper"
    class_name: "RNNModelWrapper"
    attributes:
      rnnmodel_init: {}
      validation_mode: false
      forecast_horizon: 10
View original docstring example

The source example references XGBModelWrapper, not RNNModelWrapper.

yaml
agent:
    name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: XGBModelWrapper
  class_name: XGBModelWrapper
  template_input: InputTemplate
  attributes:
    forecast_horizon: 100
    xgbmodel_init:
        lags: 30
        lags_past_covariates: 30
        output_chunk_length: 100
        random_state: 42
        n_estimators: 200
        learning_rate: 0.1
        max_depth: 6
For a full list of options use the sinapsis cli: sinapsis info --all-template-names.
If you want to see all available models, please visit:
https://unit8co.github.io/darts/generated_api/darts.models.forecasting.html

Inheritance

Immediate parent: sinapsis_darts_forecasting.templates.time_series_model.TimeSeriesModel

Environment variables

Environment definitions belong to their canonical Python modules.

SINAPSIS_BUILD_DOCS · defined elsewhere