R: Parametric bootstrap test for clustering in presence-absence...

prabtest {prabclus} | R Documentation

## Parametric bootstrap test for clustering in presence-absence matrices

### Description

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 (for the default test statistics, see parameter `teststat` below) 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`.

### Usage

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

    ## S3 method for class 'prabtest'
    summary(object, above.p=object$teststat %in%
             c("groups","inclusions","mean"),
             group.outmean=FALSE,...)

    ## S3 method for class 'summary.prabtest'
    print(x, ...)

### Arguments

`prabobject` | 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 five 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`.
`step2` | numerical between 0 and 1. Interval length between subsequent choices of `pd` for the second simulation (see parameter `twostep`). 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.
`ignore.richness` | logical. If `TRUE`, there is no assumption of species richnesses to differ between regions in the null model. Regionwise probabilities don't differ in the generation of null data.
`object` | object of class `prabtest`.
`above.p` | logical. `TRUE` means that for output from `abundtest` the p-value is `p.above`, otherwise `p.below`.
`group.outmean` | logical. If `TRUE` and `object$teststat="groups"`, statistics concerning the mean of all dissimilarities are given out by `print.summary.prabtest`.
`x` | object of class `summary.prabtest`.
`...` | no meaning, necessary for print and summary methods.

### Details

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 (2004) and the help pages of the cited functions.

### Value

`prabtest` prodices 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`.
`gtf` | the geco-distance tuning parameter (only informative if `distance="geco"`), see `prabinit`.
`times` | see above.
`pdfnb` | see above.
`ignore.richness` | see above.

`summary.prabtest` produces an object of class `summary.prabtest`, which is a list with components

`rrange` | range of the simulation results (test statistic values) of `object`.
`rmean` | mean of the simulation results (test statistic values) of `object`.
`datac, p.value, pd, tuning, teststat, distance, times, pdfnb, abund, sarlambda` | directly taken from `object`, see `prabtest` and `abundtest`.
`groupinfo` | if `object$teststat="groups"`, components `rrangeg` (matrix of group-wise ranges of test statistic value), `rmeang` (vector of group-wise means of test statistic value), `rrangem` (range over simulations of overall mean of within-group dissimilarities), `rmeanm` (mean over simulations of overall mean of within-group dissimilarities) are added to the list `object$groupinfo`, and this is given out.

### Author(s)

Christian Hennig chrish@stats.ucl.ac.uk http://www.homepages.ucl.ac.uk/~ucakche

### References

Hennig, C. and Hausdorf, B. (2004) Distance-based parametric bootstrap tests for clustering of species ranges. Computational Statistics and Data Analysis 45, 875-896. http://stat.ethz.ch/Research-Reports/110.html.

Hausdorf, B. and Hennig, C. (2003) Biotic Element Analysis in Biogeography. Systematic Biology 52, 717-723.

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

### See Also

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

### Examples

    options(digits=4)
    data(kykladspecreg)
    data(nb)
    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")
    kpt <- prabtest(x, times=5, pd=0.35)
    # These settings are chosen to make the example execution
    # a bit faster; usually you will use prabtest(kprab).
    summary(kpt)

[Package prabclus version 2.2-6 Index]