\name{ARCHmXAdditive}
\alias{ARCHmXAdditive}
\title{Creating and fitting an Additive ARCH-m(X) model for variable selection}
\usage{
ARCHmXAdditive(
  eps, 
  X, 
  p, 
  delta=2,
  covariates="all",
  method="smooth_means_Positive_Constraint_Exp",
  train_end = NULL, 
  n_burn = 10, 
  max_outer_iter = 30, 
  tol = 1e-4,
  hypothesisTest=TRUE,
  k.choice = "plugin"
)
}
\arguments{
\item{eps}{Time series.}
\item{X}{Matrix with exogenous covariates where the number of rows is equal to the length of eps and columns represent the covariates}
\item{p}{Order of the Additive ARCH-m(X) model. Value of p cannot be 0.}
\item{delta}{Value of the power of the main time series for a POWER-GARCH. Default is 2.}
\item{covariates}{Instead of slicing X when building partial models, you can specify a vector of column indices. Defaults to "all".}
\item{method}{Backfitting strategy used for the additive nonparametric component. One of \code{"smooth_means_Positive_Constraint_Exp"}, \code{"smooth_means_lowes"}, or \code{"smooth_variance"}.
  \tabular{ll}{
    \code{"smooth_means_Positive_Constraint_Exp"} \tab Smooth log-partial-residuals and exponentiate (log/exp positivity constraint).\cr
    \code{"smooth_means_lowes"} \tab Smooth partial residuals and shift upward by subtracting the minimum (smooth + shift).\cr
    \code{"smooth_variance"} \tab Smooth a local weighted variance curve of partial residuals, take a square root, then shift upward (variance-smooth + shift).\cr
  }
}
\item{train_end}{Optional integer. If provided, fit on \code{1:train_end} and compute test metrics on the remainder. If not provided, fit on the full sample.}
\item{n_burn}{Integer burn-in. Iterations and fitted quantities are evaluated only after burn-in has passed. Default is 10.}
\item{max_outer_iter}{Maximum number of outer backfitting iterations. Default is 30.}
\item{tol}{Convergence tolerance for the outer iterations. Default is \code{1e-4}.}
\item{hypothesisTest}{Whether to perform covariate hypothesis testing, default is TRUE.}
\item{k.choice}{Choice of window size k for the ANOVA hypotghesis test. Options are "plugin" or "CV". Default is "plugin".}
}

\value{
An object of class ARCHmXAdditive
}

\description{
Fits an Additive ARCH-m(X) model with given data and estimates the alphas and nonparametric functions m(X). 
}

\details{
This function fits an additive semiparametric volatility model of the form
\deqn{\epsilon_t = \sigma_t w_t,}
\deqn{\sigma_t^2 = \sum_{i=1}^{p}\alpha_i |\epsilon_{t-i}|^2 + \sum_{\ell=1}^{d} m_{\ell}(X_{t-1,\ell}).}

Estimation proceeds by iterating between:
\enumerate{
\item Updating the ARCH parameters \eqn{\alpha_1,\ldots,\alpha_p} (subject to nonnegativity constraints), and
\item Updating the additive components \eqn{m_{\ell}} using backfitting with a positivity-enforcing strategy controlled by \code{method}.
}

The outer loop stops when the change in the objective (or updates) is below \code{tol} or when \code{max_outer_iter} is reached.

No variable selection is done in this function, but an ANOVA-type hypothesis test may be performed for the significance of each covariate. This is enabled by default. 
}

\examples{
\donttest{
# We simulate a time series as in the simulate.ARCHmXAdditive example.
set.seed(1)
n <- 2000
alpha <- c(0.2, 0.1)
valinit <- 200
X <- matrix(rnorm((n+valinit) * 3), ncol = 3)

m <- list(
  function(x) 4 * abs(sin(x)),
  function(x) 2 * x^2,
  function(x) 1.5
)

data <- sim.ARCHmXAdditive(n = n, alpha = alpha, X = X, m = m)
p <- length(alpha)

# Then we fit the model
model <- ARCHmXAdditive(X = data$X, p = p, eps = data$eps, 
                        method = "smooth_means_lowes", max_outer_iter = 15)
model$alphas
model$converged

# We inspect the model summary
summary(model)
}
}
