StatsForecastModelWrapper
Python template · sinapsis_darts_forecasting.templates.time_series_model
Overview
Base Template for Darts Time Series forecasting models.
StatsForecastModel — inherited documentation
The base class for transferable future covariates "local" forecasting models, handling single uni- or multivariate target and optional future covariates time series. Additionally, at prediction time, it can be applied to new data unrelated to the original series used for fitting the model.
Transferable Future Covariates Local Forecasting Models (TFC-LFM) are models that can be trained on a single uni- or multivariate target and optional future covariates series. Additionally, at prediction time, it can be applied to new data unrelated to the original series used for fitting the model. Currently in Darts, all models in this category wrap to statsmodel models such as VARIMA. TFC-LFMs usually train on the entire target and future covariates series supplied when calling :func:`fit()` at once. They can also predict in one go with :func:`predict()` for any number of predictions `n` after the end of the training series. When using future covariates, the values for the future `n` prediction steps must be given in the covariate series.
All implementations must implement the :func:`_fit()` and :func:`_predict()` methods.StatsForecast Model.
Can be used to fit any `StatsForecast` base model. For more information on available models, see the `StatsForecast package <https://nixtlaverse.nixtla.io/statsforecast/index.html>`__.
In addition to univariate deterministic forecasting, our `StatsForecastModel` comes with additional support:
- **Future covariates:** Use exogenous features to potentially improve predictive accuracy.
- It either uses the base model's native exogenous features, or
- It adds future covariates support by first regressing the series against the future covariates using a :class:`~darts.models.forecasting.linear_regression_model.LinearRegressionModel` model and then running the StatsForecast model on the in-sample residuals from this original regression. This approach was inspired by `this post of Stephan Kolassa <https://stats.stackexchange.com/q/220885>`__.
- **Probabilstic forecasting:** Some base models might require setting `prediction_intervals` at `model` creation to support probabilistic forecasting. To generate probabilistic forecasts, you can set the following parameters when calling :meth:`~darts.models.forecasting.sf_model.StatsForecastModel.predict`:
- Forecast quantile values directly by setting `predict_likelihood_parameters=True`.
- Generate sampled forecasts from these quantiles by setting `num_samples >> 1`.
- **Conformal prediction:** In addition to the native probabilistic support, you can perform conformal prediction / forecasting by setting `prediction_intervals` at model creation. Then predict the in the same way as described above.
- **Transferable series forecasting:** Apply the fitted model to a new input `series` at prediction time.
- It either uses the base model's native transferrable series support (StatsForecast models that support the `forward()` method), or
- It adds support by first fitting a copy of the model on the new series, and then using that model to generate the corresponding forecast.
.. note:: Future covariates are not supported when the input series contain missing values.
Parameters ---------- model Any StatsForecast model. add_encoders A large number of 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': {'future': ['relative']}, 'custom': {'future': [encode_year]}, 'transformer': Scaler(), 'tz': 'CET' } .. quantiles Optionally, produce quantile predictions at `quantiles` levels when performing probabilistic forecasting with `num_samples > 1` or `predict_likelihood_parameters=True`. random_state Controls the randomness for reproducible forecasting.
Examples -------- >>> from darts.datasets import AirPassengersDataset >>> from darts.models import StatsForecastModel >>> from darts.utils.timeseries_generation import datetime_attribute_timeseries >>> from statsforecast.models import AutoARIMA >>> series = AirPassengersDataset().load() >>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series >>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6) >>> # define AutoARIMA parameters >>> model = StatsForecastModel(model=AutoARIMA(season_length=12)) >>> model.fit(series, future_covariates=future_cov) >>> pred = model.predict(6, future_covariates=future_cov) >>> print(pred.values()) [[445.4276575 ] [420.04912881] [448.7142377 ] [491.23406559] [502.67834069] [566.04774778]]
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
Optional
Default: null
Optional
Default: null
Optional
Default: null
Optional
Default: null
Configuration example
Generated from documented defaults. Replace any placeholders and complete required nested settings before running.
templates:
- template_name: "StatsForecastModelWrapper"
class_name: "StatsForecastModelWrapper"
attributes:
validation_mode: false
forecast_horizon: 10
statsforecastmodel_init:
model: {}
quantiles: null
add_encoders: null
random_state: null
View original docstring example
The source example references XGBModelWrapper, not StatsForecastModelWrapper.
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.