applynbd              package:spatstat              R Documentation

_A_p_p_l_y _F_u_n_c_t_i_o_n _t_o _E_v_e_r_y _N_e_i_g_h_b_o_u_r_h_o_o_d _i_n _a _P_o_i_n_t _P_a_t_t_e_r_n

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

       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. This argument is incompatible with
          'R' and 'criterion'. 

       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. This
          argument is incompatible with 'N' and 'criterion'. 

criterion: Function. If this argument is present,  the neighbourhood of
          a point of 'X' is determined by evaluating this function. See
          under *Details*. This argument is incompatible with 'N' and
          'R'. 

 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'. 

_D_e_t_a_i_l_s:

     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', exactly one of which must be given. 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.

     Each point of 'X' is visited; the neighbourhood of the current
     point is determined, and stored as a point pattern 'Y'; then the
     function 'FUN' is called as 'FUN(Y, current, dists, dranks, ...)'
     where 'current' is a 'list(x,y)' giving the location of the
     current point, '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 results of each call to 'FUN' are collected and returned
     according to the usual rules for 'apply' and its relatives. See
     *Value* above.

_V_a_l_u_e:

     Similar to the result of 'apply'. If each call to 'FUN' returns a
     single numeric value, the result is a vector of dimension 'X$n',
     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 'X$n'.

_A_u_t_h_o_r(_s):

     Adrian Baddeley adrian@maths.uwa.edu.au <URL:
     http://www.maths.uwa.edu.au/~adrian/> and Rolf Turner
     rolf@math.unb.ca <URL: http://www.math.unb.ca/~rolf>

_S_e_e _A_l_s_o:

     'ppp.object', 'apply'

_E_x_a_m_p_l_e_s:

       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(Y, cur, d, r){max(d)}, exclude=TRUE)

       # marked point pattern
       data(longleaf)
       
       # compute the median of the marks of all neighbours of a point
       dbh.med <- applynbd(longleaf, R=40, 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, u, d, r, fullpicture,rad) { 
             plot(fullpicture, main="")
             points(Y[r>0], cex=2)
             points(u[1],u[2],pch="+",cex=3)
             theta <- seq(0,2*pi,length=100)
             polygon(u[1]+ rad * cos(theta),u[2]+rad*sin(theta))
             text(u[1]+rad/3,u[2]+rad/2,Y$n-1,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)

       # animation explaining the definition of the G function

       showoffG <- function(Y, u, d, r, fullpicture) { 
             plot(fullpicture, main="")
             points(Y, cex=2)
             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 <- sqrt(sum((u-v)^2))
             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)

