% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/search_neighbors.R
\name{search_neighbors}
\alias{search_neighbors}
\title{Search neighbors in a reference set}
\usage{
search_neighbors(Xr, Xu = NULL,
                 diss_method = diss_pca(), Yr = NULL,
                 neighbors, spike = NULL,
                 return_dissimilarity = FALSE, 
                 k, k_diss, k_range, pc_selection, 
                 center, scale, documentation, ...
                 )
}
\arguments{
\item{Xr}{A numeric matrix of reference observations (rows) and variables
(columns) where the neighbor search is conducted.}

\item{Xu}{Optional matrix of observations for which neighbors are to be
searched in \code{Xr}.}

\item{diss_method}{A dissimilarity method object created by one of:
\itemize{
\item \code{\link{diss_pca}()}: Mahalanobis distance in PCA space
\item \code{\link{diss_pls}()}: Mahalanobis distance in PLS space
\item \code{\link{diss_correlation}()}: Correlation-based dissimilarity
\item \code{\link{diss_euclidean}()}: Euclidean distance
\item \code{\link{diss_mahalanobis}()}: Mahalanobis distance
\item \code{\link{diss_cosine}()}: Cosine dissimilarity
}
Default is \code{diss_pca()}.}

\item{Yr}{Optional response matrix. Required for PLS methods and when using
\code{ncomp_by_opc()}.}

\item{neighbors}{A neighbor selection object created by:
\itemize{
\item \code{\link{neighbors_k}()}: Select k nearest neighbors
\item \code{\link{neighbors_diss}()}: Select neighbors by dissimilarity threshold
}}

\item{spike}{Optional integer vector indicating observations in \code{Xr}
to force into (positive indices) or exclude from (negative indices)
neighborhoods.}

\item{return_dissimilarity}{Logical indicating whether to return the
dissimilarity matrix. Default is \code{FALSE}.}

\item{k}{Deprecated.}

\item{k_diss}{Deprecated.}

\item{k_range}{Deprecated.}

\item{pc_selection}{Deprecated.}

\item{center}{Deprecated.}

\item{scale}{Deprecated.}

\item{documentation}{Deprecated.}

\item{...}{Additional arguments (currently unused).}
}
\value{
A list containing:
\describe{
\item{neighbors}{Matrix of \code{Xr} indices for each query observation's
neighbors, sorted by dissimilarity (columns = query observations).}
\item{neighbors_diss}{Matrix of dissimilarity scores corresponding to
\code{neighbors}.}
\item{unique_neighbors}{Vector of unique \code{Xr} indices that appear
in any neighborhood.}
\item{k_diss_info}{If \code{neighbors_diss()} was used, a \code{data.frame}
with columns for observation index, number of neighbors found, and final
number after applying bounds.}
\item{dissimilarity}{If \code{return_dissimilarity = TRUE}, the full
dissimilarity object.}
\item{projection}{If the dissimilarity method includes
\code{return_projection = TRUE}, the projection object.}
\item{gh}{If the dissimilarity method includes \code{gh = TRUE}, the
GH distances.}
}
}
\description{
\loadmathjax
Searches for the nearest neighbors of observations in a reference set or
between two sets of observations.
}
\details{
This function is useful for reducing large reference sets by identifying
only relevant neighbors before running \code{\link{mbl}}.

If \code{Xu} is not provided, the function searches for neighbors within
\code{Xr} itself (excluding self-matches). If \code{Xu} is provided,
neighbors of each observation in \code{Xu} are searched in \code{Xr}.

The \code{spike} argument allows forcing specific observations into or out
of all neighborhoods. Positive indices are always included; negative indices
are always excluded.
}
\examples{
\donttest{
library(prospectr)
data(NIRsoil)

Xu <- NIRsoil$spc[!as.logical(NIRsoil$train), ]
Yu <- NIRsoil$CEC[!as.logical(NIRsoil$train)]
Yr <- NIRsoil$CEC[as.logical(NIRsoil$train)]
Xr <- NIRsoil$spc[as.logical(NIRsoil$train), ]

Xu <- Xu[!is.na(Yu), ]
Yu <- Yu[!is.na(Yu)]
Xr <- Xr[!is.na(Yr), ]
Yr <- Yr[!is.na(Yr)]

# Correlation-based neighbor search with k neighbors
ex1 <- search_neighbors(
  Xr = Xr, Xu = Xu,
  diss_method = diss_correlation(),
  neighbors = neighbors_k(40)
)

# PCA-based with OPC selection
ex2 <- search_neighbors(
  Xr = Xr, Xu = Xu,
  diss_method = diss_pca(
    ncomp = ncomp_by_opc(40),
    scale = TRUE,
    return_projection = TRUE
  ),
  Yr = Yr,
  neighbors = neighbors_k(50)
)

# Observations not in any neighborhood
setdiff(seq_len(nrow(Xr)), ex2$unique_neighbors)

# Dissimilarity threshold-based selection
ex3 <- search_neighbors(
  Xr = Xr, Xu = Xu,
  diss_method = diss_pls(
    ncomp = ncomp_by_opc(40),
    scale = TRUE
  ),
  Yr = Yr,
  neighbors = neighbors_diss(threshold = 0.5, k_min = 10, k_max = 100)
)
}

}
\references{
Ramirez-Lopez, L., Behrens, T., Schmidt, K., Stevens, A., Dematte, J.A.M.,
Scholten, T. 2013a. The spectrum-based learner: A new local approach for
modeling soil vis-NIR spectra of complex data sets. Geoderma 195-196,
268-279.

Ramirez-Lopez, L., Behrens, T., Schmidt, K., Viscarra Rossel, R., Dematte,
J.A.M., Scholten, T. 2013b. Distance and similarity-search metrics for use
with soil vis-NIR spectra. Geoderma 199, 43-53.
}
\seealso{
\code{\link{dissimilarity}}, \code{\link{mbl}},
\code{\link{neighbors_k}}, \code{\link{neighbors_diss}}
}
\author{
\href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez}
}
