\HeaderA{matchpt}{Nearest neighbor search.}{matchpt}
\keyword{manip}{matchpt}
\keyword{array}{matchpt}
\begin{Description}\relax
Find the nearest neighbors of a set of query points in the same
or another set of points in an
n-dimensional real vector space, using the Euclidean distance.
\end{Description}
\begin{Usage}
\begin{verbatim}
    matchpt(x, y)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A matrix (or vector) of coordinates.
Each row represents a point in an \code{ncol(x)}-dimensional real
vector space.
\item[\code{y}] Optional, matrix (or vector) with the same number of columns
as \code{x}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{y} is provided, the function searches
for each point in \code{x} its nearest neighbor in \code{y}.
If \code{y} is missing, it searches
for each point in \code{x} its nearest neighbor in \code{x},
excluding that point itself.
In the case of ties, only the neighbor with the smaller index is given.

The implementation is simple and of complexity \code{nrow(x)} times
\code{nrow(y)}. For larger problems, please consider one of the many
more efficient nearest neighbor search algorithms.
\end{Details}
\begin{Value}
A \code{data.frame} with two columns and \code{nrow(x)} rows.
The first column is the index of the nearest neighbor,
the second column the distance to the nearest neighbor.
If \code{y} was given, the index is a row number in \code{y},
otherwise, in \code{x}. The row names of the result are those of \code{x}.
\end{Value}
\begin{Author}\relax
Oleg Sklyar \email{osklyar@ebi.ac.uk}
\end{Author}
\begin{Examples}
\begin{ExampleCode}
    a <- matrix(c(2,2,3,5,1,8,-1,4,5,6), ncol=2L, nrow=5L)
    rownames(a) = LETTERS[seq_len(nrow(a))]
    matchpt(a)
    b <- c(1,2,4,5,6)
    d <- c(5.3, 3.2, 8.9, 1.3, 5.6, -6, 4.45, 3.32)
    matchpt(b, d)
    matchpt(d, b)
\end{ExampleCode}
\end{Examples}

