# nnmap

##### K-th Nearest Point Map

Given a point pattern, this function constructs pixel images giving the distance from each pixel to its \(k\)-th nearest neighbour in the point pattern, and the index of the \(k\)-th nearest neighbour.

##### Usage

```
nnmap(X, k = 1, what = c("dist", "which"),
…, W = as.owin(X),
is.sorted.X = FALSE, sortby = c("range", "var", "x", "y"))
```

##### Arguments

- X
Point pattern (object of class

`"ppp"`

).- k
Integer, or integer vector. The algorithm will find the

`k`

th nearest neighbour.- what
Character string specifying what information should be returned. Either the nearest neighbour distance (

`"dist"`

), the index of the nearest neighbour (`"which"`

), or both.- …
Arguments passed to

`as.mask`

to determine the pixel resolution of the result.- W
Window (object of class

`"owin"`

) specifying the spatial domain in which the distances will be computed. Defaults to the window of`X`

.- is.sorted.X
Logical value attesting whether the point pattern

`X`

has been sorted. See Details.- sortby
Determines which coordinate to use to sort the point pattern. See Details.

##### Details

Given a point pattern `X`

, this function constructs two pixel images:

a distance map giving, for each pixel, the distance to the nearest point of

`X`

;a nearest neighbour map giving, for each pixel, the identifier of the nearest point of

`X`

.

If the argument `k`

is specified, then the `k`

-th nearest
neighbours will be found.

If `what="dist"`

then only the distance map is returned.
If `what="which"`

then only the nearest neighbour map
is returned.

The argument `k`

may be an integer or an integer vector.
If it is a single integer, then the `k`

-th nearest neighbours
are computed. If it is a vector, then the `k[i]`

-th nearest
neighbours are computed for each entry `k[i]`

. For example, setting
`k=1:3`

will compute the nearest, second-nearest and
third-nearest neighbours.

##### Value

A pixel image, or a list of pixel images.

By default (if `what=c("dist", "which")`

), the result is
a list with two components `dist`

and `which`

containing the distance map and the nearest neighbour map.

If `what="dist"`

then the result is a real-valued pixel image
containing the distance map.

If `what="which"`

then the result is an integer-valued pixel image
containing the nearest neighbour map.

If `k`

is a vector of several integers, then the result is
similar except that each pixel image is replaced by a list of
pixel images, one for each entry of `k`

.

##### Sorting data and pre-sorted data

Read this section if you care about the speed of computation.

For efficiency, the algorithm sorts the point pattern `X`

into increasing order of the \(x\) coordinate
or increasing order of the the \(y\) coordinate.
Sorting is only an intermediate step;
it does not affect the output, which is always given in the same
order as the original data.

By default (if `sortby="range"`

),
the sorting will occur on the coordinate that has the larger range of
values (according to the frame of the enclosing window of `X`

).
If `sortby = "var"`

), sorting will occur on the coordinate that
has the greater variance (in the pattern `X`

).
Setting `sortby="x"`

or `sortby = "y"`

will specify that
sorting should occur on the \(x\) or \(y\) coordinate, respectively.

If the point pattern `X`

is already
sorted, then the argument `is.sorted.X`

should be set to `TRUE`

, and `sortby`

should be set
equal to `"x"`

or `"y"`

to indicate which coordinate
is sorted.

##### Warning About Ties

Ties are possible: there may be two data points
which lie exactly the same distance away from a particular pixel.
This affects the results from `nnmap(what="which")`

.
The handling of ties is not well-defined: it is not consistent
between different computers and different installations of R.
If there are ties, then different calls to `nnmap(what="which")`

may give inconsistent results. For example, you may get a different answer
from `nnmap(what="which",k=1)`

and `nnmap(what="which", k=1:2)[[1]]`

.

##### See Also

##### Examples

```
# NOT RUN {
plot(nnmap(cells, 2, what="which"))
# }
```

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