# nncross.pp3

##### Nearest Neighbours Between Two Patterns in 3D

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.

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

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