# nnwhich

##### Nearest neighbour

Finds the nearest neighbour of each point in a point pattern.

##### Usage

```
nnwhich(X, …)
# S3 method for ppp
nnwhich(X, …, k=1, by=NULL, method="C")
# S3 method for default
nnwhich(X, Y=NULL, …, k=1, by=NULL, method="C")
```

##### Arguments

- X,Y
Arguments specifying the locations of a set of points. For

`nnwhich.ppp`

, the argument`X`

should be a point pattern (object of class`"ppp"`

). For`nnwhich.default`

, typically`X`

and`Y`

would be numeric vectors of equal length. Alternatively`Y`

may be omitted and`X`

may be a list with two components`x`

and`y`

, or a matrix with two columns.- …
Ignored by

`nnwhich.ppp`

and`nnwhich.default`

.- k
Integer, or integer vector. The algorithm will compute the distance to the

`k`

th nearest neighbour.- by
Optional. A factor, which separates

`X`

into groups. The algorithm will find the nearest neighbour in each group.- method
String specifying which method of calculation to use. Values are

`"C"`

and`"interpreted"`

.

##### Details

For each point in the given point pattern, this function finds
its nearest neighbour (the nearest other point of the pattern).
By default it returns a vector giving, for each point,
the index of the point's
nearest neighbour. If `k`

is specified, the algorithm finds
each point's `k`

th nearest neighbour.

The function `nnwhich`

is generic, with
method for point patterns (objects of class `"ppp"`

)
and a default method which are described here, as well as a method for
three-dimensional point patterns (objects of class `"pp3"`

,
described in `nnwhich.pp3`

.

The method `nnwhich.ppp`

expects a single
point pattern argument `X`

.
The default method expects that `X`

and `Y`

will determine
the coordinates of a set of points. Typically `X`

and
`Y`

would be numeric vectors of equal length. Alternatively
`Y`

may be omitted and `X`

may be a list with two components
named `x`

and `y`

, or a matrix or data frame with two columns.

The argument `k`

may be a single integer, or an integer vector.
If it is a vector, then the \(k\)th nearest neighbour distances are
computed for each value of \(k\) specified in the vector.

If the argument `by`

is given, it should be a `factor`

,
of length equal to the number of points in `X`

.
This factor effectively partitions `X`

into subsets,
each subset associated with one of the levels of `X`

.
The algorithm will then find, for each point of `X`

,
the nearest neighbour *in each subset*.

If there are no points (if `x`

has length zero)
a numeric vector of length zero is returned.
If there is only one point (if `x`

has length 1),
then the nearest neighbour is undefined, and a value of `NA`

is returned. In general if the number of points is less than or equal
to `k`

, then a vector of `NA`

's is returned.

The argument `method`

is not normally used. It is
retained only for checking the validity of the software.
If `method = "interpreted"`

then the distances are
computed using interpreted R code only. If `method="C"`

(the default) then C code is used.
The C code is faster by two to three orders of magnitude
and uses much less memory.

To evaluate the *distance* between a point and its nearest
neighbour, use `nndist`

.

To find the nearest neighbours from one point pattern
to another point pattern, use `nncross`

.

##### Value

Numeric vector or matrix giving, for each point,
the index of its nearest neighbour (or `k`

th nearest neighbour).

If `k = 1`

(the default), the return value is a
numeric vector `v`

giving the indices of the nearest neighbours
(the nearest neighbout of the `i`

th point is
the `j`

th point where `j = v[i]`

).

If `k`

is a single integer, then the return value is a
numeric vector giving the indices of the
`k`

th nearest neighbours.

If `k`

is a vector, then the return value is a
matrix `m`

such that `m[i,j]`

is the
index of the `k[j]`

th nearest neighbour for the
`i`

th data point.

If the argument `by`

is given, then the result is a data frame
containing the indices described above, from each point of `X`

,
to the nearest point in each subset of `X`

defined by the factor `by`

.

##### Nearest neighbours of each type

If `X`

is a multitype point pattern
and `by=marks(X)`

, then the algorithm will find,
for each point of `X`

, the nearest neighbour
of each type. See the Examples.

##### Warnings

A value of `NA`

is returned if there is only one point
in the point pattern.

##### See Also

##### Examples

```
# NOT RUN {
data(cells)
plot(cells)
m <- nnwhich(cells)
m2 <- nnwhich(cells, k=2)
# plot nearest neighbour links
b <- cells[m]
arrows(cells$x, cells$y, b$x, b$y, angle=15, length=0.15, col="red")
# find points which are the neighbour of their neighbour
self <- (m[m] == seq(m))
# plot them
A <- cells[self]
B <- cells[m[self]]
plot(cells)
segments(A$x, A$y, B$x, B$y)
# nearest neighbours of each type
head(nnwhich(ants, by=marks(ants)))
# }
```

*Documentation reproduced from package spatstat, version 1.59-0, License: GPL (>= 2)*