GACE (version 1.0.0)

gace_forecast: GACE Forecasting Engine (Generalized Adaptive Capped Estimator)

Description

Deterministic forecasting method combining hybrid growth signals, volatility-aware asymmetric caps, and optional seasonal scaling. Supports weekly, monthly, quarterly, and yearly time series.

Usage

gace_forecast(
  df,
  periods = 12,
  freq = c("week", "month", "quarter", "year"),
  seasonal = TRUE,
  cap_low = -0.3,
  cap_high = 0.3,
  verbose = FALSE
)

Value

A data frame with columns:

• period – integer index of historical and forecast periods,

• value – observed or forecast values,

• type – "historical" or "forecast".

The returned object has S3 class "gace_forecast" and includes engine details in the "gace_details" attribute.

Arguments

df

Numeric vector or time series of historical values.

periods

Integer; number of future periods to forecast.

freq

One of "week", "month", "quarter", or "year". Used when df is not a ts object, and also informs the growth/seasonal logic.

seasonal

Logical; whether to apply seasonal scaling.

cap_low

Numeric; baseline lower growth cap.

cap_high

Numeric; baseline upper growth cap.

verbose

Logical; if TRUE, prints diagnostic messages.

Details

This is the main user-facing function. It wraps the internal engine and returns a data frame suitable for plotting and downstream analysis.

Examples

# \donttest{
  set.seed(1)
  y <- ts(rnorm(60, mean = 100, sd = 10), frequency = 12)
  fc <- gace_forecast(y, periods = 12, freq = "month")
  head(fc)
# }