% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/GEMSS.R
\name{gemss_select}
\alias{gemss_select}
\title{Subdata Selection via GEMSS}
\usage{
gemss_select(
  X,
  Y,
  ns,
  covtype,
  parameters = NULL,
  X_val = NULL,
  Y_val = NULL,
  c1 = NULL,
  n_srs = NULL,
  n_top = NULL,
  verbose = TRUE
)
}
\arguments{
\item{X}{an \code{n x p} matrix of input design locations.}

\item{Y}{an \code{n x 1} numeric vector of observed responses.}

\item{ns}{target size of the final subdata.}

\item{covtype}{covariance kernel type, either "Gaussian", "Matern5_2", or "Matern3_2".}

\item{parameters}{a list of hyperparameters: \code{beta0} (mean),
\code{theta} (length-scales), and \code{g} (nugget). If not provided,
these are estimated via \code{hetGP::\link[hetGP]{mleHomGP}} on a pilot
sample generated by \code{twinning::\link[twinning]{twin}}.}

\item{X_val, Y_val}{optional validation data for calculating the predictive R-squared.
If omitted, a random sample of size \code{min(0.1*n, 5000)} is used.}

\item{c1}{value between 0 and 1 of the first term in GEMSS criterion (\eqn{c_2 = 1 - c_1}).
The default (\code{NULL}) uses the adaptive weighting proposed in the paper.}

\item{n_srs, n_top}{optional values to determine the candidate set for each iteration:
\itemize{
\item \code{n_srs}: number of random data points (default is \code{ns/2}).
\item \code{n_top}: number of top-ranked points from the previous iteration (default is \code{ns/2}).
}}

\item{verbose}{logical; if \code{TRUE}, progress is printed at each iteration.}
}
\value{
a list containing:
\itemize{
\item \code{index}: the indices of the selected subdata.
\item \code{r_sq}: a data.frame containing the subdata size and the corresponding predictive R-square.
\item \code{parameters}: a list of hyperparameters containing \code{beta0}, \code{theta}, \code{g}, and \code{sigma2} (the plug-in estimator of the variance).
}
}
\description{
Implements the Generalized Error-Minimizing Subsampling (GEMSS) algorithm to select subdata for
Gaussian Process models.
}
\details{
The GEMSS criterion is defined as:
\deqn{\mathcal{G} = c_1 \delta_1^2 + c_2 \delta_2}
where \eqn{\delta_1^2} is the squared prediction error and \eqn{\delta_2} is the
posterior variance. The weights \eqn{c_1} and \eqn{c_2 = 1 - c_1} control the
balance between prediction accuracy and space-filling properties.

The default value for \eqn{c_1} is \eqn{3\delta_2^2 / (2\delta_1^4 + 3\delta_2^2)},
which is derived by minimizing the variance of the GEMSS criterion. Setting
\eqn{c_1 = 0} results in a space-filling subdata

The algorithm initializes with a small random sample of size 2 and
sequentially adds the point from the candidate set that maximizes \eqn{\mathcal{G}}
until the subdata reaches size ns.

The candidate set in each iteration is composed of two parts: a random
sample of size n_srs, and the n_top points that yielded the highest
\eqn{\mathcal{G}} values in the previous iteration.

All GP hyperparameters except \eqn{\sigma^2} are estimated from an initial
pilot sample of size \eqn{ns} and remain fixed throughout the selection process.
}
\examples{
# --- Example 1: 1D Regression ---
fx <- function(x) cos((x - 0.8) * 2 * pi)^7 * sin(x) + 5 * sin(x) * (sin(x^2))^10
X <- matrix(runif(200), 200, 1)
Y <- apply(X, 1, fx) + rnorm(nrow(X), 0, 0.05)

# Select 20 points using GEMSS
res <- gemss_select(X, Y, ns = 20, covtype = "Matern5_2")

# Predict on a grid
x.grid <- as.matrix(seq(0, 1, 0.01))
y.pred <- gp_predict(x.grid, X[res$index, ], Y[res$index], "Matern5_2", res$parameters)

# Visualize 1D Results
plot(X, Y, col = "grey", main = "Selected Subdata and GP Prediction")
points(X[res$index, ], Y[res$index], col = "red", pch = 19)
lines(x.grid, y.pred$mean, col = "red", lwd = 2)

# --- Example 2: 2D Surface (Michalewicz function) ---
\donttest{
michalewicz <- function(xx) {
  x1 <- xx[1] * pi; x2 <- xx[2] * pi; m <- 10
  - (sin(x1) * (sin(x1^2 / pi))^(2 * m) + sin(x2) * (sin(2 * x2^2 / pi))^(2 * m))
}

X2D <- matrix(runif(2000), 1000, 2)
Y2D <- apply(X2D, 1, michalewicz) + rnorm(nrow(X2D), 0, 0.005)

res2D <- gemss_select(X2D, Y2D, ns = 80, covtype = "Matern5_2")

# Visualization using ContourFunctions if available
if (requireNamespace("ContourFunctions", quietly = TRUE)) {
  ngrid <- 50 # Reduced grid size for faster example execution
  gx <- seq(0, 1, len = ngrid)
  grid <- as.matrix(expand.grid(x1 = gx, x2 = gx))

  # plot the contour of Michalewicz function
  y_grid <- apply(grid, 1, michalewicz)
  ContourFunctions::cf_grid(gx, gx, matrix(y_grid, ngrid, ngrid),
                          bar = TRUE, main = "Michalewicz Function")

  prep <- gp_predict(grid, X2D[res2D$index, ], Y2D[res2D$index],
  "Matern5_2", res2D$parameters)
  ContourFunctions::cf_grid(gx, gx, matrix(prep$mean, ngrid, ngrid),
                            bar = TRUE, main = "Prediction Using Selected Subdata",
                            afterplotfunc = function() {
                              points(X2D[res2D$index, ], col = 'blue', pch = 1, cex = 1.5, lwd = 2)
                            })
}
}

}
\references{
Chang, M. C., Hua, S. Z., & Wu, C. F. J. (2026). GEMSS-Driven Subsampling
for Information Extraction and Redundancy Elimination. \emph{Technometrics},
1–20. \doi{10.1080/00401706.2026.2670596}
}
