R: Nearest Neighbours Between Two Patterns in 3D

nncross.pp3 {spatstat.geom} | R Documentation

## Nearest Neighbours Between Two Patterns in 3D

### Description

Given two point patterns `X` and `Y` in three dimensions, finds the nearest neighbour in `Y` of each point of `X`.

### Usage

      ## S3 method for class 'pp3'
    nncross(X, Y,
              iX=NULL, iY=NULL,
              what = c("dist", "which"),
              ...,
              k = 1,
              sortby=c("range", "var", "x", "y", "z"),
              is.sorted.X = FALSE,
              is.sorted.Y = FALSE)

### Arguments

`X,Y` | Point patterns in three dimensions (objects of class `"pp3"`).
`iX, iY` | Optional identifiers, used to determine whether a point in `X` is identical to a point in `Y`. See Details.
`what` | Character string specifying what information should be returned. Either the nearest neighbour distance (`"dist"`), the identifier of the nearest neighbour (`"which"`), or both.
`k` | Integer, or integer vector. The algorithm will compute the distance to the `k`th nearest neighbour.
`sortby` | Determines which coordinate to use to sort the point patterns. See Details.
`is.sorted.X, is.sorted.Y` | Logical values attesting whether the point patterns `X` and `Y` have been sorted. See Details.
`...` | Ignored.

### Details

Given two point patterns `X` and `Y` in three dimensions, this function finds, for each point of `X`, the nearest point of `Y`. The distance between these points is also computed. If the argument `k` is specified, then the `k`-th nearest neighbours will be found.

The return value is a data frame, with rows corresponding to the points of `X`. The first column gives the nearest neighbour distances (i.e. the `i`th entry is the distance from the `i`th point of `X` to the nearest element of `Y`). The second column gives the indices of the nearest neighbours (i.e.\ the `i`th entry is the index of the nearest element in `Y`.) If `what="dist"` then only the vector of distances is returned. If `what="which"` then only the vector of indices 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. The result is a data frame.

Note that this function is not symmetric in `X` and `Y`. To find the nearest neighbour in `X` of each point in `Y`, use `nncross(Y,X)`.

The arguments `iX` and `iY` are used when the two point patterns `X` and `Y` have some points in common. In this situation `nncross(X, Y)` would return some zero distances. To avoid this, attach a unique integer identifier to each point, such that two points are identical if their identifying numbers are equal. Let `iX` be the vector of identifier values for the points in `X`, and `iY` the vector of identifiers for points in `Y`. Then the code will only compare two points if they have different values of the identifier. See the Examples.

### Value

A data frame, or a vector if the data frame would contain only one column.

By default (if `what=c("dist", "which")` and `k=1`) a data frame with two columns:

`dist` | Nearest neighbour distance
`which` | Nearest neighbour index in `Y`

If `what="dist"` and `k=1`, a vector of nearest neighbour distances.

If `what="which"` and `k=1`, a vector of nearest neighbour indices.

If `k` is specified, the result is a data frame with columns containing the `k`-th nearest neighbour distances and/or nearest neighbour indices.

### Sorting data and pre-sorted data

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

For efficiency, the algorithm sorts both the point patterns `X` and `Y` into increasing order of the x coordinate, or both into increasing order of the y coordinate, or both into increasing order of the z 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 largest range of values (according to the frame of the enclosing window of `Y`). If `sortby = "var"`), sorting will occur on the coordinate that has the greater variance (in the pattern `Y`). Setting `sortby="x"` or `sortby = "y"` or `sortby = "z"` will specify that sorting should occur on the x, y or z coordinate, respectively.

If the point pattern `X` is already sorted, then the corresponding argument `is.sorted.X` should be set to `TRUE`, and `sortby` should be set equal to `"x"`, `"y"` or `"z"` to indicate which coordinate is sorted.

Similarly if `Y` is already sorted, then `is.sorted.Y` should be set to `TRUE`, and `sortby` should be set equal to `"x"`, `"y"` or `"z"` to indicate which coordinate is sorted.

If both `X` and `Y` are sorted on the same coordinate axis then both `is.sorted.X` and `is.sorted.Y` should be set to `TRUE`, and `sortby` should be set equal to `"x"`, `"y"` or `"z"` to indicate which coordinate is sorted.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au

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

### See Also

`nndist` for nearest neighbour distances in a single point pattern.

### Examples

      # two different point patterns
      X <- pp3(runif(10), runif(10), runif(10), box3(c(0,1)))
      Y <- pp3(runif(20), runif(20), runif(20), box3(c(0,1)))
      N <- nncross(X,Y)$which
      N <- nncross(X,Y, what="which") #faster
      # note that length(N) = 10

      # k-nearest neighbours
      N3 <- nncross(X, Y, k=1:3)

      # two patterns with some points in common
      Z <- pp3(runif(20), runif(20), runif(20), box3(c(0,1)))
      X <- Z[1:15]
      Y <- Z[10:20]
      iX <- 1:15
      iY <- 10:20
      N <- nncross(X,Y, iX, iY, what="which")

[Package spatstat.geom version 2.2-0 Index]