# adipart: Additive Diversity Partitioning and Hierarchical Null Model... In vegan: Community Ecology Package

## Description

In additive diversity partitioning, mean values of alpha diversity at lower levels of a sampling hierarchy are compared to the total diversity in the entire data set (gamma diversity). In hierarchical null model testing, a statistic returned by a function is evaluated according to a nested hierarchical sampling design (`hiersimu`).

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15``` ```adipart(...) ## Default S3 method: adipart(y, x, index=c("richness", "shannon", "simpson"), weights=c("unif", "prop"), relative = FALSE, nsimul=99, ...) ## S3 method for class 'formula' adipart(formula, data, index=c("richness", "shannon", "simpson"), weights=c("unif", "prop"), relative = FALSE, nsimul=99, ...) hiersimu(...) ## Default S3 method: hiersimu(y, x, FUN, location = c("mean", "median"), relative = FALSE, drop.highest = FALSE, nsimul=99, ...) ## S3 method for class 'formula' hiersimu(formula, data, FUN, location = c("mean", "median"), relative = FALSE, drop.highest = FALSE, nsimul=99, ...) ```

## Arguments

 `y` A community matrix. `x` A matrix with same number of rows as in `y`, columns coding the levels of sampling hierarchy. The number of groups within the hierarchy must decrease from left to right. If `x` is missing, function performs an overall decomposition into alpha, beta and gamma diversities. `formula` A two sided model formula in the form `y ~ x`, where `y` is the community data matrix with samples as rows and species as column. Right hand side (`x`) must be grouping variables referring to levels of sampling hierarchy, terms from right to left will be treated as nested (first column is the lowest, last is the highest level, at least two levels specified). Interaction terms are not allowed. `data` A data frame where to look for variables defined in the right hand side of `formula`. If missing, variables are looked in the global environment. `index` Character, the diversity index to be calculated (see Details). `weights` Character, `"unif"` for uniform weights, `"prop"` for weighting proportional to sample abundances to use in weighted averaging of individual alpha values within strata of a given level of the sampling hierarchy. `relative` Logical, if `TRUE` then alpha and beta diversity values are given relative to the value of gamma for function `adipart`. `nsimul` Number of permutations to use if `matr` is not of class 'permat'. If `nsimul = 0`, only the `FUN` argument is evaluated. It is thus possible to reuse the statistic values without using a null model. `FUN` A function to be used by `hiersimu`. This must be fully specified, because currently other arguments cannot be passed to this function via `...`. `location` Character, identifies which function (mean or median) is to be used to calculate location of the samples. `drop.highest` Logical, to drop the highest level or not. When `FUN` evaluates only arrays with at least 2 dimensions, highest level should be dropped, or not selected at all. `...` Other arguments passed to functions, e.g. base of logarithm for Shannon diversity, or `method`, `thin` or `burnin` arguments for `oecosimu`.

## Details

Additive diversity partitioning means that mean alpha and beta diversities add up to gamma diversity, thus beta diversity is measured in the same dimensions as alpha and gamma (Lande 1996). This additive procedure is then extended across multiple scales in a hierarchical sampling design with i = 1, 2, 3, …, m levels of sampling (Crist et al. 2003). Samples in lower hierarchical levels are nested within higher level units, thus from i=1 to i=m grain size is increasing under constant survey extent. At each level i, α_i denotes average diversity found within samples.

At the highest sampling level, the diversity components are calculated as

beta_m = gamma - alpha_m

For each lower sampling level as

beta_i = alpha_(i+1) - alpha_i

Then, the additive partition of diversity is

gamma = alpha_1 + sum(beta_i)

Average alpha components can be weighted uniformly (`weight="unif"`) to calculate it as simple average, or proportionally to sample abundances (`weight="prop"`) to calculate it as weighted average as follows

alpha_i = sum(D_ij*w_ij)

where D_{ij} is the diversity index and w_{ij} is the weight calculated for the jth sample at the ith sampling level.

The implementation of additive diversity partitioning in `adipart` follows Crist et al. 2003. It is based on species richness (S, not S-1), Shannon's and Simpson's diversity indices stated as the `index` argument.

The expected diversity components are calculated `nsimul` times by individual based randomisation of the community data matrix. This is done by the `"r2dtable"` method in `oecosimu` by default.

`hiersimu` works almost in the same way as `adipart`, but without comparing the actual statistic values returned by `FUN` to the highest possible value (cf. gamma diversity). This is so, because in most of the cases, it is difficult to ensure additive properties of the mean statistic values along the hierarchy.

## Value

An object of class `"adipart"` or `"hiersimu"` with same structure as `oecosimu` objects.

## Author(s)

Péter Sólymos, [email protected]

## References

Crist, T.O., Veech, J.A., Gering, J.C. and Summerville, K.S. (2003). Partitioning species diversity across landscapes and regions: a hierarchical analysis of α, β, and γ-diversity. Am. Nat., 162, 734–743.

Lande, R. (1996). Statistics and partitioning of species diversity, and similarity among multiple communities. Oikos, 76, 5–13.

See `oecosimu` for permutation settings and calculating p-values. `multipart` for multiplicative diversity partitioning.

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34``` ```## NOTE: 'nsimul' argument usually needs to be >= 99 ## here much lower value is used for demonstration data(mite) data(mite.xy) data(mite.env) ## Function to get equal area partitions of the mite data cutter <- function (x, cut = seq(0, 10, by = 2.5)) { out <- rep(1, length(x)) for (i in 2:(length(cut) - 1)) out[which(x > cut[i] & x <= cut[(i + 1)])] <- i return(out)} ## The hierarchy of sample aggregation levsm <- with(mite.xy, data.frame( l1=1:nrow(mite), l2=cutter(y, cut = seq(0, 10, by = 2.5)), l3=cutter(y, cut = seq(0, 10, by = 5)), l4=cutter(y, cut = seq(0, 10, by = 10)))) ## Let's see in a map par(mfrow=c(1,3)) plot(mite.xy, main="l1", col=as.numeric(levsm\$l1)+1, asp = 1) plot(mite.xy, main="l2", col=as.numeric(levsm\$l2)+1, asp = 1) plot(mite.xy, main="l3", col=as.numeric(levsm\$l3)+1, asp = 1) par(mfrow=c(1,1)) ## Additive diversity partitioning adipart(mite, index="richness", nsimul=19) adipart(mite ~ ., levsm, index="richness", nsimul=19) ## Hierarchical null model testing ## diversity analysis (similar to adipart) hiersimu(mite, FUN=diversity, relative=TRUE, nsimul=19) hiersimu(mite ~., levsm, FUN=diversity, relative=TRUE, nsimul=19) ## Hierarchical testing with the Morisita index morfun <- function(x) dispindmorisita(x)\$imst hiersimu(mite ~., levsm, morfun, drop.highest=TRUE, nsimul=19) ```

### Example output

```Loading required package: permute
This is vegan 2.4-4

Call: adipart(y = mite, index = "richness", nsimul = 19)

nullmodel method 'r2dtable' with 19 simulations
options:  index richness, weights unif
alternative hypothesis: statistic is less or greater than simulated values

statistic     SES   mean   2.5%    50%  97.5% Pr(sim.)
alpha.1    15.114 -43.353 22.316 22.044 22.300 22.603     0.05 *
gamma      35.000   0.000 35.000 35.000 35.000 35.000     1.00
beta.1     19.886  43.353 12.684 12.397 12.700 12.956     0.05 *
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

Call: adipart(formula = mite ~ ., data = levsm, index = "richness",
nsimul = 19)

nullmodel method 'r2dtable' with 19 simulations
options:  index richness, weights unif
alternative hypothesis: statistic is less or greater than simulated values

statistic      SES     mean     2.5%      50%   97.5% Pr(sim.)
alpha.1    15.114 -41.7895 22.33383 21.98786 22.35714 22.5629     0.05 *
alpha.2    29.750 -22.9498 34.82895 34.36250 35.00000 35.0000     0.05 *
alpha.3    33.000   0.0000 35.00000 35.00000 35.00000 35.0000     0.05 *
gamma      35.000   0.0000 35.00000 35.00000 35.00000 35.0000     1.00
beta.1     14.636   7.4536 12.49511 11.90250 12.51429 12.9186     0.05 *
beta.2      3.250  13.9126  0.17105  0.00000  0.00000  0.6375     0.05 *
beta.3      2.000   0.0000  0.00000  0.00000  0.00000  0.0000     0.05 *
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
hiersimu object

Call: hiersimu(y = mite, FUN = diversity, relative = TRUE, nsimul = 19)

nullmodel method 'r2dtable' with 19 simulations

alternative hypothesis: statistic is less or greater than simulated values

statistic     SES    mean    2.5%     50% 97.5% Pr(sim.)
level_1   0.76064 -60.388 0.93935 0.93477 0.93962 0.945     0.05 *
leve_2    1.00000   0.000 1.00000 1.00000 1.00000 1.000     1.00
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
hiersimu object

Call: hiersimu(formula = mite ~ ., data = levsm, FUN = diversity,
relative = TRUE, nsimul = 19)

nullmodel method 'r2dtable' with 19 simulations

alternative hypothesis: statistic is less or greater than simulated values

statistic      SES    mean    2.5%     50%  97.5% Pr(sim.)
l1   0.76064  -72.186 0.93833 0.93520 0.93754 0.9423     0.05 *
l2   0.89736 -133.460 0.99807 0.99691 0.99801 0.9995     0.05 *
l3   0.92791 -492.633 0.99936 0.99909 0.99938 0.9996     0.05 *
l4   1.00000    0.000 1.00000 1.00000 1.00000 1.0000     1.00
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
hiersimu object

Call: hiersimu(formula = mite ~ ., data = levsm, FUN = morfun,
drop.highest = TRUE, nsimul = 19)

nullmodel method 'r2dtable' with 19 simulations

alternative hypothesis: statistic is less or greater than simulated values

statistic     SES     mean     2.5%      50%   97.5% Pr(sim.)
l1   0.52070  5.8049  0.35934  0.31216  0.36452  0.4048     0.05 *
l2   0.60234 13.9170  0.15898  0.10812  0.15947  0.2111     0.05 *
l3   0.67509 21.8738 -0.18455 -0.27930 -0.17545 -0.1364     0.05 *
---
Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
```

vegan documentation built on May 31, 2017, 4:08 a.m.