hierDiversity: Hierarchical Group-wise Diversity Partitioning
In hierDiversity: Hierarchical Multiplicative Partitioning of Complex Phenotypes

Description Usage Arguments Details Value Note Author(s) References Examples

View source: R/hierDiversity.R

Group-wise diversity partitioning (Marion et al. in press) summarizes diversity for each group using the framework of effective or Hill numbers at each hierarchical level for any order q (Hill 1973; Jost 2006, 2007). This approach facilitates comparisons among groups at each level. Hierarchical bootstrapping is then used to approximate uncertainty around diversity estimates.

1 2	hierDiversity(dat, group, replace = NULL, reps = 99, q = 1, quant = c(0.025, 0.975), sims = FALSE)

`dat`	A matrix of community or phenotypic data where columns are individual species or traits and rows are replicates (e.g., sites, individuals, groups). Matrix elements are abundances or amounts (e.g., concentrations, counts).
`group`	A matrix with the same number of rows as in `dat`, where columns code the levels of the sampling hierarchy that DO NOT include the individual level (this is added by the function). The column groupings should—from left to right—go from least inclusive to most inclusive, with the highest level containing only one grouping; i.e., the number of groups within the hierarchy should decrease from left to right.
`replace`	A vector of logicals to indicate whether resampling is done with replacement at each level. If `NULL`, bootstrapping is automatically done for all levels.
`reps`	Numeric indicating the number of bootstrap replicates to conduct for approximating uncertainty.
`q`	Order of diversity. Default is the exponential of Shannon's entropy where q = 1.
`quant`	Numeric vector of probabilities with values in [0,1] for bootstrapped sample quantiles. Defaults to `c(0.025, 0.975)`.
`sims`	Logical to save each bootstrapped diversity estimate.

hierDiversity uses group-wise hierarchical partitioning (Marion et al. in press) to summarize community or phenotypic complexity as the 'effective number' (Hill 1973; Jost 2006, 2007) of parts within and among groups.

For each level of the hierarchial sampling design with i = 1, 2, 3, …, m levels of sampling (e.g., individuals, demes, regions, ..., continents), the total (gamma) diversity of each group within a level is multiplicatively partitioned (Whittaker 1972; Jost 2006, 2007) into two components: (1) alpha, the within-group component, is the average effective number of individual phenotypic elements within a sample; and (2) beta, the among-group component, is the effective number of completely distinct phenotypic combinations present and estimates the extent of differentiation among phenotypes (Jost 2006).

Group-wise partitioning (Marion et al. in press) uniquely differs from the level-wise partitioning approach proposed by Crist et al. (2003). Instead of a single α_{i} and β_{i} at level i, separate estimates are provided for each of the n_{i+1} groups at the next level up. This method facilitates comparisons among groups at each hierarchical level; level-wise partitioning highlights comparisons among i levels in the hierarchy.

To enable comparisons when there are unequal sample sizes among levels, this function also provides two standardized estimates of beta diversity: turnover and homogeneity (Jost 2007). Turnover is the proportional turnover rate per sample ranging from 0 (all samples are identical) to unity (all samples are completely distinct). Homogeneity is interpreted as the inverse of turnover. See Jost (2007) for a more complete mathmatical description.

To approximate uncertainty around the diversity estimates, hierarchical bootstrapping is used. In each iteration, the appropriate subgroups in a level are re-sampled, the groups within those subgroups are resampled, etc. down to the lowest level of replication.

hierDiversity returns a list of diversity estimates for each group within each hierarchical level. For each group, a dataframe is provided. The first row returns the true estimates of diversity. The second returns the standard error (standard deviation of bootstrap replicates). Subsequent rows return the quantiles specified in the quant arguement. The dataframe returns the following columns:

`alpha`	A scalar, alpha diversity, is the average effective number of parts within a group-level replicate.
`beta`	A scalar, beta diversity, is the effective number of completely distinct combinations within a group. Ranges from unity, when all group members are identical, to N when all group members are distinct.
`gamma`	A scalar, gamma diversity, is the pooled total effective number of parts overall.
`turnover`	A scalar that gives the proportional turnover among group replicates. The lower limit is 0 when all group members are identical, and the upper limit is unity when all members are distinct.
`homogeneity`	A scalar where the lower limit is 0 when all N group members are completely distinct, and the upper limit is unity when all members are identical.

If sims=TRUE, a separate dataframe is provided for each group returning the saved bootstrapped diversity replicates for each iteration of rep.

If groupings among levels are not unique (i.e., group "A" appears in both level 1 and level 2), only the diversity estimates from the lowest (least inclusive) should be interpreted. For higher levels, alpha will equal gamma, beta diversity will be one, and there will be no error due to the hierarchical nature of the sampling.

Zachary Marion zmarion@vols.utk.edu, James Fordyce jfordyce@utk.edu, and Benjamin Fitzpatrick benfitz@utk.edu

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

Fordyce, J.A. and S.B. Malcolm (2000). Specialist weevil, Rhyssomatus lineaticollis, does not spatially avoid cardenolide defenses of common milkweed by ovipositing into pith tissue. J. Chem. Ecol.. 26(12): 2857–2874.

Hill, M.O. (1973). Diversity and evenness: a unifying notation and its consequences. Ecology, 54(2): 427–432.

Jost, L. (2006). Entropy and diversity. Oikos, 113(2): 363–375.

Jost, L. (2007). Partitioning diversity into independent alpha and beta components. Ecology, 88(10): 2427–2439.

Marion, Z.H., J.A. Fordyce, and B.M. Fitzpatrick. Extending the concept of diversity partitioning to characterize complex phenotypes. Am. Nat.. in press.

Whittaker R.H. (1972.) Evolution and measurement of species diversity. Taxon, 21, 213–251.

## NOTE: 'reps' argument usually needs to be >= 99.
## The lower values used here are for demonstration.

set.seed(2)
## Create Data Matrix
dat <- matrix(rpois(1000, 3), nrow=100)
#Create Grouping Matrix
group <- as.matrix(data.frame(
  L1 = rep(c("A","B","C","D","E"), each=20),
  L2 = rep(c("AB", "CDE"), times=c(40,60)),
  L3 = rep("total",100)))

hierDiversity(dat, group, reps=9)
replace <- c(FALSE, rep(TRUE, 3))
hierDiversity(dat, group, replace=replace, reps=9, q=2)
div <- hierDiversity(dat, group, reps=9, q=2, 
  quant=c(0.25, 0.75), sims=TRUE)
div$L2$CDE


##### Example data from Fordyce & Malcolm (2000) 
data(milkweedData)
data(milkweedVars)
milkDat <- as.matrix(milkweedData)
milkVars <- as.matrix(milkweedVars)

milkDiv <- hierDiversity(milkDat, milkVars, reps=5, q=3, 
  sims=TRUE)
milkDiv$infectstatus
turnover <- c(milkDiv$infectstatus$I[[2]][,5],
  milkDiv$infectstatus$U[[2]][,5])
infectionStatus <- rep(c("infected","uninfected"), each=6)
boxplot(turnover~infectionStatus, las = 1, 
  ylab = "Turnover", xlab = "Infection Status")