R: Nearest neighbour distances

nndist {spatstat.geom} | R Documentation

## Nearest neighbour distances

### Description

Computes the distance from each point to its nearest neighbour in a point pattern. Alternatively computes the distance to the second nearest neighbour, or third nearest, etc.

### Usage

      nndist(X, ...)
      ## S3 method for class 'ppp'
    nndist(X, ..., k=1, by=NULL, method="C")
      ## Default S3 method:
    nndist(X, Y=NULL, ..., k=1, by=NULL, method="C")

### Arguments

`X,Y` | Arguments specifying the locations of a set of points. For `nndist.ppp`, the argument `X` should be a point pattern (object of class `"ppp"`). For `nndist.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. Alternatively `X` can be a three-dimensional point pattern (class `"pp3"`), a higher-dimensional point pattern (class `"ppx"`), a point pattern on a linear network (class `"lpp"`), or a spatial pattern of line segments (class `"psp"`).
`...` | Ignored by `nndist.ppp` and `nndist.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 compute the distance to the nearest point in each group.
`method` | String specifying which method of calculation to use. Values are `"C"` and `"interpreted"`.

### Details

This function computes the Euclidean distance from each point in a point pattern to its nearest neighbour (the nearest other point of the pattern). If `k` is specified, it computes the distance to the `k`th nearest neighbour.

The function `nndist` is generic, with a method for point patterns (objects of class `"ppp"`), and a default method for coordinate vectors.

There are also methods for line segment patterns, `nndist.psp`, three-dimensional point patterns, `nndist.pp3`, higher-dimensional point patterns, `nndist.ppx` and point patterns on a linear network, `nndist.lpp`; these are described in their own help files. Type `methods(nndist)` to see all available methods.

The method for planar point patterns `nndist.ppp` expects a single point pattern argument `X` and returns the vector of its nearest neighbour distances.

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 compute, for each point of `X`, the distance to the nearest neighbour in each subset.

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.

If there is only one point (if `x` has length 1), then a nearest neighbour distance of `Inf` is returned. If there are no points (if `x` has length zero) a numeric vector of length zero is returned.

To identify which point is the nearest neighbour of a given point, use `nnwhich`.

To use the nearest neighbour distances for statistical inference, it is often advisable to use the edge-corrected empirical distribution, computed by `Gest`.

To find the nearest neighbour distances from one point pattern to another point pattern, use `nncross`.

### Value

Numeric vector or matrix containing the nearest neighbour distances for each point.

If `k = 1` (the default), the return value is a numeric vector `v` such that `v[i]` is the nearest neighbour distance for the `i`th data point.

If `k` is a single integer, then the return value is a numeric vector `v` such that `v[i]` is the `k`th nearest neighbour distance for the `i`th data point.

If `k` is a vector, then the return value is a matrix `m` such that `m[i,j]` is the `k[j]`th nearest neighbour distance for the `i`th data point.

If the argument `by` is given, then the result is a data frame containing the distances 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 compute, for each point of `X`, the distance to the nearest neighbour of each type. See the Examples.

To find the minimum distance from any point of type `i` to the nearest point of type `j`, for all combinations of `i` and `j`, use `minnndist`, or the R function `aggregate` as suggested in the Examples.

### Warnings

An infinite or `NA` value is returned if the distance is not defined (e.g. 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.psp`, `nndist.pp3`, `nndist.ppx`, `pairdist`, `Gest`, `nnwhich`, `nncross`, `minnndist`, `maxnndist`.

### Examples

       data(cells)
       # nearest neighbours
       d <- nndist(cells)

       # second nearest neighbours
       d2 <- nndist(cells, k=2)

       # first, second and third nearest
       d1to3 <- nndist(cells, k=1:3)

       x <- runif(100)
       y <- runif(100)
       d <- nndist(x, y)

       # Stienen diagram
       plot(cells %mark% nndist(cells), markscale=1)

       # distance to nearest neighbour of each type
       nnda <- nndist(ants, by=marks(ants))
       head(nnda)
       # For nest number 1, the nearest Cataglyphis nest is 87.32125 units away

       # minimum distance between each pair of types
       minnndist(ants, by=marks(ants))

       # Use of 'aggregate':
       # _minimum_ distance between each pair of types
       aggregate(nnda, by=list(from=marks(ants)), min)
       # _mean_ nearest neighbour distances
       aggregate(nnda, by=list(from=marks(ants)), mean)
       # The mean distance from a Messor nest to
       # the nearest Cataglyphis nest is 59.02549 units

[Package spatstat.geom version 2.2-0 Index]