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.

Usage

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

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.

• IfNis given, then the neighbours of the current point are theNpoints ofXwhich are closest to the current point (including the current point itself unlessexclude=TRUE).
• IfRis given, then the neighbourhood of the current point consists of all points ofXwhich lie closer than a distanceRfrom the current point.
• Ifcriterionis given, then it must be a function with two argumentsdistanddrankwhich will be vectors of equal length. The interpretation is thatdist[i]will be the distance of a point from the current point, anddrank[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 asdistanddrankwhosei-th entry isTRUEif the corresponding point should be included in the neighbourhood. See the examples below.
• If more than one of the argumentsN,Randcriterionis given, the neighbourhood is defined as theintersectionof the neighbourhoods specified by these arguments. For example ifN=3andR=5then 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 patternY;
• the functionFUNis called as:FUN(Y=Y, current=current, dists=dists, dranks=dranks, ...)wherecurrentis the location of the current point (in a format explained below),distsis a vector of distances from the current point to each of the points inY,dranksis a vector of the ranks of these distances with respect to the full point patternX, and...are the arguments passed from the call toapplynbd;
• The result of the call toFUNis stored.

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.

See Also

ppp.object, apply, markstat, marktable

Aliases

• applynbd

Examples

data(redwood)

  # count the number of points within radius 0.2 of each point of X
  nneighbours <- applynbd(redwood, R=0.2, function(Y, ...){Y$n-1})
  # equivalent to:
  nneighbours <- applynbd(redwood, R=0.2, function(Y, ...){Y$n}, 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
  data(longleaf)
  <testonly># smaller dataset
	longleaf <- longleaf[seq(1, longleaf$n, by=80)]</testonly>
  # compute the median of the marks of all neighbours of a point
  # (see also 'markstat')
  dbh.med <- applynbd(longleaf, R=90, exclude=TRUE,
                 function(Y, ...) { median(Y$marks)})


  # ANIMATION explaining the definition of the K function
  # (arguments `fullpicture' and 'rad' are passed to FUN)

  showoffK <- function(Y, current, dists, dranks, fullpicture,rad) { 
	plot(fullpicture, main="")
	points(Y, cex=2)
        u <- current
	points(u$x,u$y,pch="+",cex=3)
	theta <- seq(0,2*pi,length=100)
	polygon(u$x+ rad * cos(theta),u$y+rad*sin(theta))
	text(u$x+rad/3,u$y+rad/2,Y$n,cex=3)
	Sys.sleep(if(runif(1) < 0.1) 1.5 else 0.3)
	return(Y$n - 1)
  }
  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)
	Sys.sleep(if(runif(1) < 0.1) 1.5 else 0.3)
	return(nnd)
  }

  data(cells)
  applynbd(cells, N=1, showoffG, exclude=TRUE, fullpicture=cells)