# 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`

.

`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

`plot(nnmap(cells, 2, what="which"))`

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