# nndist

##### Nearest neighbour distances

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, method="C")
# S3 method for default
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 \(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*.

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

##### See Also

`nndist.psp`

,
`nndist.pp3`

,
`nndist.ppx`

,
`nndist.lpp`

,
`pairdist`

,
`Gest`

,
`nnwhich`

,
`nncross`

.

##### Examples

```
# NOT RUN {
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)/2), 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
# Use of 'aggregate':
# minimum distance between each pair of types
aggregate(nnda, by=list(from=marks(ants)), min)
# Always a symmetric matrix
# 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
# }
```

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