Type: Package
Title: Diversity Through Hill Numbers
Version: 0.5.2
Date: 2023-08-19
Author: Daijiang Li
Maintainer: Daijiang Li <daijianglee@gmail.com>
Description: Calculate taxonomic, functional and phylogenetic diversity measures through Hill Numbers proposed by Chao, Chiu and Jost (2014) <doi:10.1146/annurev-ecolsys-120213-091540>.
License: MIT + file LICENSE
Depends: R (≥ 3.1)
Imports: FD, plyr, ade4, ape, tibble, geiger
RoxygenNote: 7.2.3
Suggests: testthat, covr, betapart
URL: https://github.com/daijiang/hillR
BugReports: https://github.com/daijiang/hillR/issues
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2023-08-19 22:40:32 UTC; dli
Repository: CRAN
Date/Publication: 2023-08-19 23:02:32 UTC

hillR: Diversity Through Hill Numbers

Description

The R package 'hillR' implements the framework proposed by Chao, et al. 2014 and makes it easy to calculate taxonomic, functional, and phylogenetic diversity of ecological communities as Hill numbers. For each facet of diversity, 'hillR' has three functions. The first set of functions (hill_taxa, hill_func, and hill_phylo) calculates alpha diversity of each site. The second set of functions (hill_taxa_parti, hill_func_parti, and hill_phylo_parti) calculates diversity across all sites. The third set of functions (hill_taxa_parti_pairwise, hill_func_parti_pairwise, and hill_phylo_parti_pairwise) calculates all possible pairwise diversity across all sites. Users can set the argument _q_ to control the weight of species abundance.

Details

Users may be interested in other similar packages such as vegetarian and iNEXT.

Taxonomic Hill Numbers

hill_taxa, hill_taxa_parti, hill_taxa_parti_pairwise

Functional Hill Numbers

hill_func, hill_func_parti, hill_func_parti_pairwise

Phylogenetic Hill Numbers

hill_phylo, hill_phylo_parti, hill_phylo_parti_pairwise

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Functional diversity through Hill Numbers

Description

Calculate functional diversity for each site (alpha diversity).

Usage

hill_func(
  comm,
  traits,
  traits_as_is = FALSE,
  q = 0,
  base = exp(1),
  check_data = TRUE,
  div_by_sp = FALSE,
  ord = c("podani", "metric"),
  fdis = TRUE,
  stand_dij = FALSE
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

traits

A data frame of species functional traits data. Species as rows, traits as columns. It can include both continuous and categorical data. It will be transformed into a distance matrix using 'FD::gowdis(traits)'. If all traits are numeric, then it will use Euclidean distance.

traits_as_is

if FALSE (default) traits data frame will be transformed into a distance matrix. Otherwise, will use as is (i.e. traits is a symmetric distance matrix).

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

base

default is exp(1), the base of log.

check_data

whether to check data first? Default is TRUE.

div_by_sp

as FD calculated in this way will be highly correlated with taxonomic diversity, one potential simple way to correct this is to divide the results by the number of species. However, a more common way to deal with correlations is to use null models and calculate standardized effect sizes. Therefore, I set the default to be FALSE.

ord

ord in FD::gowdis.

fdis

whether to calculate FDis, default is TRUE

stand_dij

whether to standardize distance matrix to have max value of 1? Default is FALSE.

Value

A matrix, with these information for each site: Q (Rao's Q); D_q (functional hill number, the effective number of equally abundant and functionally equally distinct species); MD_q (mean functional diversity per species, the effective sum of pairwise distances between a fixed species and all other species); FD_q (total functional diversity, the effective total functional distance between species of the assemblage). See Chiu and Chao 2014 page 4 for more information.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Chiu, Chun-Huo, and Anne Chao. Distance-Based Functional Diversity Measures and Their Decomposition: A Framework Based on Hill Numbers. PLoS ONE 9, no. 7 (July 7, 2014): e100014. <doi:10.1371/journal.pone.0100014>.

Examples

dummy = FD::dummy
hill_func(comm = dummy$abun, traits = dummy$trait, q = 0)
hill_func(comm = dummy$abun, traits = dummy$trait, q = 1)
hill_func(comm = dummy$abun, traits = dummy$trait, q = 0.9999)
hill_func(comm = dummy$abun, traits = dummy$trait, q = 2)
hill_func(comm = dummy$abun, traits = dummy$trait, q = 3)

Decompostion of functional diversity through Hill Numbers

Description

Calculate functional gamma, alpha, and beta diversity for all communities, as well as site similarity. These values are based on ALL communities.

Usage

hill_func_parti(
  comm,
  traits,
  traits_as_is = FALSE,
  q = 0,
  base = exp(1),
  check_data = TRUE,
  rel_then_pool = TRUE,
  ord = c("podani", "metric"),
  stand_dij = FALSE,
  show_warning = TRUE
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

traits

A data frame of species functional traits data. Species as rows, traits as columns. It can include both continuous and categorical data. It will be transformed into a distance matrix using 'FD::gowdis(traits)'. If all traits are numeric, then it will use Euclidean distance.

traits_as_is

if FALSE (default) traits data frame will be transformed into a distance matrix. Otherwise, will use as is (i.e. traits is a symmetric distance matrix).

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

base

default is exp(1), the base of log.

check_data

whether to check data first? Default is TRUE.

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

ord

ord in FD::gowdis.

stand_dij

whether to standardize distance matrix to have max value of 1? Default is FALSE.

show_warning

whether to print warning, default is TRUE.

Value

a data frame with one row (across all sites), including these columns: q, RaoQ of pooled assemblage, gamma diversity, alpha diversity, beta diversity, local species overlap (similar to Sorensen), and region species overlap (similar to Jaccard). See Chiu and Chao 2014 Table 3 for more information.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Chiu, Chun-Huo, and Anne Chao. Distance-Based Functional Diversity Measures and Their Decomposition: A Framework Based on Hill Numbers. PLoS ONE 9, no. 7 (July 7, 2014): e100014. <doi:10.1371/journal.pone.0100014>.

See Also

hill_taxa_parti, hill_func

Examples

dummy = FD::dummy
hill_func_parti(comm = dummy$abun, traits = dummy$trait, q = 0)
hill_func_parti(comm = dummy$abun, traits = dummy$trait, q = 1)
hill_func_parti(comm = dummy$abun, traits = dummy$trait, q = 0.9999)
hill_func_parti(comm = dummy$abun, traits = dummy$trait, q = 2)
hill_func_parti(comm = dummy$abun, traits = dummy$trait, q = 3)

Pairwise comparisons for all sites.

Description

Calculate pairwise functional gamma, alpha, and beta diversity for communities, as well as site similarity. It is based on hill_func_parti. If comm has >2 sites, this function will give results for all pairwise comparisons.

Usage

hill_func_parti_pairwise(
  comm,
  traits,
  traits_as_is = FALSE,
  q = 0,
  rel_then_pool = TRUE,
  output = c("data.frame", "matrix"),
  pairs = c("unique", "full"),
  .progress = TRUE,
  show_warning = TRUE,
  ...
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

traits

A data frame of species functional traits data. Species as rows, traits as columns. It can include both continuous and categorical data. It will be transformed into a distance matrix using 'FD::gowdis(traits)'. If all traits are numeric, then it will use Euclidean distance.

traits_as_is

if FALSE (default) traits data frame will be transformed into a distance matrix. Otherwise, will use as is (i.e. traits is a symmetric distance matrix).

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

output

output type: data.frame (default) or matrix. If matrix, then this function will return a list of matrices.

pairs

full or unique (default). Do you want to compare all possible pairs (i.e. n^2) or just unique pairs (i.e. choose(n, 2))?

.progress

Whether to show progress bar. Default is 'TRUE'.

show_warning

whether to print warning, default is TRUE.

...

additional arguments for hill_func_parti.

Value

a data frame with results for all pairwise comparisons.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Chiu, Chun-Huo, and Anne Chao. Distance-Based Functional Diversity Measures and Their Decomposition: A Framework Based on Hill Numbers. PLoS ONE 9, no. 7 (July 7, 2014): e100014. <doi:10.1371/journal.pone.0100014>.

See Also

hill_func_parti

Examples

## Not run: 
dummy = FD::dummy
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 0)
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 0,
                         output = 'matrix')
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 0,
                         output = 'matrix', pairs = 'full')
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 1)
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 0.9999)
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 2)
hill_func_parti_pairwise(comm = dummy$abun, traits = dummy$trait, q = 3)

## End(Not run)

Phylogenetic diversity through Hill Numbers

Description

Calculate alpha phylogenetic diversity based on Hill numbers

Usage

hill_phylo(
  comm,
  tree,
  q = 0,
  base = exp(1),
  rel_then_pool = TRUE,
  show_warning = TRUE,
  return_dt = FALSE
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

tree

A phylogeny with class 'phylo'.

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

base

default is exp(1), the base of log.

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

show_warning

whether to print warning, default is TRUE.

return_dt

Whether to return the Phylogenetic Hill numbers Dt, default is 'FALSE'.

Value

A vector of hill number based phylogenetic diversity ('PD(T)', effective total branch length) for all sites.

Author(s)

Chiu & Chao & Daijiang Li

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Examples

comm = dummy = FD::dummy$abun
tree = ape::rtree(n = ncol(comm), tip.label = paste0('sp', 1:8))
hill_phylo(comm, tree, q = 0)
hill_phylo(comm, tree, q = 0.999)
hill_phylo(comm, tree, q = 1)
hill_phylo(comm, tree, q = 2)

Phylogenetic diversity of multiple sites

Description

Calculate overall phylogenetic diversity and site similarity across multiple sites.

Usage

hill_phylo_parti(
  comm,
  tree,
  q = 0,
  base = exp(1),
  rel_then_pool = TRUE,
  show_warning = TRUE,
  check_data = TRUE
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

tree

A phylogeny with class 'phylo'.

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

base

default is exp(1), the base of log.

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

show_warning

whether to print warning, default is TRUE.

check_data

Whether to check the community data and phylogeny. Default is 'TRUE'. Can be set to 'FALSE' to speed up 'hill_phylo_parti_pairwise()'.

Value

A data frame with one row (across all sites) and six columns: q, gamma diversity, alpha diversity, beta diversity, local similarity (similar to Sorensen), and region similarity (similar to Jaccard).

Author(s)

Chiu & Chao, Daijiang Li

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Examples

comm = dummy = FD::dummy$abun
tree = ape::rtree(n = ncol(comm), tip.label = paste0('sp', 1:8))
hill_phylo_parti(comm, tree, q = 0)
hill_phylo_parti(comm, tree, q = 0.999)
hill_phylo_parti(comm, tree, q = 1)
hill_phylo_parti(comm, tree, q = 2)

Pairwise phylogenetic diversity through Hill numbers

Description

Calculate pairwise phylogenetic diversity.

Usage

hill_phylo_parti_pairwise(
  comm,
  tree,
  q = 0,
  output = c("data.frame", "matrix"),
  pairs = c("unique", "full"),
  rel_then_pool = TRUE,
  .progress = TRUE,
  show_warning = TRUE,
  ...
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

tree

A phylogeny with class 'phylo'.

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

output

output type: data.frame (default) or matrix. If matrix, then this function will return a list of matrices.

pairs

full or unique (default). Do you want to compare all possible pairs (i.e. n^2) or just unique pairs (i.e. choose(n, 2))?

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

.progress

Whether to show progress bar. Default is 'TRUE'.

show_warning

whether to print warning, default is TRUE.

...

additional arguments for hill_func_parti.

Value

A data frame or a matrix with results for all pairwise comparisons.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

See Also

hill_phylo_parti

Examples

## Not run: 
comm = dummy = FD::dummy$abun
tree = ape::rtree(n = ncol(comm), tip.label = paste0('sp', 1:8))
hill_phylo_parti_pairwise(comm, tree, q = 0, show_warning = FALSE)
hill_phylo_parti_pairwise(comm, tree, q = 0.999, show_warning = FALSE)
hill_phylo_parti_pairwise(comm, tree, q = 1, show_warning = FALSE)
hill_phylo_parti_pairwise(comm, tree, q = 2, show_warning = FALSE)

## End(Not run)

Taxonomic diversity through Hill Numbers

Description

Calculate taxonomic diversity for each site (alpha diversity).

Usage

hill_taxa(comm, q = 0, MARGIN = 1, base = exp(1))

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

MARGIN

default is 1, if sites are columns, set MARGIN to 2.

base

default is exp(1), the base of log.

Value

A named vector, diversity values for each site in the comm.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Jost, Lou. Entropy and diversity. Oikos 113, no. 2 (2006): 363-375. <doi:10.1111/j.2006.0030-1299.14714.x>.

Examples

dummy = FD::dummy
hill_taxa(comm = dummy$abun, q = 0)
# same as: vegan::specnumber(dummy$abun)
hill_taxa(comm = dummy$abun, q = 0.999)
hill_taxa(comm = dummy$abun, q = 1)
# same as: exp(vegan::diversity(x = dummy$abun, index = 'shannon'))
hill_taxa(comm = dummy$abun, q = 2)
# same as: vegan::diversity(x = dummy$abun, index = 'invsimpson')

Decompostion of Taxonomic diversity through Hill Numbers

Description

Calculate taxonomic gamma, alpha, and beta diversity across all communities, as well as site similarity. If comm has 2 sites, this function gives pair comparison. If comm has >2 sites, gamma diversity is the diversity of the pooled assemblage, alpha is the average diversity across all site, beta is across all communities.

Usage

hill_taxa_parti(
  comm,
  q = 0,
  base = exp(1),
  rel_then_pool = TRUE,
  show_warning = TRUE,
  check_data = TRUE
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

base

default is exp(1), the base of log.

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

show_warning

whether to print warning, default is TRUE.

check_data

whether to check data first? Default is TRUE.

Value

A data frame with one row (across all sites), including these columns: q, gamma diversity, alpha diversity, beta diversity, MacArthur's homogeneity measure, local similarity (species overlap, similar to Sorensen), and region similarity (species overlap, similar to Jaccard). See Chao, Chiu and Jost 2014 Table 2 for more information.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Jost, Lou. Entropy and diversity. Oikos 113, no. 2 (2006): 363-375. <doi:10.1111/j.2006.0030-1299.14714.x>.

See Also

hill_taxa

Examples

dummy = FD::dummy
hill_taxa_parti(comm = dummy$abun, q = 0)
hill_taxa_parti(comm = dummy$abun, q = 1)
hill_taxa_parti(comm = dummy$abun, q = 0.9999999)
hill_taxa_parti(comm = dummy$abun, q = 0.9999999, rel_then_pool = FALSE)
hill_taxa_parti(comm = dummy$abun, q = 1, rel_then_pool = FALSE)
hill_taxa_parti(comm = dummy$abun, q = 2)
hill_taxa_parti(comm = dummy$abun, q = 3)

Pairwise comparisons for all sites

Description

Calculate pairwise taxonomic gamma, alpha, and beta diversity for communities, as well as site similarity. It is based on hill_taxa_parti. If comm has >2 sites, this function will give results for all pairwise comparisons.

Usage

hill_taxa_parti_pairwise(
  comm,
  q = 0,
  rel_then_pool = TRUE,
  output = c("data.frame", "matrix"),
  pairs = c("unique", "full"),
  .progress = TRUE,
  show_warning = TRUE,
  ...
)

Arguments

comm

A data frame of vegetation data. Sites as rows, species as columns.

q

Hill number, q = 0 (default) to get species richness, q = 1 to get shannon entropy, q = 2 will give inverse Simpson.

rel_then_pool

default is TRUE. Abundance of species are first changed to relative abundance within sites, then pooled into one assemblage. If FALSE, sites are pooled first, then change abundance of species to relative abundance.

output

output type: data.frame (default) or matrix. If matrix, then this function will return a list of matrices.

pairs

full or unique (default). Do you want to compare all possible pairs (i.e. n^2) or just unique pairs (i.e. choose(n, 2))?

.progress

Whether to show progress bar. Default is 'TRUE'.

show_warning

whether to print warning, default is TRUE.

...

other arguments in hill_taxa_parti().

Value

A data frame with results for all pairwise comparisons.

References

Chao, Anne, Chun-Huo Chiu, and Lou Jost. Unifying Species Diversity, Phylogenetic Diversity, Functional Diversity, and Related Similarity and Differentiation Measures Through Hill Numbers. Annual Review of Ecology, Evolution, and Systematics 45, no. 1 (2014): 297–324. <doi:10.1146/annurev-ecolsys-120213-091540>.

Jost, Lou. Entropy and diversity. Oikos 113, no. 2 (2006): 363-375. <doi:10.1111/j.2006.0030-1299.14714.x>.

See Also

hill_taxa_parti

Examples

## Not run: 
dummy = FD::dummy
hill_taxa_parti_pairwise(comm = dummy$abun, q = 0)
hill_taxa_parti_pairwise(comm = dummy$abun, q = 0, output = 'matrix')
hill_taxa_parti_pairwise(comm = dummy$abun, q = 1)
hill_taxa_parti_pairwise(comm = dummy$abun, q = 0.9999999)
hill_taxa_parti_pairwise(comm = dummy$abun, q = 0.9999999, rel_then_pool = FALSE)
hill_taxa_parti_pairwise(comm = dummy$abun, q = 1, rel_then_pool = FALSE)
hill_taxa_parti_pairwise(comm = dummy$abun, q = 2)
hill_taxa_parti_pairwise(comm = dummy$abun, q = 3)

## End(Not run)

mirror server hosted at Truenetwork, Russian Federation.