GlobalNaiveAggregateWrapper
Python template · sinapsis_darts_forecasting.templates.time_series_model
Overview
Base Template for Darts Time Series forecasting models.
GlobalNaiveAggregate — 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.Global Naive Aggregate Model.
The model generates forecasts for each `series` as described below:
- take an aggregate (computed with `agg_fn`, default: mean) from each target component over the last `input_chunk_length` points - the forecast is the component aggregate repeated `output_chunk_length` times
Depending on the horizon `n` used when calling `model.predict()`, the forecasts are either:
- a constant aggregate value (default: mean) if `n <= output_chunk_length`, or - a moving aggregate if `n > output_chunk_length`, as a result of the autoregressive prediction.
This model is equivalent to:
- :class:`~darts.models.forecasting.baselines.NaiveMean`, when `input_chunk_length` is equal to the length of the input target `series`, and `agg_fn='mean'`. - :class:`~darts.models.forecasting.baselines.NaiveMovingAverage`, with identical `input_chunk_length` and `output_chunk_length=1`, and `agg_fn='mean'`.
.. note:: - Model checkpointing with `save_checkpoints=True`, and checkpoint loading with `load_from_checkpoint()` and `load_weights_from_checkpoint()` are not supported for global naive models.
Parameters ---------- input_chunk_length The length of the input sequence fed to the model. output_chunk_length The length of the emitted forecast and output sequence fed to the model. 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`). agg_fn The aggregation function to use. If a string, must be the name of `torch` function that can be imported directly from `torch` (e.g. `"mean"` for `torch.mean`, `"sum"` for `torch.sum`). The function must have the signature below. If a `Callable`, it must also have the signature below.
.. highlight:: python .. code-block:: python
def agg_fn(x: torch.Tensor, dim: int, *args, **kwargs) -> torch.Tensor: # x has shape `(batch size, input_chunk_length, n targets)`, `dim` is always `1`. # function must return a tensor of shape `(batch size, n targets)` return torch.mean(x, dim=dim) .. **kwargs Optional arguments to initialize the pytorch_lightning.Module, pytorch_lightning.Trainer, and Darts' :class:`TorchForecastingModel`. Since naive models are not trained, the following parameters will have no effect: `loss_fn`, `likelihood`, `optimizer_cls`, `optimizer_kwargs`, `lr_scheduler_cls`, `lr_scheduler_kwargs`, `n_epochs`, `save_checkpoints`, and some of `pl_trainer_kwargs`.
Examples -------- >>> from darts.datasets import IceCreamHeaterDataset >>> from darts.models import GlobalNaiveAggregate >>> # create list of multivariate series >>> series_1 = IceCreamHeaterDataset().load() >>> series_2 = series_1 + 100. >>> series = [series_1, series_2] >>> # predict 3 months, take mean over last 60 months >>> horizon, icl = 3, 60 >>> # naive mean over last 60 months (with `output_chunk_length = horizon`) >>> model = GlobalNaiveAggregate(input_chunk_length=icl, output_chunk_length=horizon) >>> # predict after end of each multivariate series >>> pred = model.fit(series).predict(n=horizon, series=series) >>> [p.values() for p in pred] [array([[29.666668, 50.983337], [29.666668, 50.983337], [29.666668, 50.983337]]), array([[129.66667, 150.98334], [129.66667, 150.98334], [129.66667, 150.98334]])] >>> # naive moving mean (with `output_chunk_length < horizon`) >>> model = GlobalNaiveAggregate(input_chunk_length=icl, output_chunk_length=1, agg_fn="mean") >>> pred = model.fit(series).predict(n=horizon, series=series) >>> [p.values() for p in pred] [array([[29.666668, 50.983337], [29.894447, 50.88306 ], [30.109352, 50.98111 ]]), array([[129.66667, 150.98334], [129.89445, 150.88307], [130.10936, 150.98111]])] >>> # naive moving sum (with `output_chunk_length < horizon`) >>> model = GlobalNaiveAggregate(input_chunk_length=icl, output_chunk_length=1, agg_fn="sum") >>> pred = model.fit(series).predict(n=horizon, series=series) >>> [p.values() for p in pred] [array([[ 1780., 3059.], [ 3544., 6061.], [ 7071., 12077.]]), array([[ 7780., 9059.], [15444., 17961.], [30771., 35777.]])]
Capabilities
Capabilities: not setInstallation
Install the published package using pip or uv.
pip install sinapsis-darts-forecasting==1.0.0uv pip install sinapsis-darts-forecasting==1.0.0uv add sinapsis-darts-forecasting==1.0.0Configuration
Effective fields from the inspector schema, including nested Pydantic model fields.
Optional
Default: null
Optional
Default: false
Optional
Default: 10
Required
Default: null
Configuration example
Generated from documented defaults. Replace any placeholders and complete required nested settings before running.
templates:
- template_name: "GlobalNaiveAggregateWrapper"
class_name: "GlobalNaiveAggregateWrapper"
attributes:
validation_mode: false
forecast_horizon: 10
globalnaiveaggregate_init: {}
View original docstring example
The source example references XGBModelWrapper, not GlobalNaiveAggregateWrapper.
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.htmlInheritance
sinapsis_darts_forecasting.templates.time_series_model.TimeSeriesModelEnvironment variables
Environment definitions belong to their canonical Python modules.