prabclus: prabtest – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

prabtest

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 `-5step2` and `+5step2`. 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 christian.hennig@unibo.it https://www.unibo.it/sitoweb/christian.hennig/en

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.

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)

prabclus

Functions for Clustering and Testing of Presence-Absence, Abundance and Multilocus Genetic Data

v2.3-2

GPL

Authors

Christian Hennig <christian.hennig@unibo.it>, Bernhard Hausdorf <Hausdorf@zoologie.uni-hamburg.de>

Initial release

2020-01-06