R: Nearest neighbour

nnwhich {spatstat} | R Documentation

## Nearest neighbour

### Description

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

### Usage

      nnwhich(X, ...)
      ## S3 method for class 'ppp'
    nnwhich(X, ..., k=1, by=NULL, method="C")
      ## Default S3 method:
    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 kth 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.

### Author(s)

Pavel Grabarnik pavel.grabar@issp.serpukhov.su and Adrian Baddeley Adrian.Baddeley@curtin.edu.au

### See Also

`nndist`, `nncross`

### Examples

       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)))

[Package spatstat version 1.63-3 Index]