prabtest {prabclus}

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 tuningth 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 [e-mail] 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.

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)