Documentation
¶
Overview ¶
Package models provides forecasting model implementations.
Package models provides forecasting model interfaces and implementations for Kedastral.
Models consume historical metric data in the form of FeatureFrames and produce Forecasts representing predicted future values over a specified horizon. The baseline model implementation uses exponential moving averages and optional seasonality patterns for prediction.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ARIMAModel ¶ added in v0.1.2
type ARIMAModel struct {
// contains filtered or unexported fields
}
ARIMAModel implements the Model interface using AutoRegressive Integrated Moving Average.
ARIMA(p,d,q) where:
- p: AutoRegressive order (how many past values to use)
- d: Differencing order (trend removal: 0=none, 1=linear, 2=quadratic)
- q: Moving Average order (how many past errors to use)
The model requires training on historical data before making predictions. It is thread-safe for concurrent Predict calls after training.
func NewARIMAModel ¶ added in v0.1.2
func NewARIMAModel(metric string, stepSec, horizonSec int, p, d, q int) *ARIMAModel
NewARIMAModel creates a new ARIMA model with the specified parameters.
Parameters:
- metric: Metric name to forecast
- stepSec: Step size in seconds between predictions (must be > 0)
- horizonSec: Forecast horizon in seconds (must be >= stepSec)
- p: AR order (0 = auto-detect, defaults to 1)
- d: Differencing order (0 = auto-detect, defaults to 1; max 2)
- q: MA order (0 = auto-detect, defaults to 1)
Auto-detection (p=0, d=0, or q=0) uses sensible defaults for general-purpose forecasting.
Panics if metric is empty, stepSec <= 0, horizonSec < stepSec, or d > 2.
func (*ARIMAModel) Name ¶ added in v0.1.2
func (m *ARIMAModel) Name() string
Name returns the model name with ARIMA parameters.
func (*ARIMAModel) Predict ¶ added in v0.1.2
func (m *ARIMAModel) Predict(ctx context.Context, features FeatureFrame) (Forecast, error)
Predict generates a forecast for the configured horizon.
The prediction process:
- Uses trained AR and MA coefficients
- Generates predictions step-by-step using ARIMA equations
- Applies inverse differencing to restore trend
- Enforces non-negativity constraint
The features parameter is ignored - ARIMA uses stored model state.
Returns error if:
- Context is cancelled
- Model has not been trained (call Train first)
func (*ARIMAModel) Train ¶ added in v0.1.2
func (m *ARIMAModel) Train(ctx context.Context, history FeatureFrame) error
Train fits the ARIMA model to historical data.
The training process:
- Extracts metric values from feature rows
- Applies differencing (d times) to achieve stationarity
- Computes mean of stationary series
- Fits AR coefficients using Yule-Walker equations
- Fits MA coefficients using innovations algorithm
- Stores last p values and q errors for prediction
Minimum data requirements: max(p+d, q+d, 10) points needed for stable training.
Returns error if:
- Context is cancelled
- Insufficient training data
- Numerical instability during coefficient estimation
type BaselineModel ¶
type BaselineModel struct {
// contains filtered or unexported fields
}
BaselineModel implements a simple forecasting model using exponential moving averages and optional hour-of-day seasonality patterns.
Algorithm:
- Compute EMA5m and EMA30m over recent window
- Base forecast = 0.7*EMA5m + 0.3*EMA30m
- Optional seasonality: if sufficient hour-of-day data exists, compute Mean_h and blend: yhat = 0.8*Base + 0.2*Mean_h
- All values are non-negative
This model is stateless and requires no training.
func NewBaselineModel ¶
func NewBaselineModel(metric string, stepSec, horizon int) *BaselineModel
NewBaselineModel creates a new baseline forecasting model. The model uses EMA-based forecasting with optional seasonality.
func (*BaselineModel) Name ¶
func (m *BaselineModel) Name() string
Name returns the model identifier.
func (*BaselineModel) Predict ¶
func (m *BaselineModel) Predict(ctx context.Context, features FeatureFrame) (Forecast, error)
Predict generates a forecast using EMA-based prediction with optional seasonality.
The features FeatureFrame should contain recent historical values with:
- "value": the metric value (required)
- "hour": hour of day 0-23 (optional, for seasonality)
- "timestamp": Unix timestamp (optional, for ordering)
Returns a Forecast with Values of length horizon/stepSec, all non-negative.
func (*BaselineModel) Train ¶
func (m *BaselineModel) Train(ctx context.Context, history FeatureFrame) error
Train extracts seasonality patterns from historical data. For the baseline model, this computes hour-of-day means if sufficient data exists. Returns nil (training is optional for baseline).
type FeatureFrame ¶
FeatureFrame represents a collection of feature rows for model training and prediction. Each row is a map of feature names to their float64 values, typically including timestamps and derived features like hour-of-day or day-of-week.
Example:
FeatureFrame{
Rows: []map[string]float64{
{"timestamp": 1609459200, "value": 150.0, "hour": 0, "day": 5},
{"timestamp": 1609459260, "value": 155.0, "hour": 0, "day": 5},
},
}
type Forecast ¶
type Forecast struct {
// Metric is the name of the metric being forecast (e.g., "http_rps")
Metric string
// Values contains the forecast predictions at regular intervals
Values []float64
// StepSec is the interval in seconds between consecutive values
StepSec int
// Horizon is the total forecast window in seconds
Horizon int
}
Forecast represents a time-series forecast generated by a model. Values contains the predicted metric values at regular intervals (StepSec) over the forecast horizon (Horizon seconds).
The length of Values should be: len(Values) = Horizon / StepSec
type Model ¶
type Model interface {
// Train trains the model on historical data.
// For stateless models like baseline, this may be a no-op.
// Returns an error if training fails or if the history is insufficient.
//
// The context can be used to cancel long-running training operations.
Train(ctx context.Context, history FeatureFrame) error
// Predict generates a forecast based on the provided features.
// The features typically include recent historical values and time-based
// features (hour, day, etc.) extracted from the data.
//
// Returns an error if prediction fails or if features are invalid.
// The returned Forecast must have non-negative values.
Predict(ctx context.Context, features FeatureFrame) (Forecast, error)
// Name returns the model's identifier (e.g., "baseline", "arima").
// Used for logging, metrics, and model selection.
Name() string
}
Model defines the interface for forecasting models. Implementations must be safe for concurrent use if documented as such.
The baseline implementation (baseline.go) provides a simple moving average with optional seasonality that requires no training.
Source Files