# nncross.pp3: Nearest Neighbours Between Two Patterns in 3D

Description Usage Arguments Details Value Sorting data and pre-sorted data Author(s) See Also Examples

### Description

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

### Usage

 ```1 2 3 4 5 6 7 8 9``` ``` ## 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

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)

, \rolf , and Jens Oehlschlaegel

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

### Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17``` ``` # 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") ```

Search within the spatstat package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? or email at ian@mutexlabs.com.

Please suggest features or report bugs with the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.