Feat/exp smoothing add argument (#2904)

* feat: add extra arguments for Exponential Smoothing model

* changelog update

* doc changes and PR suggestions

Author: jakubchlapek

CHANGELOG.md

@@ -16,6 +16,7 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 - `from_group_dataframe()` now supports creating `TimeSeries` from **additional DataFrame backends** (Polars, PyArrow, ...). We leverage `narwhals` as the compatibility layer between DataFrame libraries. See their [documentation](https://narwhals-dev.github.io/narwhals/) for all supported backends. [#2766](https://github.com/unit8co/darts/pull/2766) by [He Weilin](https://github.com/cnhwl).
 - Added `add_regressor_configs` parameter to the `Prophet` model, enabling component-specific control over `prior_scale`, `mode`, and `standardize` for the future covariates. [#2882](https://github.com/unit8co/darts/issues/2882) by [Ramsay Davis](https://github.com/RamsayDavisWL).
 - 🔴 Increased the decimal places for quantile component names from 2 to 3 for more precise quantiles. (e.g. `component_name_q0.500` for quantile 0.5). This affects quantile forecasts as well as quantiles computed with `TimeSeries.quantile()`. [#2887](https://github.com/unit8co/darts/pull/2786) by [He Weilin](https://github.com/cnhwl).
+- Added model creation parameters `random_errors` and `error` to `ExponentialSmoothing` that give control over how probabilistic forecasts are generated. [#2290491](https://github.com/unit8co/darts/pull/2904) by [Jakub Chłapek](https://github.com/jakubchlapek)
 
 **Fixed**
 

darts/models/forecasting/exponential_smoothing.py

@@ -25,6 +25,8 @@ def __init__(
         damped: Optional[bool] = False,
         seasonal: Optional[SeasonalityMode] = SeasonalityMode.ADDITIVE,
         seasonal_periods: Optional[int] = None,
+        error: Optional[str] = "add",
+        random_errors: Optional[Any] = None,
         random_state: Optional[int] = None,
         kwargs: Optional[dict[str, Any]] = None,
         **fit_kwargs,
@@ -63,6 +65,17 @@ def __init__(
         seasonal_periods
             The number of periods in a complete seasonal cycle, e.g., 4 for quarterly data or 7 for daily
             data with a weekly cycle. If not set, inferred from frequency of the series.
+        error
+            Specifies the type of error model for state space formulation to use when using predict()
+            with ``num_samples > 1``. Default is `"add"`.
+            Will be passed to statsmodels' :func:`simulate()` method. See the documentation `here
+            <https://www.statsmodels.org/stable/generated/statsmodels.tsa.holtwinters.HoltWintersResults.simulate.html>`_
+            for more information.
+        random_errors
+            Specifies how the random errors should be obtained, when using predict() with ``num_samples > 1``.
+            Will be passed to statsmodels' :func:`simulate()` method. See the documentation `here
+            <https://www.statsmodels.org/stable/generated/statsmodels.tsa.holtwinters.HoltWintersResults.simulate.html>`_
+            for more information.
         random_state
             Controls the randomness for reproducible forecasting.
         kwargs
@@ -100,6 +113,8 @@ def __init__(
         self.seasonal = seasonal
         self.infer_seasonal_periods = seasonal_periods is None
         self.seasonal_periods = seasonal_periods
+        self.error = error
+        self.random_errors = random_errors
         self.constructor_kwargs = dict() if kwargs is None else kwargs
         self.fit_kwargs = fit_kwargs
         self.model = None
@@ -156,7 +171,13 @@ def predict(
             rng = check_random_state(random_state)
 
             forecast = np.expand_dims(
-                self.model.simulate(n, repetitions=num_samples, random_state=rng),
+                self.model.simulate(
+                    n,
+                    repetitions=num_samples,
+                    random_state=rng,
+                    random_errors=self.random_errors,
+                    error=self.error,
+                ),
                 axis=1,
             )
 

darts/tests/models/forecasting/test_exponential_smoothing.py

@@ -91,3 +91,31 @@ def test_fit_kwargs(self):
         # forecasts should be slightly different
         assert pred.time_index.equals(pred_ls.time_index)
         assert all(np.not_equal(pred.values(), pred_ls.values()))
+
+    def test_random_errors(self):
+        """Test whether random_errors parameter is correctly passed to simulate()"""
+        series = tg.sine_timeseries(length=100, freq="H")
+        model = ExponentialSmoothing(random_state=42)
+        model.fit(series)
+        pred = model.predict(n=10, num_samples=10, random_state=42)
+
+        model_boot = ExponentialSmoothing(random_errors="bootstrap", random_state=42)
+        model_boot.fit(series)
+        pred_boot = model_boot.predict(n=10, num_samples=10, random_state=42)
+
+        # methods with different random_errors set should yield different forecasts
+        assert not np.allclose(pred.values(), pred_boot.values(), atol=1e-5)
+
+    def test_error(self):
+        """Test whether error parameter is correctly passed to simulate()"""
+        series = tg.sine_timeseries(length=100, freq="H")
+        model = ExponentialSmoothing(random_state=42)
+        model.fit(series)
+        pred = model.predict(n=10, num_samples=10, random_state=42)
+
+        model_boot = ExponentialSmoothing(error="mul", random_state=42)
+        model_boot.fit(series)
+        pred_boot = model_boot.predict(n=10, num_samples=10, random_state=42)
+
+        # methods with different error set should yield different forecasts
+        assert not np.allclose(pred.values(), pred_boot.values(), atol=1e-5)

darts/tests/models/forecasting/test_local_forecasting_models.py

@@ -665,7 +665,7 @@ def test_model_str_call(self, config):
             (
                 ExponentialSmoothing(),
                 "ExponentialSmoothing(trend=ModelMode.ADDITIVE, damped=False, seasonal=SeasonalityMode.ADDITIVE, "
-                + "seasonal_periods=None, random_state=None, kwargs=None)",
+                + "seasonal_periods=None, error=add, random_errors=None, random_state=None, kwargs=None)",
             ),  # no params changed
             (
                 ARIMA(1, 1, 1),