# applynbd

##### Apply Function to Every Neighbourhood in a Point Pattern

Visit each point in a point pattern, find the neighbouring points, and apply a given function to them.

- Keywords
- spatial, programming, iteration

##### Usage

`applynbd(X, FUN, N=NULL, R=NULL, criterion=NULL, exclude=FALSE, …)`

##### Arguments

- X
Point pattern. An object of class

`"ppp"`

, or data which can be converted into this format by`as.ppp`

.- FUN
Function to be applied to each neighbourhood. The arguments of

`FUN`

are described under**Details**.- N
Integer. If this argument is present, the neighbourhood of a point of

`X`

is defined to consist of the`N`

points of`X`

which are closest to it.- R
Nonnegative numeric value. If this argument is present, the neighbourhood of a point of

`X`

is defined to consist of all points of`X`

which lie within a distance`R`

of it.- criterion
Function. If this argument is present, the neighbourhood of a point of

`X`

is determined by evaluating this function. See under**Details**.- exclude
Logical. If

`TRUE`

then the point currently being visited is excluded from its own neighbourhood.- …
extra arguments passed to the function

`FUN`

. They must be given in the form`name=value`

.

##### Details

This is an analogue of `apply`

for point patterns. It visits each point in the point pattern `X`

,
determines which points of `X`

are ``neighbours'' of the current
point, applies the function `FUN`

to this neighbourhood,
and collects the values returned by `FUN`

.

The definition of ``neighbours'' depends on the arguments
`N`

, `R`

and `criterion`

.
Also the argument `exclude`

determines whether
the current point is excluded from its own neighbourhood.

If

`N`

is given, then the neighbours of the current point are the`N`

points of`X`

which are closest to the current point (including the current point itself unless`exclude=TRUE`

).If

`R`

is given, then the neighbourhood of the current point consists of all points of`X`

which lie closer than a distance`R`

from the current point.If

`criterion`

is given, then it must be a function with two arguments`dist`

and`drank`

which will be vectors of equal length. The interpretation is that`dist[i]`

will be the distance of a point from the current point, and`drank[i]`

will be the rank of that distance (the three points closest to the current point will have rank 1, 2 and 3). This function must return a logical vector of the same length as`dist`

and`drank`

whose`i`

-th entry is`TRUE`

if the corresponding point should be included in the neighbourhood. See the examples below.If more than one of the arguments

`N`

,`R`

and`criterion`

is given, the neighbourhood is defined as the*intersection*of the neighbourhoods specified by these arguments. For example if`N=3`

and`R=5`

then the neighbourhood is formed by finding the 3 nearest neighbours of current point, and retaining only those neighbours which lie closer than 5 units from the current point.

When `applynbd`

is executed,
each point of `X`

is visited, and the following happens
for each point:

the neighbourhood of the current point is determined according to the chosen rule, and stored as a point pattern

`Y`

;the function

`FUN`

is called as:`FUN(Y=Y, current=current, dists=dists, dranks=dranks, …)`

where

`current`

is the location of the current point (in a format explained below),`dists`

is a vector of distances from the current point to each of the points in`Y`

,`dranks`

is a vector of the ranks of these distances with respect to the full point pattern`X`

, and`…`

are the arguments passed from the call to`applynbd`

;The result of the call to

`FUN`

is stored.

The results of each call to `FUN`

are collected and returned
according to the usual rules for `apply`

and its
relatives. See the **Value** section of this help file.

The format of the argument `current`

is as follows.
If `X`

is an unmarked point pattern, then `current`

is a
vector of length 2 containing the coordinates of the current point.
If `X`

is marked, then `current`

is a point pattern
containing exactly one point, so that `current$x`

is its
\(x\)-coordinate and `current$marks`

is its mark value.
In either case, the coordinates of the current point can be referred to as
`current$x`

and `current$y`

.

Note that `FUN`

will be called exactly as described above,
with each argument named explicitly. Care is required when writing the
function `FUN`

to ensure that
the arguments will match up. See the Examples.

See `markstat`

for a common use of this function.

To simply tabulate the marks in every `R`

-neighbourhood, use
`marktable`

.

##### Value

Similar to the result of `apply`

.
If each call to `FUN`

returns a single numeric value,
the result is a vector of dimension `npoints(X)`

, the number of points
in `X`

.
If each call to `FUN`

returns a vector of the same length
`m`

, then the result is a matrix of dimensions `c(m,n)`

;
note the transposition of the indices, as usual for the family of
`apply`

functions.
If the calls to `FUN`

return vectors of different lengths,
the result is a list of length `npoints(X)`

.

##### See Also

##### Examples

```
# NOT RUN {
redwood
# count the number of points within radius 0.2 of each point of X
nneighbours <- applynbd(redwood, R=0.2, function(Y, ...){npoints(Y)-1})
# equivalent to:
nneighbours <- applynbd(redwood, R=0.2, function(Y, ...){npoints(Y)}, exclude=TRUE)
# compute the distance to the second nearest neighbour of each point
secondnndist <- applynbd(redwood, N = 2,
function(dists, ...){max(dists)},
exclude=TRUE)
# marked point pattern
trees <- longleaf
# }
# NOT RUN {
# compute the median of the marks of all neighbours of a point
# (see also 'markstat')
dbh.med <- applynbd(trees, R=90, exclude=TRUE,
function(Y, ...) { median(marks(Y))})
# ANIMATION explaining the definition of the K function
# (arguments `fullpicture' and 'rad' are passed to FUN)
if(interactive()) {
showoffK <- function(Y, current, dists, dranks, fullpicture,rad) {
plot(fullpicture, main="")
points(Y, cex=2)
ux <- current[["x"]]
uy <- current[["y"]]
points(ux, uy, pch="+",cex=3)
theta <- seq(0,2*pi,length=100)
polygon(ux + rad * cos(theta), uy+rad*sin(theta))
text(ux + rad/3, uy + rad/2,npoints(Y),cex=3)
if(interactive()) Sys.sleep(if(runif(1) < 0.1) 1.5 else 0.3)
return(npoints(Y))
}
applynbd(redwood, R=0.2, showoffK, fullpicture=redwood, rad=0.2, exclude=TRUE)
# animation explaining the definition of the G function
showoffG <- function(Y, current, dists, dranks, fullpicture) {
plot(fullpicture, main="")
points(Y, cex=2)
u <- current
points(u[1],u[2],pch="+",cex=3)
v <- c(Y$x[1],Y$y[1])
segments(u[1],u[2],v[1],v[2],lwd=2)
w <- (u + v)/2
nnd <- dists[1]
text(w[1],w[2],round(nnd,3),cex=2)
if(interactive()) Sys.sleep(if(runif(1) < 0.1) 1.5 else 0.3)
return(nnd)
}
applynbd(cells, N=1, showoffG, exclude=TRUE, fullpicture=cells)
}
# }
```

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