Docs /Templates/ sinapsis-darts-forecasting

NBEATSModelWrapper

sinapsis-darts-forecastingDartsdartsdynamicforecastingmodels

Python template · sinapsis_darts_forecasting.templates.time_series_model

Overview

Base Template for Darts Time Series forecasting models.

NBEATSModel — 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.Neural Basis Expansion Analysis Time Series Forecasting (N-BEATS).

This is an implementation of the N-BEATS architecture, as outlined in [1]_.

In addition to the univariate version presented in the paper, our implementation also supports multivariate series (and covariates) by flattening the model inputs to a 1-D series and reshaping the outputs to a tensor of appropriate dimensions. Furthermore, it also supports producing probabilistic forecasts (by specifying a `likelihood` parameter).

This model supports past covariates (known for `input_chunk_length` points before prediction time).

Parameters ---------- input_chunk_length Number of time steps in the past to take as a model input (per chunk). Applies to the target series, and past and/or future covariates (if the model supports it). output_chunk_length Number of time steps predicted at once (per chunk) by the internal model. Also, the number of future values from future covariates to use as a model input (if the model supports future covariates). It is not the same as forecast horizon `n` used in `predict()`, which is the desired number of prediction points generated using either a one-shot- or autoregressive forecast. Setting `n <= output_chunk_length` prevents auto-regression. This is useful when the covariates don't extend far enough into the future, or to prohibit the model from using future values of past and / or future covariates for prediction (depending on the model's covariate support). output_chunk_shift Optionally, the number of steps to shift the start of the output chunk into the future (relative to the input chunk end). This will create a gap between the input and output. If the model supports `future_covariates`, the future values are extracted from the shifted output chunk. Predictions will start `output_chunk_shift` steps after the end of the target `series`. If `output_chunk_shift` is set, the model cannot generate autoregressive predictions (`n > output_chunk_length`). generic_architecture Boolean value indicating whether the generic architecture of N-BEATS is used. If not, the interpretable architecture outlined in the paper (consisting of one trend and one seasonality stack with appropriate waveform generator functions). num_stacks The number of stacks that make up the whole model. Only used if `generic_architecture` is set to `True`. The interpretable architecture always uses two stacks - one for trend and one for seasonality. num_blocks The number of blocks making up every stack. num_layers The number of fully connected layers preceding the final forking layers in each block of every stack. layer_widths Determines the number of neurons that make up each fully connected layer in each block of every stack. If a list is passed, it must have a length equal to `num_stacks` and every entry in that list corresponds to the layer width of the corresponding stack. If an integer is passed, every stack will have blocks with FC layers of the same width. expansion_coefficient_dim The dimensionality of the waveform generator parameters, also known as expansion coefficients. Only used if `generic_architecture` is set to `True`. trend_polynomial_degree The degree of the polynomial used as waveform generator in trend stacks. Only used if `generic_architecture` is set to `False`. dropout The dropout probability to be used in fully connected layers. This is compatible with Monte Carlo dropout at inference time for model uncertainty estimation (enabled with ``mc_dropout=True`` at prediction time). activation The activation function of encoder/decoder intermediate layer (default='ReLU'). Supported activations: ['ReLU', 'RReLU', 'PReLU', 'ELU', 'Softplus', 'Tanh', 'SELU', 'LeakyReLU', 'Sigmoid', 'GELU'] **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``. use_reversible_instance_norm Whether to use reversible instance normalization `RINorm` against distribution shift as shown in [2]_. It is only applied to the features of the target series and not the covariates. 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``.

References ---------- .. [1] https://openreview.net/forum?id=r1ecqn4YwB .. [2] T. Kim et al. "Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift", https://openreview.net/forum?id=cGDAkQo1C0p

Examples -------- >>> from darts.datasets import WeatherDataset >>> from darts.models import NBEATSModel >>> series = WeatherDataset().load() >>> # predicting atmospheric pressure >>> target = series['p (mbar)'][:100] >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100) >>> past_cov = series['rain (mm)'][:100] >>> # changing the activation function of the encoder/decoder to LeakyReLU >>> model = NBEATSModel( >>> input_chunk_length=6, >>> output_chunk_length=6, >>> n_epochs=5, >>> activation='LeakyReLU' >>> ) >>> model.fit(target, past_covariates=past_cov) >>> pred = model.predict(6) >>> print(pred.values()) [[ 929.78509085] [1013.66339481] [ 999.8843893 ] [ 892.66032082] [ 921.09781534] [ 950.37965429]]

.. note:: `NBEATS example notebook <https://unit8co.github.io/darts/examples/07-NBEATS-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
validation_mode
bool
Optional
Default: false
forecast_horizon
int
Optional
Default: 10
nbeatsmodel_initRequired
BaseModel
Required
Default: null

Configuration example

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

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

The source example references XGBModelWrapper, not NBEATSModelWrapper.

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