R: Parametric bootstrap test for clustering in abundance...

abundtest {prabclus} | R Documentation

## 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 `tuning`th 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 chrish@stats.ucl.ac.uk http://www.homepages.ucl.ac.uk/~ucakche

### 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)

[Package prabclus version 2.2-6 Index]