prabtest              package:prabclus              R Documentation

_P_a_r_a_m_e_t_r_i_c _b_o_o_t_s_t_r_a_p _t_e_s_t _f_o_r _c_l_u_s_t_e_r_i_n_g _i_n _p_r_e_s_e_n_c_e-_a_b_s_e_n_c_e _m_a_t_r_i_c_e_s

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

     Parametric bootstrap test of a null model of i.i.d., but spatially
     autocorrelated species against clustering of the species' occupied
     areas (or alternatively nestedness). In spite of the lots of
     parameters, a standard execution will be 
      'prabmatrix <- prabinit(file="path/prabmatrixfile",
     neighborhood="path/neighborhoodfile")'
      'test <- prabtest(prabmatrix)'
      'summary(test)'
      *Note:* Data formats are described on the 'prabinit' help page.
     You may also consider the example datasets 'kykladspecreg.dat' and
     'nb.dat'. Take care of the parameter 'rows.are.species' of
     'prabinit'.

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

     prabtest(x, teststat = "distratio", tuning=switch(teststat,distratio=0.25,
     lcomponent=floor(3*ncol(x$distmat)/4),
     isovertice=ncol(x$distmat),nn=4,NA), times = 1000, pd = NULL,
     prange = c(0, 1), nperp = 4, step = 0.1, twostep = TRUE, sf.sim = FALSE,
     sf.const = sf.sim, pdfnb=FALSE)

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

       x: an object of class 'prab' (presence-absence data), as
          generated by 'prabinit'.

teststat: string, indicating the test statistics. '"isovertice"':
          number of isolated vertices in the graph of 'tuning' smallest
          distances between species. '"lcomponent"': size of largest
          connectivity component in this graph. '"distratio"': ratio
          between 'tuning' smallest and largest distances. '"nn"':
          average distance of species to 'tuning'th nearest neighbor. 
          '"inclusions"': number of inclusions between areas of
          different species (tests for nestedness structure, not for
          clustering).

  tuning: integer or (if 'teststat="distratio"') numerical between 0
          and 1. Tuning constant for test statistics, see 'teststat'.

   times: integer. Number of simulation runs.

      pd: numerical between 0 and 1. The probability that a new region
          is drawn from the non-neighborhood of the previous regions
          belonging to a species under generation. If 'NA' (the
          default), 'prabtest' estimates this by function 'autoconst'.
          Otherwise the next four parameters have no effect.

  prange: numerical range vector, lower value not smaller than 0,
          larger value not larger than 1. Range where 'pd' is to be
          found. Used by function 'autoconst'.

   nperp: integer. Number of simulations per 'pd'-value. Used by
          function 'autoconst'.

    step: numerical between 0 and 1. Interval length between subsequent
          choices of 'pd' for the first simulation. Used by function
          'autoconst'.

 twostep: logical. If 'TRUE', a first estimation step for 'pd' is
          carried out in the whole 'prange', and then the final
          estimation is determined between the preliminary estimator
          '-5*step2' and {+5*step2}. Else, the first simulation
          determines the final estimator. Used by function 'autoconst'.

  sf.sim: logical. Indicates if the range sizes of the species are held
          fixed in the test simulation ('TRUE') or generated from their
          empirical distribution in 'x' ('FALSE'). See function
          'randpop.nb'.

sf.const: logical. Same as 'sf.sim', but for estimation of 'pd' by
          'autoconst'.

   pdfnb: logical. If 'TRUE', the probabilities of the regions are
          modified according to the number of neighboring regions in
          'randpop.nb', see Hennig and Hausdorf (2002), p. 5. This is
          usually no improvement.

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

     From the original data, the distribution of the range sizes of the
     species, the autocorrelation parameter 'pd' (estimated by
     'autoconst') and the distribution on the regions induced by the
     relative species numbers are taken. With these parameters, 'times'
     populations according to the null model implemented in
     'randpop.nb' are generated and the test statistic is evaluated.
     The resulting p-value is number of simulated statistic values more
     extreme than than the value of the original data'+1' divided by
     'times+1'. "More extreme" means smaller for '"lcomponent"',
     '"distratio"', '"nn"', larger for '"inclusions"', and twice the
     smaller number between the original statistic value and the
     "border", i.e., a two-sided test for '"isovertice"'. If 'pd=NA'
     was specified, a diagnostic plot for the estimation of 'pd' is
     plotted by 'autoconst'. For details see Hennig and Hausdorf (2002)
     and the help pages of the cited functions.

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

     An object of class 'prabtest', which is a list with components 

 results: vector of test statistic values for all simulated
          populations.

   datac: test statistic value for the original data.'

 p.value: the p-value.

  tuning: see above.

      pd: see above.

     reg: regression coefficients from 'autoconst'.

teststat: see above.

distance: the distance measure chosen, see 'prabinit'.

   times: see above.

   pdfnb: see above.

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

     Christian Hennig hennig@math.uni-hamburg.de <URL:
     http://www.math.uni-hamburg.de/home/hennig/>

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

     Hennig, C. and Hausdorf, B. (2002) Distance-based parametric
     bootstrap tests for clustering of species ranges, submitted, <URL:
     http://stat.ethz.ch/Research-Reports/110.html>.

     Hausdorf, B. and Hennig, C. (2003)  Biotic Element Analysis in
     Biogeography. To appear in  _Systematic Biology_.

     Hausdorf, B. and Hennig, C. (2003) Nestedness of nerth-west
     European land snail ranges as a consequence of differential
     immigration from Pleistocene glacial refuges. _Oecologia_ 135,
     102-109.

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

     'prabinit' generates objects of class 'prab'.

     'autoconst' estimates 'pd' from such objects.

     'randpop.nb' generates populations from the null model. An
     alternative model is given by 'cluspop.nb'.

     Some more information on the test statistics is given in
     'homogen.test', 'lcomponent', 'distratio', 'nn', 'incmatrix'.

     The simulations are computed by 'pop.sim'.

     Summary and print methods: 'summary.prabtest'.

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

     data(kykladspecreg)
     # Note: If you do not use the installed package, replace this by
     # kykladspecreg <- read.table("(path/)kykladspecreg.dat")
     data(nb)
     # Note: If you do not use the installed package, replace this by
     # nb <- list()
     # for (i in 1:34)
     #   nb <- c(nb,list(scan(file="(path/)nb.dat",
     #                   skip=i-1,nlines=1)))
     set.seed(1234)
     x <- prabinit(prabmatrix=kykladspecreg, neighborhood=nb)
     # If you want to use your own ASCII data files, use
     # x <- prabinit(file="path/prabmatrixfile",
     # neighborhood="path/neighborhoodfile")
     prabtest(x, times=100, pd=0.35)
     # These settings are chosen to make the example execution
     # a bit faster; usually you will use prabtest(kprab).

