# applynbd: Apply Function to Every Neighbourhood in a Point Pattern In spatstat.geom: Geometrical Functionality of the 'spatstat' Family

 applynbd R Documentation

## Apply Function to Every Neighbourhood in a Point Pattern

### Description

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

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

### Author(s)

\spatstatAuthors

.

`ppp.object`, `apply`, `markstat`, `marktable`

### Examples

```  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

# compute the median of the marks of all neighbours of a point
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)
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,u,pch="+",cex=3)
v <- c(Y\$x,Y\$y)
segments(u,u,v,v,lwd=2)
w <- (u + v)/2
nnd <- dists
text(w,w,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)
}
```

spatstat.geom documentation built on March 29, 2022, 9:06 a.m.