Implements the Holt-Winters forecasting algorithm for time series data. More...

#include <fx_holt_winters_forecaster.h>

Public Member Functions
void	initialize_model (const Series &batch)
	Initialize Holt-Winters model if sufficient history exists. More...

Advance_Result	advance (const Series &batch)
	Advance the Holt-Winters model with new observations. More...

Point_Forecast	forecast_at (int k_minutes)
	Generate an h-minute-ahead forecast from current state. More...

Holt_Winters_State &	state ()
	Return the Holt-Winters state for updating. More...

void	reset_model ()
	Reset the Holt-Winters model to its default/uninitialized values. More...

Private Member Functions
void	ingest_one (int64_t ts, double yt, Advance_Result &ar)
	Process a single observation into the Holt-Winters state. More...

Private Attributes
Holt_Winters_State	m_state

Detailed Description

Implements the Holt-Winters forecasting algorithm for time series data.

The Holt-Winters method predicts future values in a time series based on past observations. This class provides an implementation of the Holt-Winters algorithm, allowing users to:

Initialize the model using historical data (initialize_model)
Advance the state based on new data (advance)
Generate forecasts for future time steps (forecast_at)

Note: This class is designed to work with time series data represented as a sequence of Sample objects.

Member Function Documentation

◆ advance()

Advance_Result Holt_Winters_Forecaster::advance ( const Series & batch )

Advance the Holt-Winters model with new observations.

Process every observation in batch using ingest_one().

Parameters

batch Time series of samples, this batch is the unprocessed tail

Returns: Advance_Result Number of observations processed.

Note: Assumes a write lock on the forecast model is active.

◆ forecast_at()

Point_Forecast Holt_Winters_Forecaster::forecast_at ( int k_minutes )

Generate an h-minute-ahead forecast from current state.

Forecast = level + (k_minutes * trend) + seasonal[(T - m + h) mod m]. Adds 95% confidence interval using residual standard deviation.

Parameters

k_minutes Horizon in minutes (e.g. 60, 1440, 10080).

Returns: Point_Forecast Predicted value, CI bounds, and target timestamp.

Note: Seasonal index is aligned one full cycle back: (T - m + h) mod m.

◆ ingest_one()

void Holt_Winters_Forecaster::ingest_one	(	int64_t	ts,
		double	yt,
		Advance_Result &	ar
	)

private

Process a single observation into the Holt-Winters state.

Steps:

Read the seasonal component from one full cycle (day) back.
Compute one-step-ahead fitted value and residual for this data point (yt).
Update level, trend, and seasonal components using smoothing equations.
Record residual into Welford stats for confidence intervals.
Parameters

ts Timestamp (unix seconds) of this observation

yt Observed value at time ts

ar Advance result

Note
The seasonal slot for this phase (minute of day) is overwritten with the new seasonal estimate after use. This guarantees 'seasonal alignment.' The term 'global index' simply means the index of the entire set of disk metrics, of which the current time series batch is a subset.

Assumes a write lock on the forecast model is active.

◆ initialize_model()

void Holt_Winters_Forecaster::initialize_model ( const Series & batch )

Initialize Holt-Winters model if sufficient history exists.

Requires at least two full seasonal cycles. Computes:

Initial trend as the average per-step difference between corresponding points in the first two seasons.
Initial level as the mean of the first season.
Initial seasonal components as (y_t - (level + t * trend)).
Parameters

batch Time series (must contain at least 2*m samples).

Note
This must be called before any advance() if the model is not initialized.

Assumes a write lock on the forecast model is active.

◆ reset_model()

void Holt_Winters_Forecaster::reset_model ( )

Reset the Holt-Winters model to its default/uninitialized values.

Clears all fitted parameters and statistics, requiring re-initialization or retraining before the forecaster can be used again.

◆ state()

Holt_Winters_State & Holt_Winters_Forecaster::state ( )

inline

Return the Holt-Winters state for updating.

Member Data Documentation

◆ m_state

Holt_Winters_State Holt_Winters_Forecaster::m_state