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.
- Keywords
- spatial, programming, iteration
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 byas.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 theN
points ofX
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 ofX
which lie within a distanceR
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 formname=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 theN
points ofX
which are closest to the current point (including the current point itself unlessexclude=TRUE
). - If
R
is given, then the neighbourhood of the current point consists of all points ofX
which lie closer than a distanceR
from the current point. - If
criterion
is given, then it must be a function with two argumentsdist
anddrank
which 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 asdist
anddrank
whosei
-th entry isTRUE
if the corresponding point should be included in the neighbourhood. See the examples below. - If more than one of the arguments
N
,R
andcriterion
is given, the neighbourhood is defined as theintersectionof the neighbourhoods specified by these arguments. For example ifN=3
andR=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, ...)
wherecurrent
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 inY
,dranks
is 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 to
FUN
is stored.
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 toFUN
returns a single numeric value, the result is a vector of dimensionX$n
, the number of points inX
. If each call toFUN
returns a vector of the same lengthm
, then the result is a matrix of dimensionsc(m,n)
; note the transposition of the indices, as usual for the family ofapply
functions. If the calls toFUN
return vectors of different lengths, the result is a list of lengthX$n
.
See Also
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)