---
title: "gace-introduction"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{gace-introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


Introduction to GACE: Generalized Adaptive Capped Estimator

Overview
The Generalized Adaptive Capped Estimator (GACE) is a deterministic
forecasting framework designed for stable and interpretable projections
across weekly, monthly, quarterly, and yearly time series.

Unlike stochastic models, GACE uses a structured set of growth components
and volatility-aware caps that ensure consistent behavior, even for noisy
business or operational data.

This vignette introduces:
• preprocessing and growth extraction,
• growth capping,
• seasonal factor construction,
• recursive forecast generation,
• how to use gace_forecast() and plot_gace().

Basic Usage
library(GACE)

set.seed(1)
y <- ts(rnorm(60, mean = 100, sd = 10), frequency = 12)

fc <- gace_forecast(
  df      = y,
  periods = 12,
  freq    = "month"
)

head(fc)

Plotting the Forecast
plot_gace(fc)

How GACE Works

1. Preprocessing
GACE optionally cleans the input using:
• winsorization of extreme values,
• preservation of zeros,
• minimal smoothing.

2. Growth Components
GACE extracts four growth signals:
• Year-over-year
• Short-term (lag-1)
• Rolling-window movement
• Drift / long-run trend

These signals are trimmed, averaged, and dynamically stabilized.

3. Volatility-Aware Caps
GACE applies asymmetric caps such as −0.30 to +0.30. Caps adapt when series volatility increases.

4. Seasonal Factors
If seasonal = TRUE and frequency > 1, GACE computes smoothed, normalized seasonal loads.

5. Recursive Forecast
future = level * (1 + growth_t) * seasonal_factor_t

with decay parameters gamma and beta.

Multi-frequency Support

Weekly    → "week"
Monthly   → "month"
Quarterly → "quarter"
Yearly    → "year"

Conclusion
GACE provides a transparent, reproducible, and fast method for forecasting operational time series.