ETSForecaster¶

class omnicast.ETSForecaster(trend='add', seasonal=None, seasonal_period=None, damped_trend=False)[source]

Bases: BaseForecaster

Error-trend-seasonal state-space model with automatic component defaults.

Examples

>>> import pandas as pd
>>> from omnicast import ETSForecaster
>>> y = pd.Series([10.0, 12.0, 11.0, 13.0, 15.0, 14.0])
>>> model = ETSForecaster(trend="add").fit(y)
>>> model.predict(horizon=2).mean.round(2).tolist()
[15.6, 16.49]

Pass seasonal="add" (or "mul") with seasonal_period set to model a repeating cycle alongside the trend.

Notes

When to use this model¶
Best for	Series with a known trend/seasonal shape where you want a full statistical fit (AIC/BIC, parameter confidence intervals) rather than an approximation
Avoid when	You want the trend/seasonal order searched for you (see `AutoARIMAForecaster`) or need exogenous regressors
Handles trend	Yes, via `trend` (`"add"`, `"mul"`, or `None`)
Handles seasonality	Yes, via `seasonal` + `seasonal_period`
Extra dependencies	None (uses `statsmodels`)
Min. observations	Enough for `statsmodels` to estimate the requested components; at least `2 * seasonal_period` when seasonal

Parameters:

trend (str | None)
seasonal (str | None)
seasonal_period (int | None)
damped_trend (bool)

fit(y, X=None)

Return type:

BaseForecaster

Parameters:

y (Iterable[float] | Series)
X (object)

fit_predict(y, horizon, **kwargs)

Return type:

ForecastResult

Parameters:

y (Iterable[float] | Series)
horizon (int)
kwargs (object)

get_params()

Return type:: dict[str, object]

predict(horizon, X=None, level=(80, 95))

Return type:

ForecastResult

Parameters:

horizon (int)
X (object)
level (float | Iterable[float])

Error-trend-seasonal exponential smoothing as a state-space model (statsmodels.tsa.exponential_smoothing.ets.ETSModel), with additive error by construction. Give it explicit knowledge of the series’ trend and seasonal structure rather than having it searched for you (see AutoARIMAForecaster / AutoForecaster for automatic selection).

from omnicast import ETSForecaster

model = ETSForecaster(
    trend="add",
    seasonal="add",
    seasonal_period=12,
    damped_trend=False,
).fit(y)
forecast = model.predict(horizon=6, level=[80, 95])
print(forecast.to_frame())

           mean  lower_80  upper_80  lower_95  upper_95
2026-01  207.05    205.12    208.99    204.09    210.01
2026-02  215.37    213.43    217.31    212.41    218.33
2026-03  220.41    218.47    222.35    217.44    223.38
2026-04  225.69    223.74    227.63    222.71    228.66
2026-05  226.02    224.07    227.97    223.03    229.01
2026-06  224.21    222.25    226.17    221.21    227.21

Because it’s a proper state-space fit rather than an approximation, ETSForecaster exposes the full statistical estimator surface:

model.params_                                # fitted smoothing/seasonal parameters
model.parameter_confidence_intervals_        # 95% CIs for each parameter
model.aic_, model.bic_                       # for comparing against ARIMA, Theta, etc.

trend and seasonal accept "add", "mul", or None. Passing seasonal="add" (or "mul") without a seasonal_period raises ValueError – the model needs to know the cycle length, it won’t guess it. Set damped_trend=True to flatten long-horizon trend extrapolation, useful when a linear trend is implausible far into the future.