R: K-th Nearest Point Map

nnmap {spatstat.geom} | R Documentation

## K-th Nearest Point Map

### Description

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]]`.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

, Rolf Turner r.turner@auckland.ac.nz , and Jens Oehlschlaegel

### See Also

`distmap`

### Examples

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

[Package spatstat.geom version 2.2-0 Index]