applynbd: Apply Function to Every Neighbourhood in a Point Pattern

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/applynbd.R

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.

When applynbd is executed, each point of X is visited, and the following happens for each point:

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

.

See Also

ppp.object, apply, markstat, marktable

Examples

 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[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)
  }

spatstat documentation built on Nov. 21, 2017, 9:06 a.m.