nnmap: K-th Nearest Point Map

In spatstat.geom: Geometrical Functionality of the 'spatstat' Family

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"), squared=FALSE)

Arguments

X	Point pattern (object of class "ppp").
k	Integer, or integer vector. The algorithm will find the kth 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.
squared	Logical value specifying whether to return the squared distances instead of the distances themselves.

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.

If squared=TRUE then squared distances are returned with the name "dist2" instead of "dist".

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

, \rolf, and Jens Oehlschlaegel

See Also

distmap

Examples

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

spatstat.geom documentation built on March 21, 2026, 9:06 a.m.