% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sparse_chaos.R
\name{sparse_khaos}
\alias{sparse_khaos}
\title{Bayesian Sparse Polynomial Chaos Expansion}
\usage{
sparse_khaos(
  X,
  y,
  degree = c(2, 2, 16),
  order = c(1, 1, 5),
  prior = c(1, 1, 1),
  lambda = 1,
  rho = 0,
  regularize = TRUE,
  max_basis = 1e+06,
  enrichment = "adaptive",
  adaptive_ladder = c(10000, 1e+05),
  verbose = TRUE
)
}
\arguments{
\item{X}{A data frame or matrix of predictors scaled to lie between 0 and 1.}

\item{y}{A numeric response vector of length \code{nrow(X)}.}

\item{degree}{Integer vector of length 3 giving the polynomial-degree schedule:
\code{c(d_init, d_increment, d_max)}.}

\item{order}{Integer vector of length 3 giving the interaction-order schedule:
\code{c(q_init, q_increment, q_max)}.}

\item{prior}{Numeric vector of prior hyperparameters
\code{c(n0, v0, s0)}, where \code{n0} controls shrinkage of the regression
coefficients, \code{v0} is the degrees-of-freedom parameter for the inverse-gamma
prior on \eqn{\sigma^2}, and \code{s0} is the scale parameter for that prior.}

\item{lambda}{Nonnegative penalty parameter used in the KIC calculation. Larger
values favor sparser models.}

\item{rho}{Basis functions are discarded after partial-correlation screening if
their squared partial correlation is smaller than \code{rho}.}

\item{regularize}{Logical; if \code{TRUE}, a weighted LASSO pre-screen is used
to reduce the candidate basis set before partial-correlation ranking.}

\item{max_basis}{Maximum number of candidate basis functions allowed in any
fitting round. This acts as a hard cap on computational cost.}

\item{enrichment}{Either an integer in \code{0:4} specifying a fixed enrichment
strategy, or the character string \code{"adaptive"}, which allows the strategy
to become more restrictive when the next candidate set would otherwise be too
large. See Details.}

\item{adaptive_ladder}{Numeric vector of candidate-size thresholds used only when
\code{enrichment = "adaptive"}. The ladder should have length between 1 and 4,
be sorted in increasing order, and satisfy \code{max(adaptive_ladder) <= max_basis}.
Internally, the ladder is used to determine when the algorithm should fall back
to a more restrictive enrichment strategy before attempting the next recursion
step.}

\item{verbose}{Logical; if \code{TRUE}, progress messages are printed.}
}
\value{
An object of class \code{"sparse_khaos"}.
The object is a list containing:
\describe{
\item{B}{Matrix of selected basis functions evaluated at the training inputs.}
\item{nbasis}{Number of selected basis functions (including intercept).}
\item{vars}{Matrix encoding the polynomial multi-indices for each basis function.}
\item{beta_hat}{MAP estimates of the regression coefficients.}
\item{s2}{Estimated noise variance.}
\item{X, y}{Training data (with \code{y} on the original scale).}
\item{mu_y, sigma_y}{Centering and scaling constants used for \code{y}.}
\item{BtB, BtBi}{Cross-product matrix and its inverse.}
\item{G}{Prior scaling factors for coefficients.}
\item{prior}{Prior hyperparameters.}
\item{KIC}{Kashyap information criterion values for candidate models.}
}
}
\description{
A Bayesian sparse polynomial chaos expansion (PCE) method based on the
forward-selection framework of Shao et al. (2017), with optional enrichment
strategies that adapt the candidate basis set across degree and interaction-order
expansions.
}
\details{
For fixed maximum degree and interaction order, the method constructs a candidate
library of polynomial basis functions, ranks them using marginal correlations and
sequential partial correlations, and evaluates nested models using the Kashyap
information criterion (KIC). The best-ranked model is retained at that stage.

If the selected model contains a basis function at the current maximum degree or
interaction order, the algorithm attempts another fitting round with increased
degree and/or interaction order. In later rounds, the candidate basis set can be
rebuilt using one of several enrichment strategies rather than constructing the
full basis library from scratch.

The \code{enrichment} argument controls how the candidate set is generated after
the first fitting round:
\describe{
\item{\code{0} (local enrichment)}{
Starts from the previously selected basis functions and applies local
modifications to each term. These include deletion, simplification,
complication, and promotion moves. This is typically the fastest strategy,
but it is also the most local.}
\item{\code{1} (active-variable rebuild)}{
Rebuilds the full candidate library using only variables that were active
in the previously selected model. This is computationally efficient, but
inactive variables cannot re-enter once dropped.}
\item{\code{2} (full active rebuild plus sparse inactive enrichment)}{
Rebuilds the candidate library on the currently active variables, then
enriches around the previously selected basis functions by allowing inactive
variables to re-enter through complication and promotion moves. This is a
compromise between speed and flexibility.}
\item{\code{3} (full active rebuild plus inactive enrichment)}{
Rebuilds the candidate library on the active variables, then enriches that
larger active-variable library by allowing inactive variables to re-enter
through complication and promotion moves. This is more expansive than
\code{enrichment = 2}, but can be substantially more expensive.}
\item{\code{4} (full rebuild)}{
Rebuilds the full candidate library over all variables at each enrichment
step. This is the most exhaustive strategy.}
\item{\code{"adaptive"}}{
Begins with a relatively expansive enrichment strategy and, before the next
recursion step, uses an upper bound on the candidate-set size to decide
whether a more restrictive strategy should be used instead. This recovers
the computational benefit of avoiding construction of candidate sets that
are known in advance to be too large.}
}

When \code{enrichment = "adaptive"}, the function uses \code{adaptive_ladder}
together with an upper bound on the next candidate-set size. If the current
enrichment choice appears too expensive, the algorithm steps down to a more
restrictive enrichment rule before proceeding. If even the most restrictive
admissible next step is predicted to exceed the allowed budget, the current
fitted model is returned.

Strategies \code{2}, \code{3}, and \code{"adaptive"} are designed to address a
limitation of active-variable-only rebuilds: variables that are inactive in one
round are allowed to re-enter the model in later rounds.
}
\examples{
X <- lhs::maximinLHS(100, 2)
f <- function(x) 10.391 * ((x[1] - 0.4) * (x[2] - 0.6) + 0.36)
y <- apply(X, 1, f) + stats::rnorm(100, 0, 0.1)

fit <- sparse_khaos(X, y)

}
\references{
Shao, Q., Younes, A., Fahs, M., and Mara, T. A. (2017).
Bayesian sparse polynomial chaos expansion for global sensitivity analysis.
\emph{Computer Methods in Applied Mechanics and Engineering}, \strong{318},
474--496.

Rumsey, K. N., Francom, D., Gibson, G., Tucker, J. D., and Huerta, G. (2026).
Bayesian adaptive polynomial chaos expansions.
\emph{Stat}, \strong{15}(1), e70151.
}
