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

## Description

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

## Usage

 `1` ``` 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`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56``` ``` 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 # (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,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) } ```