Holt-Winters

Install and import#

npm install fintech-algorithms

import { forecastHoltWintersAdditive } from "fintech-algorithms/statistical-time-series/forecast-models/holt-winters";

Signature#

forecastHoltWintersAdditive(values, alpha, beta, gamma, period, horizon, initialLevel, initialTrend, initialSeasonals)

Additive Holt-Winters: exponential smoothing of level, trend and seasonality. Unfashionable and frequently competitive with far more complex methods on short seasonal series.

Parameters#

Returns#

{ forecast, fitted, residuals, trace, state }

Forecasts with a trace of level, trend and seasonal components at each step.

Errors#

• When any smoothing factor falls outside 0…1, or initialSeasonals is not of length period — throws

Complexity: time O(n), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

[10, 12, 11, 13]

0.5

0.5

0.5

2

2

9

1

[-1, 1]

Call#

forecastHoltWintersAdditive(values, alpha, beta, gamma, period, horizon, initialLevel, initialTrend, initialSeasonals)

Returns#

object with 1 field: forecast

{
  "forecast": [12.35546875, 14.58203125]
}

Diagrams#

Calculation flow#

flowchart LR
    A["Finalized equally spaced training series"] --> B["Validate cutoff and frozen parameters"]
    B --> C["Build selected state or transformed series"]
    C --> D["Calculate horizon h conditional mean"]
    D --> E{"More horizons?"}
    E -- "yes" --> F["Append forecast and zero future innovation"]
    F --> D
    E -- "no" --> G["Publish path and state trace"]
    G --> H["Reveal holdout only for evaluation"]

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• Forecasting: Principles and Practice — Holt-Winters — Rob J. Hyndman and George Athanasopoulos
• Exponential smoothing examples — statsmodels developers
• Forecasting: Principles and Practice — Evaluating point forecast accuracy — Rob J. Hyndman and George Athanasopoulos
• Forecasting: Principles and Practice — Time series cross-validation — Rob J. Hyndman and George Athanasopoulos
• Forecasting: Principles and Practice — Evaluating regression and residual behavior — Rob J. Hyndman and George Athanasopoulos

The rest of the Forecast Models family#

• AutoRegForecasts from an autoregression with supplied coefficients.
• ARMAARMA forecasting with supplied coefficients: autoregressive terms on past values, moving-average terms on past errors.
• ARIMAARMA on a differenced series, with forecasts integrated back to the original level.
• SARIMA/SARIMAXSeasonal ARIMA with optional exogenous regressors.
• Theta ForecastThe Theta method: decompose, extrapolate, recombine.