spatstat.geom (version 2.0-1)

# nnwhich: Nearest neighbour

## Description

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"`.

## 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.

## 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`.

`nndist`, `nncross`

## Examples

```# NOT RUN {
data(cells)
plot(cells)
m <- nnwhich(cells)
m2 <- nnwhich(cells, k=2)

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