Kci                  package:ecespa                  R Documentation

_T_e_s_t _a_g_a_i_n_s_t _n_o_n-_P_o_i_s_s_o_n (_i_n-)_h_o_m_o_g_e_n_e_o_u_s _m_o_d_e_l_s

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

     Functions to automate testing of 'univariate' and 'bivariate'
     point pattern hypothesis against non-Poisson (in-)homogeneous
     models.

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

     Kci(mod1, mod2, correction="trans", nsim=99, ngrid=200, nrep=1e+05,
          r=NULL, simu="both", spctype=1)

     Ki(mod1, correction="trans", nsim=99, ngrid=200, nrep=1e+05, r=NULL,
         spctype=1)

     ## S3 ploth method for objects of class 'ecespa.kci':
     ## S3 method for class 'ecespa.kci':
     plot(x, type=1, q=0.025, kmean=TRUE, add=FALSE, maine=NULL, 
            xlabe=NULL, ylabe=NULL, xlime=NULL, ylime=NULL, 
            lty=c(1,2,3), col=c(1,2,3), lwd=c(1,1,1), ...)

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

    mod1: Fitted model. An object of class 'ppm' or 
          'ecespa.minconfit'. 

    mod2: Fitted model. An object of class 'ppm' or 
          'ecespa.minconfit'. 

correction: A character item selecting any of the options "border",
          "bord.modif",  or "translate". It specifies  the edge
          correction to be applied when computing K-functions. 

    nsim: Number of simulated point patterns to be generated when
          computing the envelopes. 

   ngrid: Dimensions (ngrid by ngrid) of a rectangular grid of
          locations where 'predict.ppm'  would evaluate the spatial
          trend of the fitted models. 

    nrep: Total number of steps (proposals) of Metropolis-Hastings
          algorithm that should be run by 'rmh' to simulate models of
          class 'ppm'.

       r: Numeric vector. The values of the argument r at which the
          K(r) functions  should be evaluated. 

    simu: A character item indicating if both models will be simulated
          for the computation of the envelopes ('simu = "both"') or 
          just the second model ('simu != "both"'). 

 spctype: Type of 'pre-thinning' method employed by 'rIPCP' in the
          simulation of 'ecespa.minconfit' models. 

       x: An object of class 'ecespa.kci'. The result of runing 'Kci'
          or 'Ki'. 

    type: What to plot. One of 1 (_K1_), 2 (_K2_), 12 (_K12_), 21
          (_K21_), 112 (_K1-K12_) or 221 (_K2-K21_). 

       q: Quantile for selecting the simulation envelopes.

   kmean: Logical. Should the mean of the simulated envelopes be
          ploted?

     add: Logical. Should the kci.plot be added to a previous plot? 

   maine: Title to add to the plot.

   xlabe: Text  or expression to label the x-axis.

   ylabe: Text  or expression to label the y-axis. 

   xlime: Max and min coordinates for the x-axis.

   ylime: Max and min coordinates for the y-axis.

     lty: Vector with the line type for the estimated Kmm function, the
          simulated envelopes and the mean of the simulated envelopes. 

     col: Vector with the color for the estimated K-function, the
          simulated envelopes and the mean of the simulated envelopes.

     lwd: Vector with the line width for the estimated K-function, the
          simulated envelopes and the mean of the simulated envelopes.

     ...: Additional graphical parameters passed to plot.

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

     These functions are designed to automate the testing of
     'univariate' and(/or) 'bivariate' point pattern hypotheses (based
     on K-functions) against non-Poisson (in-)homogeneous models. These
     non-Poisson (in-)homogeneous models should have been fitted with
     pseudolikelihood tools ('spatstat' 'ppm' function) or  with
     minimum contrast methods ('ecespa.minconfit').

     Function 'Ki' is designed to test 'univariate' hypotheses. It will
     compute the (in-)homogeneous K-function (using 'spatstat' 'Kinhom'
     function)  of the point pattern to which  the 'ppm' or 
     'ecespa.minconfit' model has beeen fitted and will compute
     'envelopes' simulating from the fitted model.  The computed
     envelopes can be considered as a pointwise test of the point
     pattern been a realisation of the fitted model.

     Function 'Kci' is designed to test 'bivariate' hypotheses. It will
     compute the  (in-)homogeneous cross K-function  (using 'spatstat'
     'Kcross.inhom' function)  and will compute envelopes simulating
     from the fitted models. As, when dealing with inhomogeneos
     patterns K12 != K21, 'Kci' will compute both functions. If 'simu =
     "both"' (default option), 'Kci' will simulate from 'mod2' to test
     K12 and from 'mod1' to test K21. If 'simu != "both"', only 'mod2'
     will be simulated. This option  may be useful when only K12 is of
     interest. Function 'Kci' will also compute univariate (in-)
     homogeneous K-functions and envelopes for each individual point
     pattern.

     The S3 ploth method will plot the selected K-function and
     envelopes (actually, it will plot the most usual L-function =
     sqrt[K(r)/pi]-r).  The appropriate K function can be selected with
     the argument 'type'. If 'type = 1' (default option), it will plot
     the univariate K function  (of the analized model in 'Ki' or of
     the first model [mod1] in 'Kci'). If 'type = 2', it will plot the
     univariate K function of the second model  (mod2 in 'Kci'). When 
     'type = 12' or 'type = 21', it will plot respectively K12 or K21.
     Options 'type = 112' or 'type = 221' will graph a kind of
     'segregation test' (see 'K1K2'), and will represent de differences
      K1-K12,  K2-K21 and their envelopes.

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

     Both 'Kci' and 'Ki' return an object of class ''ecespa.kci'',
     basically a list with the following items:

      r : Numeric vector. The values of the argument r at which the
          K(r) functions  have been evaluated.

    kia : Numeric vector. Observed (in-)homogeneous K function for
          'mod1' point pattern.

    kib : Numeric vector. Observed (in-)homogeneous K function for
          'mod2' point pattern.

kci.ab.o : Numeric vector. Observed (in-) homogeneous cross K-function
          (K12) for 'mod1' and 'mod2' point patterns.

kci.ba.o : Numeric vector. Observed (in-) homogeneous cross K-function
          (K21) for 'mod2' and 'mod1' point patterns.

kci.ab.s : Matrix of simulated (in-) homogeneous cross K-function (K12)
          for 'mod1' and 'mod2' point patterns.

kci.ba.s : Matrix of simulated (in-) homogeneous cross K-function (K21)
          for 'mod2' and 'mod1' point patterns.

  kib.s : Matrix of simulated (in-)homogeneous K function for 'mod2'
          point pattern.

  kia.s : Matrix of simulated (in-)homogeneous K function for 'mod1'
          point pattern.

datanamea : Name of 'mod1' point pattern.

datanameb : Name of 'mod2' point pattern.

modnamea : Name of model 'mod1'.

modnameb : Name of model 'mod2'.

   type : Type of analysis. "Kci" or "Ki".

_W_a_r_n_i_n_g:

     As this implementation involves the use of images as the means of
     evaluation of the (inhomogeneous) spatial trend, and a mask based
     on those images will be used as the point pattern window, the
     "Ripley's" or "isotropic" edge correction can not be employed.

     It is usual that during the simulation process some warnings are
     produced.  They are related to some simulated points being
     rejected as lying outside the specified window.

_N_o_t_e:

     Even when one of the two point patterns is assumed to be
     homogeneous Poisson (and, apparently  not worth of fitting any
     model), an homogeneous Poisson model can be easily fitted and
     passed to 'Kci' with 'ppm'. See the examples.

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

     Marcelino de la Cruz Rot marcelino.delacruz@upm.es

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

     De la Cruz, M. and Escudero, A. 2008. Null models and tools for
     multivariate heterogeneous point patterns. _Submitted_.

     De Soto, L., Olano, J.M., Rozas, V. and De la Cruz, M. 2009.
     Release of _Juniperus thurifera_ woodlands from herbivore-mediated
     arrested succession in Spain. _Applied Vegetation Science_. DOI:
     10.1111/j.1654-109X.2009.01045.x .

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

      ## Not run: 
      
         require(spatstat)
         data(urkiola)

        #####################
        ## univariate example

        # get univariate pp
        I.ppp <- split.ppp(urkiola)$birch

        # estimate inhomogeneous intensity function
        I.lam <- predict (ppm(I.ppp, ~polynom(x,y,2)), type="trend", ngrid=200)

        # Compute and plot envelopes to Kinhom, simulating from an Inhomogeneous
        #  Poisson Process:
        
        I2.env <- envelope( I.ppp,Kinhom, lambda=I.lam, correction="trans", 
                                   nsim=99, simulate=expression(rpoispp(I.lam)))
        plot(I2.env, sqrt(./pi)-r~r) 

        # It seems that there is short scale clustering; let's fit an Inhomogeneous 
        # Poisson Cluster Process: 

        I.ki <- ipc.estK(mippp=I.ppp, lambda=I.lam, correction="trans")

        # Compute and plot envelopes to Kinhom, simulating from the fitted IPCP:

        Ipc.env <- Ki(I.ki, correction="trans", nsim=99, ngrid=200)

        plot (Ipc.env)
      
        #####################
        ## bivariate example: test independence between birch and quercus in Urkiola

        J.ppp <- split.ppp(urkiola)$oak
        
        # We want to simulate oak from a homogeneous Poisson model:
        J.ppm <- ppm(J.ppp, trend=~1, interaction=Poisson() )
        
        IJ.env <- Kci (mod1=I.ki, nsim=99, mod2=J.ppm)
        
        plot(IJ.env, type=12)
        
        plot(IJ.env, type=21)
      
      ## End(Not run)

