% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gesearch.R
\name{gesearch}
\alias{gesearch}
\alias{gesearch.default}
\alias{gesearch.formula}
\alias{predict.gesearch}
\alias{plot.gesearch}
\title{Evolutionary sample search for context-specific calibrations}
\usage{
\method{gesearch}{default}(Xr, Yr, Xu, Yu = NULL, Yu_lims = NULL,
         k, b, retain = 0.95, target_size = k,
         fit_method = fit_pls(ncomp = 10),
         optimization = "reconstruction",
         group = NULL, control = gesearch_control(),
         intermediate_models = FALSE,
         verbose = TRUE, seed = NULL, pchunks = 1L, ...)

\method{gesearch}{formula}(formula, train, test, k, b, target_size, fit_method,
         ..., na_action = na.pass)

\method{predict}{gesearch}(object, newdata, type = "response",
         what = c("final", "all_generations"), ...)

\method{plot}{gesearch}(x, which = c("weakness", "removed"), ...)
}
\arguments{
\item{Xr}{A numeric matrix of predictor variables for the reference data
(observations in rows, variables in columns).}

\item{Yr}{A numeric vector or single-column matrix of response values
corresponding to \code{Xr}. Only one response variable is supported.}

\item{Xu}{A numeric matrix of predictor variables for target observations
(same structure as \code{Xr}).}

\item{Yu}{An optional numeric vector or single-column matrix of response
values for \code{Xu}. Required when \code{optimization} includes
\code{"response"}. Default is \code{NULL}.}

\item{Yu_lims}{A numeric vector of length 2 specifying expected response
limits for the target population. Used with \code{optimization = "range"}.}

\item{k}{An integer specifying the number of samples in each resampling
subset (gene size).}

\item{b}{An integer specifying the target average number of times each
training sample is evaluated per iteration. Higher values (e.g., >40)
produce more stable results but increase computation time.}

\item{retain}{A numeric value in (0, 1] specifying the proportion of samples
retained per iteration. Default is 0.95. Values >0.9 are recommended for
stability. See \code{\link{gesearch_control}} for retention strategy.}

\item{target_size}{An integer specifying the target number of selected
samples (gene pool size). Must be >= \code{k}. Default is \code{k}.}

\item{fit_method}{A fit method object created with \code{\link{fit_pls}}.
Specifies the regression model and scaling used during the search.
Currently only \code{fit_pls()} is supported.}

\item{optimization}{A character vector specifying optimization criteria:
\itemize{
\item \code{"reconstruction"}: (default) Retains samples based on
spectral reconstruction error of \code{Xu} in PLS space.
\item \code{"response"}: Retains samples based on RMSE of predicting
\code{Yu}. Requires \code{Yu}.
\item \code{"similarity"}: Retains samples based on Mahalanobis distance
between \code{Xu} and training samples in PLS score space.
\item \code{"range"}: Removes samples producing predictions outside
\code{Yu_lims}.
}
Multiple criteria can be combined, e.g.,
\code{c("reconstruction", "similarity")}.}

\item{group}{An optional factor assigning group labels to training
observations. Used for leave-group-out cross-validation to avoid
pseudo-replication.}

\item{control}{A list created with \code{\link{gesearch_control}} containing
additional algorithm parameters.}

\item{intermediate_models}{A logical indicating whether to store models for
each intermediate generation. Default is \code{FALSE}.}

\item{verbose}{A logical indicating whether to print progress information.
Default is \code{TRUE}.}

\item{seed}{An integer for random number generation to ensure
reproducibility. Default is \code{NULL}.}

\item{pchunks}{An integer specifying the chunk size used for memory-efficient
parallel processing. Larger values divide the workload into smaller pieces,
which can help reduce memory pressure. Default is 1L.}

\item{formula}{A \code{\link[stats]{formula}} defining the model.}

\item{train}{A data.frame containing training data with model variables.}

\item{test}{A data.frame containing test data with model variables.}

\item{na_action}{A function for handling missing values in training data.
Default is \code{\link[stats]{na.pass}}.}

\item{object}{A fitted \code{gesearch} object (for \code{predict}).}

\item{newdata}{A matrix or data.frame of new observations. For formula-fitted
models, a data.frame containing all predictor variables is accepted. For
non-formula models, a matrix is required.}

\item{type}{A character string specifying the prediction type. Currently only
\code{"response"} is supported.}

\item{what}{A character string specifying which models to use for prediction:
\code{"final"} (default) for predictions from final models only, or
\code{"all_generations"} for predictions from all intermediate generations
plus the final models.}

\item{x}{A \code{gesearch} object (for \code{plot}).}

\item{which}{Character string specifying what to plot:
\code{"weakness"} (maximum weakness scores per generation) or
\code{"removed"} (cumulative samples removed).}

\item{...}{Additional arguments passed to methods.}
}
\value{
\strong{For \code{gesearch}:} A list of class \code{"gesearch"} containing:
\itemize{
\item \code{x_local}: Matrix of predictors for selected samples.
\item \code{y_local}: Vector of responses for selected samples.
\item \code{indices}: Indices of selected samples from original training set.
\item \code{complete_iter}: Number of completed iterations.
\item \code{iter_weakness}: List with iteration-level weakness statistics.
\item \code{samples}: List of sample indices retained at each iteration.
\item \code{n_removed}: data.frame of samples removed per iteration.
\item \code{control}: Copy of control parameters.
\item \code{fit_method}: Fit constructor from \code{fit_method}.
\item \code{validation_results}: Cross-validation in the training only set
validation on the test set using models built only with the samples found.
\item \code{final_models}: Final PLS model containing coefficients, loadings,
scores, VIP, and selectivity ratios.
\item \code{intermediate_models}: List of models per generation (if
\code{intermediate_models = TRUE}).
\item \code{seed}: RNG seed used.
}

\strong{For \code{predict.gesearch}:}
\itemize{
\item If \code{what = "final"}: a prediction matrix with
\code{nrow(newdata)} rows and one column per PLS component.
\item If \code{what = "all_generations"}: a named list of generations,
where each generation contains a prediction matrix as above.
}
}
\description{
Implements an evolutionary search algorithm that selects a subset from large
reference datasets (e.g., spectral libraries) to build context-specific
calibrations. The algorithm iteratively removes weak or non-informative
samples based on prediction error, spectral reconstruction error, or
dissimilarity criteria. This implementation is based on the methods proposed
in Ramirez-Lopez et al. (2026a).
}
\details{
The \code{gesearch} algorithm requires a large reference dataset (\code{Xr})
where the sample search is conducted, target observations (\code{Xu}), and
three tuning parameters: \code{k}, \code{b}, and \code{retain}.

The target observations (\code{Xu}) should represent the population of
interest. These may be selected via algorithms like Kennard-Stone when
response values are unavailable.

The algorithm iteratively removes weak samples from \code{Xr} based on:
\itemize{
\item Increased RMSE when predicting \code{Yu}
\item Increased PLS reconstruction error on \code{Xu}
\item Increased dissimilarity to \code{Xu} in PLS space
}

A resampling scheme identifies samples that consistently appear in
high-error subsets. These are labeled weak and removed. The process
continues until approximately \code{target_size} samples remain.

The \code{gesearch()} function also returns a final model fitted on the selected
samples, which can be used for prediction. This model is internally validated
by cross-validation using only the selected samples from the training/reference
set. If \code{Yu} is available, a model fitted only on the selected reference samples
is first used to predict the target samples. The final model is then refitted
using both the selected reference samples and the target samples used to guide
the search, provided that response values are available for those target samples.
\subsection{Parameter guidance}{

\itemize{
\item \code{k}: Number of samples per resampling subset. See Lobsey et
al. (2017) for guidance.
\item \code{b}: Resampling intensity. Higher values increase stability
but computational cost.
\item \code{retain}: Proportion retained per iteration. Values >0.9
recommended.
}
}

\subsection{Prediction}{

The \code{predict} method generates predictions from a fitted
\code{gesearch} object. If the model was fitted with a formula,
\code{newdata} is validated and transformed to the appropriate model matrix.

When \code{what = "all_generations"}, the return value is a named list with
one element per generation, where each element contains a prediction
matrix. This option requires \code{intermediate_models = TRUE} during
fitting.
}
}
\examples{
\dontrun{
library(prospectr)
data(NIRsoil)

# Preprocess
sg_det <- savitzkyGolay(
  detrend(NIRsoil$spc, wav = as.numeric(colnames(NIRsoil$spc))),
  m = 1, p = 1, w = 7
)
NIRsoil$spc_pr <- sg_det

# Split data
train_x <- NIRsoil$spc_pr[NIRsoil$train == 1 & !is.na(NIRsoil$Ciso), ]
train_y <- NIRsoil$Ciso[NIRsoil$train == 1 & !is.na(NIRsoil$Ciso)]
test_x <- NIRsoil$spc_pr[NIRsoil$train == 0 & !is.na(NIRsoil$Ciso), ]
test_y <- NIRsoil$Ciso[NIRsoil$train == 0 & !is.na(NIRsoil$Ciso)]

# Basic search with reconstruction and similarity optimizations
gs <- gesearch(
  Xr = train_x, Yr = train_y,
  Xu = test_x, Yu = test_y,
  k = 50, b = 100, retain = 0.97,
  target_size = 200,
  fit_method = fit_pls(ncomp = 15, method = "mpls"),
  optimization = c("reconstruction", "similarity"),
  control = gesearch_control(retain_by = "probability"),
  seed = 42
)

# Predict
preds <- predict(gs, test_x)

# Plot progress
plot(gs)
plot(gs, which = "removed")

# With reconstruction and response optimization (requires Yu)
gs_response <- gesearch(
  Xr = train_x, Yr = train_y,
  Xu = test_x, Yu = test_y,
  k = 50, b = 100, retain = 0.97,
  target_size = 200,
  fit_method = fit_pls(ncomp = 15),
  optimization = c("reconstruction", "response"),
  seed = 42
)

# Parallel processing
library(doParallel)
n_cores <- min(2, parallel::detectCores() - 1)
cl <- makeCluster(n_cores)
registerDoParallel(cl)

gs_parallel <- gesearch(
  Xr = train_x, Yr = train_y,
  Xu = test_x,
  k = 50, b = 100, retain = 0.97,
  target_size = 200,
  fit_method = fit_pls(ncomp = 15),
  pchunks = 3,
  seed = 42
)

stopCluster(cl)
registerDoSEQ()
}

}
\references{
Lobsey, C.R., Viscarra Rossel, R.A., Roudier, P., Hedley, C.B. 2017.
rs-local data-mines information from spectral libraries to improve local
calibrations. European Journal of Soil Science 68:840-852.

Kennard, R.W., Stone, L.A. 1969. Computer aided design of experiments.
Technometrics 11:137-148.

Rajalahti, T., Arneberg, R., Berven, F.S., Myhr, K.M., Ulvik, R.J.,
Kvalheim, O.M. 2009. Biomarker discovery in mass spectral profiles by means
of selectivity ratio plot. Chemometrics and Intelligent Laboratory Systems
95:35-48.

Ramirez-Lopez, L., Viscarra Rossel, R., Behrens, T., Orellano, C.,
Perez-Fernandez, E., Kooijman, L., Wadoux, A. M. J.-C., Breure, T.,
Summerauer, L., Safanelli, J. L., & Plans, M. (2026a). When spectral
libraries are too complex to search: Evolutionary subset selection for
domain-adaptive calibration. \emph{Analytica Chimica Acta}, under review.
}
\seealso{
\code{\link{fit_pls}}, \code{\link{gesearch_control}}, \code{\link{mbl}}
}
\author{
\href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez},
Claudio Orellano,
\href{https://orcid.org/0000-0001-5416-4520}{Craig Lobsey},
\href{https://orcid.org/0000-0003-1540-4748}{Raphael Viscarra Rossel}
}
