Jest                package:spatstat                R Documentation

_E_s_t_i_m_a_t_e _t_h_e _J-_f_u_n_c_t_i_o_n

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

     Estimates the summary function J(r) for a point pattern in a 
     window of arbitrary shape.

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

       Jest(X)
       Jest(X, eps)
       Jest(X, eps, r)
       Jest(X, eps, breaks)

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

       X: The observed point pattern,  from which an estimate of J(r)
          will be computed. An object of class `"ppp"', or data in any
          format acceptable to `as.ppp()'. 

     eps: the resolution of the discrete approximation to Euclidean
          distance (see below). There is a sensible default. 

       r: vector of values for the argument r at which J(r)  should be
          evaluated. There is a sensible default. First-time users are
          strongly advised not to specify this argument. See below for
          important conditions on `r'. 

  breaks: An alternative to the argument `r'. Not normally invoked by
          the user. See Details section. 

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

     The J function (Van Lieshout and Baddeley ,1996) of a stationary
     point process is defined as 

                       J(r) = (1-G(r))/(1-F(r))

     where G(r) is the nearest neighbour distance distribution function
     of the point process (see `Gest')  and F(r) is its empty space
     function (see `Fest').

     For a completely random (uniform Poisson) point process, the
     J-function is identically equal to 1.  Deviations J(r) < 1 or J(r)
     > 1 typically indicate spatial clustering or spatial regularity,
     respectively. The J-function is one of the few characteristics
     that can be computed explicitly for a wide range of point
     processes.  See Van Lieshout and Baddeley (1996), Baddeley et al
     (2000), Thonnes and Van Lieshout (1999)  for further information.

     An estimate of J derived from a spatial point pattern dataset can
     be used in exploratory data analysis and formal inference about
     the pattern. The estimate of J(r) is compared against the 
     constant function 1. Deviations J(r) < 1 or J(r) > 1 may suggest
     spatial clustering or spatial regularity, respectively.

     This algorithm estimates the J-function from the point pattern
     `X'. It assumes that `X' can be treated as a realisation of a
     stationary (spatially homogeneous)  random spatial point process
     in the plane, observed through a bounded window.  The window
     (which is specified in `X' as `X$window') may have arbitrary
     shape. 

     The argument `X' is interpreted as a point pattern object  (of
     class `"ppp"', see `ppp.object') and can be supplied in any of the
     formats recognised by `as.ppp()'. 

     The functions `Fest' and `Gest' are called to  compute estimates
     of F(r) and G(r) respectively. These estimates are then combined
     by simply taking the ratio J(r) = (1-G(r))/(1-F(r)).

     In fact three different estimates are computed using different
     edge corrections (Baddeley, 1998). The Kaplan-Meier estimate
     (returned as `km') is the ratio  `J = (1-G)/(1-F)' of the
     Kaplan-Meier estimates of 1-F and 1-G computed by `Fest' and
     `Gest' respectively. The reduced-sample or border corrected
     estimate (returned as `rs') is the same ratio `J = (1-G)/(1-F)' of
     the border corrected estimates.  These estimators are slightly
     biased for J,  since they are ratios of approximately unbiased
     estimators. The logarithm of the Kaplan-Meier estimate is unbiased
     for log J.

     The uncorrected estimate (returned as `un') is the ratio `J =
     (1-G)/(1-F)' of the uncorrected (``raw'') estimates of the
     survival functions of F and G, which are the empirical
     distribution functions of the  empty space distances
     `Fest(X,...)$raw' and of the nearest neighbour distances 
     `Gest(X,...)$raw'. The uncorrected estimates of F and G are
     severely biased. However the uncorrected estimate of J is
     approximately unbiased (if the process is close to Poisson); it is
     insensitive to edge effects, and should be used when edge effects
     are severe (see Baddeley et al, 2000).

     The algorithm for `Fest' uses two discrete approximations which
     are controlled by the parameter `eps' and by the spacing of values
     of `r' respectively. See `Fest' for details. First-time users are
     strongly advised not to specify these arguments.

     Note that the value returned by `Jest' includes  the output of
     `Fest' and `Gest' as attributes (see the last example below). If
     the user is intending to compute the `F,G' and `J' functions for
     the point pattern, it is only necessary to call `Jest'.

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

     A data frame containing 

       r: the vector of values of the argument r  at which the function
          J has been  estimated

       J: the recommended estimate of J(r), which is the  Kaplan-Meier
          estimate `km'

      rs: the ``reduced sample'' or ``border correction'' estimator of
          J(r) computed from the border-corrected estimates of F and G 

      km: the spatial Kaplan-Meier estimator of J(r) computed from the
          Kaplan-Meier estimates of F and G 

      un: the uncorrected estimate of J(r) computed from the
          uncorrected estimates of F and G 

    theo: the theoretical value of J(r) for a stationary Poisson
          process: identically equal to 1 

       F: the output of `Fest' for this point pattern, containing three
          estimates of the empty space function F(r) and an estimate of
          its hazard function 

       G: the output of `Gest' for this point pattern, containing three
          estimates of the nearest neighbour distance distribution
          function G(r) and an estimate of its hazard function 

_N_o_t_e:

     Sizeable amounts of memory may be needed during the calculation.

_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>

_R_e_f_e_r_e_n_c_e_s:

     Baddeley, A.J. Spatial sampling and censoring. In O.E.
     Barndorff-Nielsen, W.S. Kendall and M.N.M. van Lieshout (eds) 
     Stochastic Geometry: Likelihood and Computation. Chapman and Hall,
     1998. Chapter 2, pages 37-78.

     Baddeley, A.J. and Gill, R.D.  The empty space hazard of a spatial
     pattern. Research Report 1994/3, Department of Mathematics,
     University of Western Australia, May 1994.

     Baddeley, A.J. and Gill, R.D. Kaplan-Meier estimators of
     interpoint distance distributions for spatial point processes.
     Annals of Statistics 25 (1997) 263-292.

     Baddeley, A., Kerscher, M., Schladitz, K. and Scott, B.T.
     Estimating the J function without edge correction. Statistica
     Neerlandica 54 (2000) 315-328.

     Borgefors, G. Distance transformations in digital images. Computer
     Vision, Graphics and Image Processing 34 (1986) 344-371.

     Cressie, N.A.C. Statistics for spatial data. John Wiley and Sons,
     1991.

     Diggle, P.J. Statistical analysis of spatial point patterns.
     Academic Press, 1983.

     Ripley, B.D. Statistical inference for spatial processes.
     Cambridge University Press, 1988.

     Stoyan, D, Kendall, W.S. and Mecke, J. Stochastic geometry and its
     applications. 2nd edition. Springer Verlag, 1995.

     Thonnes, E. and Van Lieshout, M.N.M, A comparative study on the
     power of Van Lieshout and Baddeley's J-function. Biometrical
     Journal 41 (1999) 721-734.

     Van Lieshout, M.N.M. and Baddeley, A.J. A nonparametric measure of
     spatial interaction in point patterns. Statistica Neerlandica 50
     (1996) 344-361.

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

     `Fest', `Gest', `Kest', `kmrs', `reduced.sample', `kaplan.meier'

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

        library(spatstat)
        data(cells)
        Jc <- Jest(cells, 0.01)

        plot(Jc$r, Jc$km, type="l")
        abline(h=1, lty=2)
        # values are far above J= 1, indicating regular pattern

        data(redwood)
        Jw <- Jest(redwood, 0.01)

        plot(Jw$r, Jw$km, type="l")
        abline(h=1, lty=2)
        # values are below J= 1, indicating clustered pattern


        Jc <- Jest(cells, 0.01)
        # alternative plot commands
        plot(km ~ r, type="l", data=Jc)
        # restrict the plot to values of r less than 0.1
        plot(km ~ r, type="l", data=Fc[Fc$r <= 0.1, ])
        plot(km ~ r, type="l", data=Fc, subset=(r <= 0.1))

        # simulated data
        X <- runifpoint(50)
        J <- Jest(X, 0.01)

        plot(J$r, J$km, type="l", xlab="r", ylab="J(r)", ylim=c(0,1),
            main = "empty space function")
        abline(h=1, lty=2)
        legend(0.5, 2, c("Kaplan-Meier estimator", "Poisson process"), lty=c(1,2))


        # functions F, G and J
        Jout <- Jest(X, 0.01)
        FF <- attr(Jout, "F")
        G <- attr(Jout, "G")

        plot(km ~ r, type="l", data=FF, main="Empty space function")
        plot(km ~ r, type="l", data=G, main="Nearest neighbour function")
        plot(km ~ r, type="l", data=Jout, main="J-function")


