Help for package GACE

Title:

Generalized Adaptive Capped Estimator for Time Series Forecasting

Version:

1.0.0

Maintainer:

Vinodhkumar Gunasekaran <vinoalles@gmail.com>

Description:

Provides deterministic forecasting for weekly, monthly, quarterly, and yearly time series using the Generalized Adaptive Capped Estimator. The method includes preprocessing for missing and extreme values, extraction of multiple growth components (including long-term, short-term, rolling, and drift-based signals), volatility-aware asymmetric capping, optional seasonal adjustment via damped and normalized seasonal factors, and a recursive forecast formulation with moderated growth. The package includes a user-facing forecasting interface and a plotting helper for visualization. Related forecasting background is discussed in Hyndman and Athanasopoulos (2021) https://otexts.com/fpp3/ and Hyndman and Khandakar (2008) <doi:10.18637/jss.v027.i03>. The method extends classical extrapolative forecasting approaches and is suited for operational and business planning contexts where stability and interpretability are important.

License:

MIT + file LICENSE

Encoding:

UTF-8

RoxygenNote:

7.3.3

Imports:

ggplot2, stats, utils

Depends:

R (≥ 4.1.0)

Suggests:

testthat (≥ 3.0.0), knitr, rmarkdown, covr, forecast

VignetteBuilder:

knitr

Config/testthat/edition:

URL:

https://github.com/vinoalles/GACE

BugReports:

https://github.com/vinoalles/GACE/issues

NeedsCompilation:

Packaged:

2025-12-07 20:32:14 UTC; vinodhkumargunasekaran

Author:

Vinodhkumar Gunasekaran [aut, cre]

Repository:

CRAN

Date/Publication:

2025-12-11 19:20:18 UTC

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
)

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.

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.

Examples


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

Plot GACE Forecast

Description

Produces a plot of historical and forecast values returned by gace_forecast(). Includes stability handling for missing values, non-numeric periods, and clean ggplot2 output.

Usage

plot_gace(fc)

Arguments

fc

A data frame returned by gace_forecast(), containing:

period – numeric or convertible index,
value – observed or forecast values,
type – "historical" or "forecast".

Value

A ggplot2 object.

Examples


  set.seed(1)
  y <- ts(rnorm(48, mean = 100, sd = 10), frequency = 12)
  fc <- gace_forecast(y, periods = 6, freq = "month")
  plot_gace(fc)