mojolearn.ExponentialSmoothing#

class mojolearn.ExponentialSmoothing(endog, *, seasonal='additive', seasonal_periods=2, start_periods=2, ts_num=1, eps=0.00224, initialization_method='estimated')[source]#

Bases: object

Holt-Winters exponential smoothing for a batch of seasonal series.

Fits level, trend and season with additive or multiplicative seasonality, following cuml.tsa.ExponentialSmoothing. As in cuML (and unlike scikit-learn), the data goes to the constructor as endog, fit() takes no arguments, and forecast() produces forecasts. predict(), save() and load() are additions: a saved model forecasts and predicts without refitting, also on a CPU-only install.

The default initialization_method="estimated" differs from cuML: it estimates the initial level, trend and all seasonal states jointly with the smoothing parameters by minimizing the SSE over all points (statsmodels’ definition). "heuristic" (alias "cuml") reproduces cuML’s fit: initial states from a moving-average decomposition of the first start_periods seasons, then BFGS over the smoothing parameters only. The heuristic fit is faster and usually less accurate.

Computation is float32; float64 input is converted (and copied). Non-finite values are refused with the series and position, and multiplicative seasonality needs strictly positive data. The numeric mode is the process default (see mojolearn.set_numeric_mode()).

Parameters:

endog (array-like of shape (ts_num, n) or (n,)) – The series, one per row; 1-D is one series. n must be at least start_periods * seasonal_periods.
seasonal ({“additive”, “add”, “multiplicative”, “mul”}, default “additive”) – Seasonal component type.
seasonal_periods (int, default 2) – Season length, at least 2.
start_periods (int, default 2) – Seasons used to seed the initial states, between 2 and seasonal_periods.
ts_num (int, default 1) – Number of series; must match endog.
eps (float, default 2.24e-3) – Optimizer tolerance, greater than 0 (cuML’s default).
initialization_method ({“estimated”, “heuristic”, “cuml”}, default “estimated”) – How initial states are found, as described above.

Variables:

season_ (level_, trend_,) – Fitted components.
sse_ (Array of shape (ts_num,), float32) – Sum of squared errors: over all n points under "estimated", over points seasonal_periods to n - 1 under "heuristic" (cuML’s SSE).
gamma_ (alpha_, beta_,) – Fitted smoothing parameters.
n_iter_ (Array of shape (ts_num,), int32) – Optimizer iterations.
criterion_ (Array of shape (ts_num,), int32) – Why the optimizer stopped. Under "heuristic" (BFGS): 0 iteration limit, 1 parameter change below tolerance, 2 error change below tolerance, 3 gradient norm below tolerance. Under "estimated" (Levenberg-Marquardt): 0 iteration limit, 1 no step lowers the SSE, 2 relative SSE decrease below 1e-6.

Notes

cuML’s verbose and output_type are not accepted. Results are float32 mojolearn.Array objects. When the BFGS line search hits its iteration limit, the lowest-loss trial point is kept rather than the last one, so such fits can differ from cuML’s.

Examples

>>> import numpy as np, mojolearn
>>> t = np.arange(96, dtype=np.float32)
>>> y = 20 + 0.1 * t + 3 * np.sin(2 * np.pi * t / 12).astype(np.float32)
>>> model = mojolearn.ExponentialSmoothing(y, seasonal_periods=12).fit()
>>> np.asarray(model.forecast(12)).shape
(12,)

__init__(endog, *, seasonal='additive', seasonal_periods=2, start_periods=2, ts_num=1, eps=0.00224, initialization_method='estimated')[source]#

Methods

`fit`()	Fit level, trend, season and the smoothing parameters.
`forecast`([h, index])	Forecast `h` points per series.
`get_level`([index])	Fitted level component.
`get_season`([index])	Fitted season component.
`get_trend`([index])	Fitted trend component.
`load`(path)	Load a model written by save().
`predict`([start, end, index])	One-step-ahead predictions at times `start` to `end - 1`.
`save`(path)	Save the fitted model to an `.npz` file.
`score`([index])	Sum of squared errors of the fit, as cuML's `score` returns.

fit()[source]#

Fit level, trend, season and the smoothing parameters.

Returns:: self
Raises:: ValueError – If a constraint is violated: ts_num >= 1, seasonal_periods >= 2, start_periods >= 2, seasonal_periods >= start_periods, eps > 0, n >= start_periods * seasonal_periods; or for non-finite (or, multiplicative, non-positive) data.

forecast(h=1, index=None)[source]#

Forecast h points per series.

Parameters:

h (int, default 1) – Forecast horizon, greater than 0.
index (int or None, default None) – Return only this series.

Returns:

Array, float32 – Shapes follow cuML: (h, ts_num) when index is None and ts_num > 1; (h,) when ts_num == 1 or for a given index.

predict(start=0, end=None, index=None)[source]#

One-step-ahead predictions at times start to end - 1.

A time t < n is in sample: the prediction of endog[t] from the fitted state before it was observed. Times t < 2 * seasonal_periods are NaN, because the fit does not keep the state they need. A time t >= n is a forecast, so predict(n, n + h) equals forecast(h).

Parameters:

start (int, default 0) – First time index, at least 0.
end (int or None, default None) – Index to stop before; None means n. Must be greater than start.
index (int or None, default None) – Return only this series.

Returns:

Array, float32 – Shapes as for forecast(), with end - start steps.

save(path)[source]#

Save the fitted model to an .npz file.

The fitted components, smoothing parameters, diagnostics and settings are written; endog is not. A loaded model forecasts, predicts and exposes the fitted attributes without refitting, including on a CPU-only install (ExponentialSmoothing.load(path) or mojolearn.host_model(path)).

Parameters:: path (str or path-like) – Destination file.

classmethod load(path)[source]#

Load a model written by save().

Parameters:: path (str or path-like) – File written by save().
Returns:: ExponentialSmoothing – A fitted model that forecasts and predicts; it does not refit.

score(index=None)[source]#

Sum of squared errors of the fit, as cuML’s score returns.

Parameters:: index (int or None, default None) – None returns every series’ SSE; an integer returns that series’ SSE.
Returns:: Array of shape (ts_num,) or float32

get_level(index=None)[source]#

Fitted level component.

Parameters:: index (int or None, default None) – Return only this series.
Returns:: Array, float32 – (n - seasonal_periods, ts_num) when index is None and ts_num > 1; 1-D for one series or a given index.

get_trend(index=None)[source]#

Fitted trend component.

Parameters:: index (int or None, default None) – Return only this series.
Returns:: Array, float32 – (n - seasonal_periods, ts_num) when index is None and ts_num > 1; 1-D for one series or a given index.

get_season(index=None)[source]#

Fitted season component.

Parameters:: index (int or None, default None) – Return only this series.
Returns:: Array, float32 – (n - seasonal_periods, ts_num) when index is None and ts_num > 1; 1-D for one series or a given index.