abundtest {prabclus}

Parametric bootstrap test for clustering in abundance matrices

Description

Parametric bootstrap test of a null model of i.i.d., but spatially autocorrelated species against clustering of the species' population patterns. Note that most relevant functionality of prabtest (except of the use of the geco distance) is also included in abundtest, so that abundtest can also be used on binary presence-absence data. 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/abundmatrixfile", neighborhood="path/neighborhoodfile")
test <- abundtest(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

abundtest(prabobj, teststat = "distratio", tuning = 0.25,
                       times = 1000, p.nb = NULL, 
                       prange = c(0, 1), nperp = 4, step = 0.1, step2 = 0.01, 
                       twostep = TRUE, species.fixed=TRUE, prab01=NULL,
                       groupvector=NULL,
                       sarestimate=prab.sarestimate(prabobj),
                       dist = prabobj$distance,
                       n.species = prabobj$n.species)

Arguments

prabobj

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, and treats abundance matrices as presence-absence-data). "mean": mean of the distances between species (this is a rough measure of species co-occurrence). "groups": this requires a specification of a vector defining different groups of species via parameter groupvector. The test statistic is then the mean of the distances between species of the same group. This is computed over all species, but also for every single group of species. It also includes the "mean"-test, so that the number of tests carried out is number of species groups with more than one element plus two.

tuning

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

times

integer. Number of simulation runs.

p.nb

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 NULL (the default), and prabobj$spatial, prabtest estimates this by function autoconst. Otherwise the next five parameters have no effect. If NULL, and !prabobj$spatial, spatial structure is ignored.

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.

species.fixed

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) for presence-absence data. See function randpop.nb. Use always TRUE for abundance data (not necessary if teststat="inclusions").

prab01

prabinit-object based on presence-absence matrix of same dimensions than the abundance matrix of prabobj. This specifies the presences and absences on which the presence/absence step of abundance-based tests is based (see details). If NULL (which is usually the only reasonable choice), prab01 is computed in order to indicate the nonzeroes of prabobj$prab.

groupvector

integer vector. For every species, a number indicating the species' group membership. Needed only if teststat="groups".

sarestimate

Estimator of the parameters of a simultaneous autoregression model corresponding to the null model for abundance data from Hausdorf and Hennig (2007) as generated by prab.sarestimate. This requires package spdep. Note that by explicitly specifying sarestimate=NULL simulation of 0-1 matrices can be enforced.

dist

One of "jaccard", "kulczynski", "qkulczynski" or "logkulczynski" specifying the distance measure on which the test is based. By default, this is taken from prabobj.

n.species

number of species. By default this is taken from prabobj. This should normally not be changed.

Details

For presence-absence data, the routine is described in prabtest. For abundance data, the first step under the null model is to simulated presence-absence patterns as in prabtest. The second step is to fit a simultaneous autoregression (SAR) model (Ripley 1981, section 5.2) to the log-abundances, see prab.sarestimate. The simulation from the null model is implemented in regpop.sar. For more details see Hennig and Hausdorf (2004) for presence-absence data and Hausdorf and Hennig (2007) for abundance data and the test statistics "mean" and "groups", which can also be applied to binary data.

If p.nb=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

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

results

vector of test statistic values for all simulated populations. For teststat="groups" a list with components overall (means of within group-distances), mean (means of all distances), gr (matrix with a row for every group, giving the groupwise within-group distance means).

p.above

p-value against an alternative that generates large values of the test statistic (usually reasonable for teststat="inclusions", "groups", "mean").

p.below

p-value against an alternative that generates small values of the test statistic (usually reasonable for "lcomponent", "nn", "distratio"; for "isovertice", the two-sided p may make sense which is twice the smaller one of p.above and p.below).

datac

test statistic value for the original data. (specgroups-output for teststat="groups").

tuning

see above.

distance

dist above.

teststat

see above.

pd

p.nb above.

abund

TRUE if simultaneous autoregression has been used (i.e., a sarestimate has been supplied or computed).

sarlambda

Estimator of the autocorrelation parameter lambda (see errorsarlm) defined so that the average weight of neighbors (see nb2listw) is standardized to 1.

sarestimate

the output object of prab.sarestimate.

groupinfo

list containing information from "groups" tests, with components lg (levels of groupvector), ng (number of groups), nsg (vector of group sizes), testm (value of "means" test statistic for input prabobj), pa (group-wise p.above), pb (group-wise p.below), pma (p.above of "means" test), pmb (p.below of "means" test).

Author(s)

Christian Hennig [e-mail] https://www.unibo.it/sitoweb/christian.hennig/en

References

Hausdorf, B. and Hennig, C. (2007) Null model tests of clustering of species, negative co-occurrence patterns and nestedness in meta-communities. Oikos 116, 818-828.

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.

Ripley, B. D. (1981) Spatial Statistics. Wiley.

See Also

prabinit generates objects of class prab.

autoconst estimates pd from such objects.

prabtest (analogous function for presence-absence data).

regpop.sar generates populations from the null model.

prab.sarestimate (parameter estimators for simultaneous autoregression model). This calls

errorsarlm (original estimation function from package spdep).

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

Summary and print methods: summary.prabtest.

Examples

# Note: NOT RUN.
# This needs package spdep and a bunch of packages that are
# called by spdep!
# data(siskiyou)
# set.seed(1234)
# x <- prabinit(prabmatrix=siskiyou, neighborhood=siskiyou.nb,
#              distance="logkulczynski")
# a1 <- abundtest(x, times=5, p.nb=0.0465)
# a2 <- abundtest(x, times=5, p.nb=0.0465, teststat="groups",
#                 groupvector=siskiyou.groups)
# These settings are chosen to make the example execution
# faster; usually you will use abundtest(x).
# summary(a1)
# summary(a2)