docstr: Use a regression model for ensembling individual models' predictions using the stacking technique [1]_.
  
  The provided regression model must implement ``fit()`` and ``predict()`` methods
  (e.g. scikit-learn regression models). Note that here the regression model is used to learn how to
  best ensemble the individual forecasting models' forecasts. It is not the same usage of regression
  as in :class:`RegressionModel`, where the regression model is used to produce forecasts based on the
  lagged series.
  
  If `future_covariates` or `past_covariates` are provided at training or inference time,
  they will be passed only to the forecasting models supporting them.
  
  If `forecasting_models` contains exclusively GlobalForecastingModels, they can be pre-trained. Otherwise,
  the `forecasting_models` must be untrained.
  
  The regression model does not leverage the covariates passed to ``fit()`` and ``predict()``.
  
  Parameters
  ----------
  forecasting_models
      List of forecasting models whose predictions to ensemble
  regression_train_n_points
      The number of points per series to use to train the regression model. Can be set to `-1` to use the
      entire series to train the regressor if `forecasting_models` are already fitted and
      `train_forecasting_models=False`.
  regression_model
      Any regression model with ``predict()`` and ``fit()`` methods (e.g. from scikit-learn)
      Default: ``darts.model.LinearRegressionModel(fit_intercept=False)``
  
      .. note::
          if `regression_model` is probabilistic, the `RegressionEnsembleModel` will also be probabilistic.
      ..
  regression_train_num_samples
      Number of prediction samples from each forecasting model to train the regression model (samples are
      averaged). Should be set to 1 for deterministic models. Default: 1.
  
      .. note::
          if `forecasting_models` contains a mix of probabilistic and deterministic models,
          `regression_train_num_samples will be passed only to the probabilistic ones.
      ..
  regression_train_samples_reduction
      If `forecasting_models` are probabilistic and `regression_train_num_samples` > 1, method used to
      reduce the samples before passing them to the regression model. Possible values: "mean", "median"
      or float value corresponding to the desired quantile. Default: "median"
  train_forecasting_models
      If set to `False`, the `forecasting_models` are not retrained when calling `fit()` (only supported
      if all the `forecasting_models` are pretrained `GlobalForecastingModels`). Default: ``True``.
  train_using_historical_forecasts
      If set to `True`, use `historical_forecasts()` to generate the forecasting models' predictions used to
      train the regression model in `fit()`. Available when `forecasting_models` contains only
      `GlobalForecastingModels`. Recommended when `regression_train_n_points` is greater than
      `output_chunk_length` of the underlying `forecasting_models`.
      Default: ``False``.
  show_warnings
      Whether to show warnings related to forecasting_models covariates support.
  References
  ----------
  .. [1] D. H. Wolpert, “Stacked generalization”, Neural Networks, vol. 5, no. 2, pp. 241–259, Jan. 1992
  
  Examples
  --------
  >>> from darts.datasets import AirPassengersDataset
  >>> from darts.models import RegressionEnsembleModel, NaiveSeasonal, LinearRegressionModel
  >>> series = AirPassengersDataset().load()
  >>> model = RegressionEnsembleModel(
  >>>     forecasting_models = [
  >>>         NaiveSeasonal(K=12),
  >>>         LinearRegressionModel(lags=4)
  >>>     ],
  >>>     regression_train_n_points=20
  >>> )
  >>> model.fit(series)
  >>> pred = model.predict(6)
  >>> pred.values()
  array([[494.24050364],
         [464.3869697 ],
         [496.53180506],
         [544.82269341],
         [557.35256055],
         [630.24334385]])
docstr_tok: ["Use","a","regression","model","for","ensembling","individual","models","'","predictions","using","the","stacking","technique","[","1","]","_",".","The","provided","regression","model","must","implement","``","fit","(",")","``","and","``","predict","(",")","``","methods","(","e.g",".","scikit-learn","regression","models",")",".","Note","that","here","the","regression","model","is","used","to","learn","how","to","best","ensemble","the","individual","forecasting","models","'","forecasts",".","It","is","not","the","same","usage","of","regression","as","in",":","class",":","`","RegressionModel","`",",","where","the","regression","model","is","used","to","produce","forecasts","based","on","the","lagged","series",".","If","`","future_covariates","`","or","`","past_covariates","`","are","provided","at","training","or","inference","time",",","they","will","be","passed","only","to","the","forecasting","models","supporting","them",".","If","`","forecasting_models","`","contains","exclusively","GlobalForecastingModels",",","they","can","be","pre-trained",".","Otherwise",",","the","`","forecasting_models","`","must","be","untrained",".","The","regression","model","does","not","leverage","the","covariates","passed","to","``","fit","(",")","``","and","``","predict","(",")","``",".","Parameters","--","--","--","--","--","forecasting_models","List","of","forecasting","models","whose","predictions","to","ensemble","regression_train_n_points","The","number","of","points","per","series","to","use","to","train","the","regression","model",".","Can","be","set","to","`","-1","`","to","use","the","entire","series","to","train","the","regressor","if","`","forecasting_models","`","are","already","fitted","and","`","train_forecasting_models=False","`",".","regression_model","Any","regression","model","with","``","predict","(",")","``","and","``","fit","(",")","``","methods","(","e.g",".","from","scikit-learn",")","Default",":","``","darts.model.LinearRegressionModel","(","fit_intercept=False",")","``","..","note",":",":","if","`","regression_model","`","is","probabilistic",",","the","`","RegressionEnsembleModel","`","will","also","be","probabilistic",".","..","regression_train_num_samples","Number","of","prediction","samples","from","each","forecasting","model","to","train","the","regression","model","(","samples","are","averaged",")",".","Should","be","set","to","1","for","deterministic","models",".","Default",":","1",".","..","note",":",":","if","`","forecasting_models","`","contains","a","mix","of","probabilistic","and","deterministic","models",",","`","regression_train_num_samples","will","be","passed","only","to","the","probabilistic","ones",".","..","regression_train_samples_reduction","If","`","forecasting_models","`","are","probabilistic","and","`","regression_train_num_samples","`",">","1",",","method","used","to","reduce","the","samples","before","passing","them","to","the","regression","model",".","Possible","values",":","``","mean","''",",","``","median","''","or","float","value","corresponding","to","the","desired","quantile",".","Default",":","``","median","''","train_forecasting_models","If","set","to","`","False","`",",","the","`","forecasting_models","`","are","not","retrained","when","calling","`","fit","(",")","`","(","only","supported","if","all","the","`","forecasting_models","`","are","pretrained","`","GlobalForecastingModels","`",")",".","Default",":","``","True","``",".","train_using_historical_forecasts","If","set","to","`","True","`",",","use","`","historical_forecasts","(",")","`","to","generate","the","forecasting","models","'","predictions","used","to","train","the","regression","model","in","`","fit","(",")","`",".","Available","when","`","forecasting_models","`","contains","only","`","GlobalForecastingModels","`",".","Recommended","when","`","regression_train_n_points","`","is","greater","than","`","output_chunk_length","`","of","the","underlying","`","forecasting_models","`",".","Default",":","``","False","``",".","show_warnings","Whether","to","show","warnings","related","to","forecasting_models","covariates","support",".","References","--","--","--","--","--","..","[","1","]","D.","H.","Wolpert",",","\u201c","Stacked","generalization","\u201d",",","Neural","Networks",",","vol",".","5",",","no",".","2",",","pp",".","241\u2013259",",","Jan.","1992","Examples","--","--","--","--",">",">",">","from","darts.datasets","import","AirPassengersDataset",">",">",">","from","darts.models","import","RegressionEnsembleModel",",","NaiveSeasonal",",","LinearRegressionModel",">",">",">","series","=","AirPassengersDataset","(",")",".load","(",")",">",">",">","model","=","RegressionEnsembleModel","(",">",">",">","forecasting_models","=","[",">",">",">","NaiveSeasonal","(","K=12",")",",",">",">",">","LinearRegressionModel","(","lags=4",")",">",">",">","]",",",">",">",">","regression_train_n_points=20",">",">",">",")",">",">",">","model.fit","(","series",")",">",">",">","pred","=","model.predict","(","6",")",">",">",">","pred.values","(",")","array","(","[","[","494.24050364","]",",","[","464.3869697","]",",","[","496.53180506","]",",","[","544.82269341","]",",","[","557.35256055","]",",","[","630.24334385","]","]",")"]
code: def __init__(
      self,
      forecasting_models: List[ForecastingModel],
      regression_train_n_points: int,
      regression_model=None,
      regression_train_num_samples: int = 1,
      regression_train_samples_reduction: Optional[
          Union[str, float]
      ] = "median",
      train_forecasting_models: bool = True,
      train_using_historical_forecasts: bool = False,
      show_warnings: bool = True,
  ):
      """
      Use a regression model for ensembling individual models' predictions using the stacking technique [1]_.
  
      The provided regression model must implement ``fit()`` and ``predict()`` methods
      (e.g. scikit-learn regression models). Note that here the regression model is used to learn how to
      best ensemble the individual forecasting models' forecasts. It is not the same usage of regression
      as in :class:`RegressionModel`, where the regression model is used to produce forecasts based on the
      lagged series.
  
      If `future_covariates` or `past_covariates` are provided at training or inference time,
      they will be passed only to the forecasting models supporting them.
  
      If `forecasting_models` contains exclusively GlobalForecastingModels, they can be pre-trained. Otherwise,
      the `forecasting_models` must be untrained.
  
      The regression model does not leverage the covariates passed to ``fit()`` and ``predict()``.
  
      Parameters
      ----------
      forecasting_models
          List of forecasting models whose predictions to ensemble
      regression_train_n_points
          The number of points per series to use to train the regression model. Can be set to `-1` to use the
          entire series to train the regressor if `forecasting_models` are already fitted and
          `train_forecasting_models=False`.
      regression_model
          Any regression model with ``predict()`` and ``fit()`` methods (e.g. from scikit-learn)
          Default: ``darts.model.LinearRegressionModel(fit_intercept=False)``
  
          .. note::
              if `regression_model` is probabilistic, the `RegressionEnsembleModel` will also be probabilistic.
          ..
      regression_train_num_samples
          Number of prediction samples from each forecasting model to train the regression model (samples are
          averaged). Should be set to 1 for deterministic models. Default: 1.
  
          .. note::
              if `forecasting_models` contains a mix of probabilistic and deterministic models,
              `regression_train_num_samples will be passed only to the probabilistic ones.
          ..
      regression_train_samples_reduction
          If `forecasting_models` are probabilistic and `regression_train_num_samples` > 1, method used to
          reduce the samples before passing them to the regression model. Possible values: "mean", "median"
          or float value corresponding to the desired quantile. Default: "median"
      train_forecasting_models
          If set to `False`, the `forecasting_models` are not retrained when calling `fit()` (only supported
          if all the `forecasting_models` are pretrained `GlobalForecastingModels`). Default: ``True``.
      train_using_historical_forecasts
          If set to `True`, use `historical_forecasts()` to generate the forecasting models' predictions used to
          train the regression model in `fit()`. Available when `forecasting_models` contains only
          `GlobalForecastingModels`. Recommended when `regression_train_n_points` is greater than
          `output_chunk_length` of the underlying `forecasting_models`.
          Default: ``False``.
      show_warnings
          Whether to show warnings related to forecasting_models covariates support.
      References
      ----------
      .. [1] D. H. Wolpert, “Stacked generalization”, Neural Networks, vol. 5, no. 2, pp. 241–259, Jan. 1992
  
      Examples
      --------
      >>> from darts.datasets import AirPassengersDataset
      >>> from darts.models import RegressionEnsembleModel, NaiveSeasonal, LinearRegressionModel
      >>> series = AirPassengersDataset().load()
      >>> model = RegressionEnsembleModel(
      >>>     forecasting_models = [
      >>>         NaiveSeasonal(K=12),
      >>>         LinearRegressionModel(lags=4)
      >>>     ],
      >>>     regression_train_n_points=20
      >>> )
      >>> model.fit(series)
      >>> pred = model.predict(6)
      >>> pred.values()
      array([[494.24050364],
             [464.3869697 ],
             [496.53180506],
             [544.82269341],
             [557.35256055],
             [630.24334385]])
      """
      super().__init__(
          forecasting_models=forecasting_models,
          train_num_samples=regression_train_num_samples,
          train_samples_reduction=regression_train_samples_reduction,
          train_forecasting_models=train_forecasting_models,
          show_warnings=show_warnings,
      )
  
      if regression_model is None:
          regression_model = LinearRegressionModel(
              lags=None, lags_future_covariates=[0], fit_intercept=False
          )
      elif isinstance(regression_model, RegressionModel):
          regression_model = regression_model
      else:
          # scikit-learn like model
          regression_model = RegressionModel(
              lags_future_covariates=[0], model=regression_model
          )
  
      # check lags of the regression model
      raise_if_not(
          regression_model.lags == {"future": [0]},
          f"`lags` and `lags_past_covariates` of regression model must be `None`"
          f"and `lags_future_covariates` must be [0]. Given:\n"
          f"{regression_model.lags}",
      )
  
      self.regression_model: RegressionModel = regression_model
  
      raise_if(
          regression_train_n_points == -1
          and not (self.all_trained and (not train_forecasting_models)),
          "`regression_train_n_points` can only be `-1` if `retrain_forecasting_model=False` and "
          "all `forecasting_models` are already fitted.",
          logger,
      )
  
      # converted to List[int] if regression_train_n_points=-1 and ensemble is trained with multiple series
      self.train_n_points: Union[
          int, List[int]
      ] = regression_train_n_points
  
      raise_if(
          train_using_historical_forecasts
          and not self.is_global_ensemble,
          "`train_using_historical_forecasts=True` is only available when all "
          "`forecasting_models` are global models.",
          logger,
      )
  
      self.train_using_historical_forecasts = (
          train_using_historical_forecasts
      )
  
file_path: darts/darts/models/forecasting/regression_ensemble_model.py
imports: from typing import List, Optional, Sequence, Tuple, Union
  from darts.logging import get_logger, raise_if, raise_if_not
  from darts.models.forecasting.ensemble_model import EnsembleModel
  from darts.models.forecasting.forecasting_model import ForecastingModel
  from darts.models.forecasting.linear_regression_model import LinearRegressionModel
  from darts.models.forecasting.regression_model import RegressionModel
  from darts.timeseries import TimeSeries, concatenate
  from darts.utils.utils import seq2series, series2seq
label_desc: Use image node_id 1 to create a new RegressionEnsembleModel object from inherited base classes: EnsembleModel with example: obj = RegressionEnsembleModel(forecasting_models, regression_train_n_points, regression_model, regression_train_num_samples, regression_train_samples_reduction, train_forecasting_models, train_using_historical_forecasts, show_warnings)