LightGBMModelWrapper
Python template · sinapsis_darts_forecasting.templates.time_series_model
Overview
Base Template for Darts Time Series forecasting models.
LightGBMModel — 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.LGBM Model
Parameters ---------- lags Lagged target `series` values used to predict the next time step/s. If an integer, must be > 0. Uses the last `n=lags` past lags; e.g. `(-1, -2, ..., -lags)`, where `0` corresponds the first predicted time step of each sample. If `output_chunk_shift > 0`, then lag `-1` translates to `-1 - output_chunk_shift` steps before the first prediction step. If a list of integers, each value must be < 0. Uses only the specified values as lags. If a dictionary, the keys correspond to the `series` component names (of the first series when using multiple series) and the values correspond to the component lags (integer or list of integers). The key 'default_lags' can be used to provide default lags for un-specified components. Raises and error if some components are missing and the 'default_lags' key is not provided. lags_past_covariates Lagged `past_covariates` values used to predict the next time step/s. If an integer, must be > 0. Uses the last `n=lags_past_covariates` past lags; e.g. `(-1, -2, ..., -lags)`, where `0` corresponds to the first predicted time step of each sample. If `output_chunk_shift > 0`, then lag `-1` translates to `-1 - output_chunk_shift` steps before the first prediction step. If a list of integers, each value must be < 0. Uses only the specified values as lags. If a dictionary, the keys correspond to the `past_covariates` component names (of the first series when using multiple series) and the values correspond to the component lags (integer or list of integers). The key 'default_lags' can be used to provide default lags for un-specified components. Raises and error if some components are missing and the 'default_lags' key is not provided. lags_future_covariates Lagged `future_covariates` values used to predict the next time step/s. The lags are always relative to the first step in the output chunk, even when `output_chunk_shift > 0`. If a tuple of `(past, future)`, both values must be > 0. Uses the last `n=past` past lags and `n=future` future lags; e.g. `(-past, -(past - 1), ..., -1, 0, 1, .... future - 1)`, where `0` corresponds the first predicted time step of each sample. If `output_chunk_shift > 0`, the position of negative lags differ from those of `lags` and `lags_past_covariates`. In this case a future lag `-5` would point at the same step as a target lag of `-5 + output_chunk_shift`. If a list of integers, uses only the specified values as lags. If a dictionary, the keys correspond to the `future_covariates` component names (of the first series when using multiple series) and the values correspond to the component lags (tuple or list of integers). The key 'default_lags' can be used to provide default lags for un-specified components. Raises and error if some components are missing and the 'default_lags' key is not provided. output_chunk_length Number of time steps predicted at once (per chunk) by the internal model. It is not the same as forecast horizon `n` used in `predict()`, which is the desired number of prediction points generated using 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 (history of target and past covariates) and output. If the model supports `future_covariates`, the `lags_future_covariates` are relative to the first step in 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`). 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' } ..
.. note:: To enable past and / or future encodings for any `SKLearnModel`, you must also define the corresponding covariates lags with `lags_past_covariates` and / or `lags_future_covariates`. likelihood Can be set to `quantile` or `poisson`. If set, the model will be probabilistic, allowing sampling at prediction time. This will overwrite any `objective` parameter. quantiles Fit the model to these quantiles if the `likelihood` is set to `quantile`. random_state Controls the randomness for reproducible forecasting. multi_models If True, a separate model will be trained for each future lag to predict. If False, a single model is trained to predict all the steps in 'output_chunk_length' (features lags are shifted back by `output_chunk_length - n` for each step `n`). Default: True. use_static_covariates Whether the model should use static covariate information in case the input `series` passed to ``fit()`` contain static covariates. If ``True``, and static covariates are available at fitting time, will enforce that all target `series` have the same static covariate dimensionality in ``fit()`` and ``predict()``. categorical_past_covariates Optionally, component name or list of component names specifying the past covariates that should be treated as categorical by the underlying `lightgbm.LightGBMRegressor`. The components that are specified as categorical must be integer-encoded. For more information on how LightGBM handles categorical features, visit: `Categorical feature support documentation <https://lightgbm.readthedocs.io/en/latest/Features.html#optimal-split-for-categorical-features>`__. categorical_future_covariates Optionally, component name or list of component names specifying the future covariates that should be treated as categorical by the underlying `lightgbm.LightGBMRegressor`. The components that are specified as categorical must be integer-encoded. categorical_static_covariates Optionally, string or list of strings specifying the static covariates that should be treated as categorical by the underlying `lightgbm.LightGBMRegressor`. The components that are specified as categorical must be integer-encoded. **kwargs Additional keyword arguments passed to `lightgbm.LGBRegressor`.
Examples -------- >>> from darts.datasets import WeatherDataset >>> from darts.models import LightGBMModel >>> 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] >>> # optionally, use future temperatures (pretending this component is a forecast) >>> future_cov = series['T (degC)'][:106] >>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature >>> # values corresponding to the forecasted period >>> model = LightGBMModel( >>> lags=12, >>> lags_past_covariates=12, >>> lags_future_covariates=[0,1,2,3,4,5], >>> output_chunk_length=6, >>> verbose=-1 >>> ) >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov) >>> pred = model.predict(6) >>> print(pred.values()) [[1006.85376674] [1006.83998586] [1006.63884831] [1006.57201255] [1006.52290556] [1006.39550065]]
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: "LightGBMModelWrapper"
class_name: "LightGBMModelWrapper"
attributes:
validation_mode: false
forecast_horizon: 10
lightgbmmodel_init: {}
View original docstring example
The source example references XGBModelWrapper, not LightGBMModelWrapper.
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.