% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/frNN.R
\name{frNN}
\alias{frNN}
\alias{frnn}
\alias{print.frnn}
\alias{sort.frNN}
\alias{adjacencylist.frNN}
\alias{print.frNN}
\title{Find the Fixed Radius Nearest Neighbors}
\usage{
frNN(
  x,
  eps,
  query = NULL,
  sort = TRUE,
  search = "kdtree",
  bucketSize = 10,
  splitRule = "suggest",
  approx = 0
)

\method{sort}{frNN}(x, decreasing = FALSE, ...)

\method{adjacencylist}{frNN}(x, ...)

\method{print}{frNN}(x, ...)
}
\arguments{
\item{x}{a data matrix, a dist object or a frNN object.}

\item{eps}{neighbors radius.}

\item{query}{a data matrix with the points to query. If query is not
specified, the NN for all the points in \code{x} is returned. If query is
specified then \code{x} needs to be a data matrix.}

\item{sort}{sort the neighbors by distance? This is expensive and can be
done later using \code{sort()}.}

\item{search}{nearest neighbor search strategy (one of \code{"kdtree"}, \code{"linear"} or
\code{"dist"}).}

\item{bucketSize}{max size of the kd-tree leafs.}

\item{splitRule}{rule to split the kd-tree. One of \code{"STD"}, \code{"MIDPT"}, \code{"FAIR"},
\code{"SL_MIDPT"}, \code{"SL_FAIR"} or \code{"SUGGEST"} (SL stands for sliding). \code{"SUGGEST"} uses
ANNs best guess.}

\item{approx}{use approximate nearest neighbors. All NN up to a distance of
a factor of \code{1 + approx} eps may be used. Some actual NN may be omitted
leading to spurious clusters and noise points.  However, the algorithm will
enjoy a significant speedup.}

\item{decreasing}{sort in decreasing order?}

\item{...}{further arguments}
}
\value{
\code{frNN()} returns an object of class \link{frNN} (subclass of
\link{NN}) containing a list with the following components:
\item{id }{a list of
integer vectors. Each vector contains the ids (row numbers) of the fixed radius nearest
neighbors. }
\item{dist }{a list with distances (same structure as
\code{id}). }
\item{eps }{ neighborhood radius \code{eps} that was used. }
\item{metric }{ used distance metric. }

\code{adjacencylist()} returns a list with one entry per data point in \code{x}. Each entry
contains the id of the nearest neighbors.
}
\description{
This function uses a kd-tree to find the fixed radius nearest neighbors
(including distances) fast.
}
\details{
If \code{x} is specified as a data matrix, then Euclidean distances and fast
nearest neighbor lookup using a kd-tree are used.

To create a frNN object from scratch, you need to supply at least the
elements \code{id} with a list of integer vectors with the nearest neighbor
ids for each point and \code{eps} (see below).

\strong{Self-matches:} Self-matches are not returned!
}
\examples{
data(iris)
x <- iris[, -5]

# Example 1: Find fixed radius nearest neighbors for each point
nn <- frNN(x, eps = .5)
nn

# Number of neighbors
hist(lengths(adjacencylist(nn)),
  xlab = "k", main="Number of Neighbors",
  sub = paste("Neighborhood size eps =", nn$eps))

# Explore neighbors of point i = 10
i <- 10
nn$id[[i]]
nn$dist[[i]]
plot(x, col = ifelse(seq_len(nrow(iris)) \%in\% nn$id[[i]], "red", "black"))

# get an adjacency list
head(adjacencylist(nn))

# plot the fixed radius neighbors (and then reduced to a radius of .3)
plot(nn, x)
plot(frNN(nn, eps = .3), x)

## Example 2: find fixed-radius NN for query points
q <- x[c(1,100),]
nn <- frNN(x, eps = .5, query = q)

plot(nn, x, col = "grey")
points(q, pch = 3, lwd = 2)
}
\references{
David M. Mount and Sunil Arya (2010). ANN: A Library for
Approximate Nearest Neighbor Searching,
\url{http://www.cs.umd.edu/~mount/ANN/}.
}
\seealso{
Other NN functions:
\code{\link{NN}},
\code{\link[=comps]{comps()}},
\code{\link[=kNN]{kNN()}},
\code{\link[=kNNdist]{kNNdist()}},
\code{\link[=sNN]{sNN()}}
}
\author{
Michael Hahsler
}
\concept{NN functions}
\keyword{model}
