nndist: 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 ppp
nndist(X, ..., k=1, by=NULL, proper=FALSE, method="C", metric=NULL)
  # S3 method for default
nndist(X, Y=NULL, ..., k=1, by=NULL, method="C")

Arguments

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 ith data point.

If k is a single integer, then the return value is a numeric vector v such that v[i] is the

kth nearest neighbour distance for the

ith 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

ith data point.

If the argument by is given, then it should be a factor

which separates X into groups (or any type of data acceptable to

split.ppp that determines the grouping). 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 grouping factor by.

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

If proper=FALSE (the default), data points which lie at the same spatial location are treated as different individuals, and the nearest-neighbour distance for any such point is defined to be zero. If proper=TRUE, only distances between distinct points are included in the calculation, so the nearest-neighbour distance is always nonzero (or NA if there are not enough data points).

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.

Examples

Run this code

   # 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