Holt-Winters | kube-res-foresight

Purpose and workload fit

Models level, trend, and seasonality with additive or multiplicative seasons and optional damped trend. Suitable for cyclic demand with changing levels.

History and runtime requirements

At least two complete cycles with seasonality, or four observations without it.

Inputs must be regularly sampled, gap-free, and finite. Outputs retain the metric unit, such as CPU cores, memory bytes, or requests per second. The sample interval determines the duration of a step. Minimum history permits execution; it does not establish forecast quality.

This method does not use covariates; target metrics are forecast separately.

Parameter reference

On narrow screens, swipe the parameter table horizontally to read all columns.

Parameter / type	Default / range / unit	Meaning and use
`season_length_steps` int	0 ≥ 0; steps	Season length in sample steps; zero disables seasonality where allowed. Seasonal Naive requires an explicit cycle.
`trend` bool	true No additional range	Include a trend component.
`damped` bool	false No additional range	Damp the trend using damping_phi.
`alpha` float	0 ≥ 0; ≤ 1	Level smoothing coefficient. Zero selects it automatically for Holt-Winters and Theta; larger values react faster.
`beta` float	0 ≥ 0; ≤ 1	Trend smoothing coefficient; zero selects it automatically.
`gamma` float	0 ≥ 0; ≤ 1	Seasonal smoothing coefficient; zero selects it automatically.
`seasonal_mode` string	"additive" additive / multiplicative	Additive seasonality or multiplicative scaling. Multiplicative needs strictly positive data and a season of at least two steps.
`damping_phi` float	0.98 ≥ 0.8; ≤ 1	Trend damping factor when damped=true; smaller values decay faster, one disables damping.
`non_negative` bool	true No additional range	Clamp forecasts to zero or above.

Configuration example

Edit parameters in Algorithm management. This is a parameter object, not a complete config.yaml. Seasonal examples assume five-minute sampling; adjust for your actual interval. Omitted optional values use the defaults above.

JSON

{
  "season_length_steps": 288,
  "trend": true,
  "damped": true,
  "seasonal_mode": "additive",
  "damping_phi": 0.98
}

Tuning and tradeoffs

Start with automatic smoothing coefficients (0). Enable damped to limit distant trend growth. Multiplicative mode needs a season of at least two steps and strictly positive history; use additive for zeros.

Shared parameters: shifts and quantiles

Parameter / type	Default / range / unit	Meaning and use
`reset_on_change` bool	false No additional range	Use history after a detected level shift, preserving enough points for the underlying method.
`change_threshold` float	8 ≥ 3; ≤ 50	Minimum shift relative to robust noise; used only with reset_on_change.
`change_min_shift` float	0.2 ≥ 0; ≤ 5	Minimum relative level shift; 0.2 means 20%. Used only with reset_on_change.
`quantile_level` float	0 ≥ 0; ≤ 0.99	Zero disables conformal calibration; otherwise must be above 0.5 and at most 0.99. Calibrates an upper forecast using earlier forecast errors.
`calibration_windows` int	8 ≥ 3; ≤ 50	Historical windows for conformal calibration; more windows add forecast calls and history requirements.

quantile_level uses a 0–1 scale; percentile uses 1–100. Calibration runs extra historical forecasts. Check history and runtime budgets before increasing windows; coverage is an evaluation target, not a guarantee.

Use in a module

Save parameters and check history, sample interval, and horizon.
Enable module prediction. Fixed mode runs the selected method; dynamic mode uses centrally enabled methods.
Run rolling backtests and earn version promotion before adoption. Re-run backtests after changes affecting model identity.
Review error, peak underestimation, runtime, and adoption reasons in Observe or Recommend before separately authorizing admission and replica actions.

For insufficient history, invalid settings, timeouts, or invalid output, inspect run reasons. Without eligible forecasts, the module follows its schedules, fallback, and protection rules.

Backtesting and evaluation · Recommendations and look-ahead