docstr: Linear regression 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 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 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.
      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 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 auto-regressive 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).
  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'
          }
      ..
  likelihood
      Can be set to `quantile` or `poisson`. If set, the model will be probabilistic, allowing sampling at
      prediction time. If set to `quantile`, the `sklearn.linear_model.QuantileRegressor` is used. Similarly, if
      set to `poisson`, the `sklearn.linear_model.PoissonRegressor` is used.
  quantiles
      Fit the model to these quantiles if the `likelihood` is set to `quantile`.
  random_state
      Control the randomness of the sampling. Used as seed for
      `numpy.random.Generator
      <https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator>`_. Ignored when
      no `likelihood` is set.
      Default: ``None``.
  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 at step 'output_chunk_length' in the future. 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()``.
  **kwargs
      Additional keyword arguments passed to `sklearn.linear_model.LinearRegression` (by default), to
      `sklearn.linear_model.PoissonRegressor` (if `likelihood="poisson"`), or to
      `sklearn.linear_model.QuantileRegressor` (if `likelihood="quantile"`).
  
  Examples
  --------
  Deterministic forecasting, using past/future covariates (optional)
  
  >>> from darts.datasets import WeatherDataset
  >>> from darts.models import LinearRegressionModel
  >>> 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 = LinearRegressionModel(
  >>>     lags=12,
  >>>     lags_past_covariates=12,
  >>>     lags_future_covariates=[0,1,2,3,4,5],
  >>>     output_chunk_length=6,
  >>> )
  >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
  >>> pred = model.predict(6)
  >>> pred.values()
  array([[1005.72085839],
         [1005.6548696 ],
         [1005.65403772],
         [1005.6846175 ],
         [1005.75753605],
         [1005.81830675]])
docstr_tok: ["Linear","regression","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","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","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",".","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","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","auto-regressive","forecast",".","Setting","`","n","<","=","output_chunk_length","`","prevents","auto-regression",".","This","is","useful","when","the","covariates","do","n'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",")",".","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'","}","..","likelihood","Can","be","set","to","`","quantile","`","or","`","poisson","`",".","If","set",",","the","model","will","be","probabilistic",",","allowing","sampling","at","prediction","time",".","If","set","to","`","quantile","`",",","the","`","sklearn.linear_model.QuantileRegressor","`","is","used",".","Similarly",",","if","set","to","`","poisson","`",",","the","`","sklearn.linear_model.PoissonRegressor","`","is","used",".","quantiles","Fit","the","model","to","these","quantiles","if","the","`","likelihood","`","is","set","to","`","quantile","`",".","random_state","Control","the","randomness","of","the","sampling",".","Used","as","seed","for","`","numpy.random.Generator","<","https",":","\/\/numpy.org\/doc\/stable\/reference\/random\/generator.html","#","numpy.random.Generator",">","`","_",".","Ignored","when","no","`","likelihood","`","is","set",".","Default",":","``","None","``",".","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","at","step","'output_chunk_length","'","in","the","future",".","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","(",")","``",".","*","*","kwargs","Additional","keyword","arguments","passed","to","`","sklearn.linear_model.LinearRegression","`","(","by","default",")",",","to","`","sklearn.linear_model.PoissonRegressor","`","(","if","`","likelihood=","''","poisson","''","`",")",",","or","to","`","sklearn.linear_model.QuantileRegressor","`","(","if","`","likelihood=","''","quantile","''","`",")",".","Examples","--","--","--","--","Deterministic","forecasting",",","using","past\/future","covariates","(","optional",")",">",">",">","from","darts.datasets","import","WeatherDataset",">",">",">","from","darts.models","import","LinearRegressionModel",">",">",">","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","=","LinearRegressionModel","(",">",">",">","lags=12",",",">",">",">","lags_past_covariates=12",",",">",">",">","lags_future_covariates=","[","0,1,2,3,4,5","]",",",">",">",">","output_chunk_length=6",",",">",">",">",")",">",">",">","model.fit","(","target",",","past_covariates=past_cov",",","future_covariates=future_cov",")",">",">",">","pred","=","model.predict","(","6",")",">",">",">","pred.values","(",")","array","(","[","[","1005.72085839","]",",","[","1005.6548696","]",",","[","1005.65403772","]",",","[","1005.6846175","]",",","[","1005.75753605","]",",","[","1005.81830675","]","]",")"]
code: def __init__(
      self,
      lags: Optional[LAGS_TYPE] = None,
      lags_past_covariates: Optional[LAGS_TYPE] = None,
      lags_future_covariates: Optional[FUTURE_LAGS_TYPE] = None,
      output_chunk_length: int = 1,
      add_encoders: Optional[dict] = None,
      likelihood: Optional[str] = None,
      quantiles: Optional[List[float]] = None,
      random_state: Optional[int] = None,
      multi_models: Optional[bool] = True,
      use_static_covariates: bool = True,
      **kwargs,
  ):
      """Linear regression 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 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 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.
          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 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 auto-regressive 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).
      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'
              }
          ..
      likelihood
          Can be set to `quantile` or `poisson`. If set, the model will be probabilistic, allowing sampling at
          prediction time. If set to `quantile`, the `sklearn.linear_model.QuantileRegressor` is used. Similarly, if
          set to `poisson`, the `sklearn.linear_model.PoissonRegressor` is used.
      quantiles
          Fit the model to these quantiles if the `likelihood` is set to `quantile`.
      random_state
          Control the randomness of the sampling. Used as seed for
          `numpy.random.Generator
          <https://numpy.org/doc/stable/reference/random/generator.html#numpy.random.Generator>`_. Ignored when
          no `likelihood` is set.
          Default: ``None``.
      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 at step 'output_chunk_length' in the future. 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()``.
      **kwargs
          Additional keyword arguments passed to `sklearn.linear_model.LinearRegression` (by default), to
          `sklearn.linear_model.PoissonRegressor` (if `likelihood="poisson"`), or to
          `sklearn.linear_model.QuantileRegressor` (if `likelihood="quantile"`).
  
      Examples
      --------
      Deterministic forecasting, using past/future covariates (optional)
  
      >>> from darts.datasets import WeatherDataset
      >>> from darts.models import LinearRegressionModel
      >>> 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 = LinearRegressionModel(
      >>>     lags=12,
      >>>     lags_past_covariates=12,
      >>>     lags_future_covariates=[0,1,2,3,4,5],
      >>>     output_chunk_length=6,
      >>> )
      >>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
      >>> pred = model.predict(6)
      >>> pred.values()
      array([[1005.72085839],
             [1005.6548696 ],
             [1005.65403772],
             [1005.6846175 ],
             [1005.75753605],
             [1005.81830675]])
      """
      self.kwargs = kwargs
      self._median_idx = None
      self._model_container = None
      self.quantiles = None
      self.likelihood = likelihood
      self._rng = None
  
      # parse likelihood
      available_likelihoods = ["quantile", "poisson"]  # to be extended
      if likelihood is not None:
          self._check_likelihood(likelihood, available_likelihoods)
          self._rng = np.random.default_rng(seed=random_state)
  
          if likelihood == "poisson":
              model = PoissonRegressor(**kwargs)
          if likelihood == "quantile":
              model = QuantileRegressor(**kwargs)
              (
                  self.quantiles,
                  self._median_idx,
              ) = self._prepare_quantiles(quantiles)
              self._model_container = self._get_model_container()
      else:
          model = LinearRegression(**kwargs)
  
      super().__init__(
          lags=lags,
          lags_past_covariates=lags_past_covariates,
          lags_future_covariates=lags_future_covariates,
          output_chunk_length=output_chunk_length,
          add_encoders=add_encoders,
          model=model,
          multi_models=multi_models,
          use_static_covariates=use_static_covariates,
      )
  
file_path: darts/darts/models/forecasting/linear_regression_model.py
imports: from typing import List, Optional, Sequence, Union
  import numpy
  from scipy.optimize import linprog
  from sklearn.linear_model import LinearRegression, PoissonRegressor, QuantileRegressor
  from darts.logging import get_logger
  from darts.models.forecasting.regression_model import FUTURE_LAGS_TYPE, LAGS_TYPE, RegressionModel, _LikelihoodMixin
  from darts.timeseries import TimeSeries
label_desc: Use image node_id 1 to create a new LinearRegressionModel object from inherited base classes: RegressionModel, _LikelihoodMixin with example: obj = LinearRegressionModel(lags, lags_past_covariates, lags_future_covariates, output_chunk_length, add_encoders, likelihood, quantiles, random_state, multi_models, use_static_covariates)