R: Apply Function to Every Neighbourhood in a Point Pattern

applynbd {spatstat} | 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)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner r.turner@auckland.ac.nz and Ege Rubak rubak@math.aau.dk.

### See Also

`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
      # (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)
      }

[Package spatstat version 1.63-3 Index]