hilldiv3 measures and compares the diversity of
biological communities — OTU, ASV or MAG count tables — using
Hill numbers. Hill numbers are a single, intuitive
family of diversity metrics: each one is an effective number of
taxa (“how many equally-abundant taxa would give this much
diversity”), and one parameter, the diversity order
q, slides smoothly between counting all taxa equally
(richness), weighting them by abundance (Shannon) and focusing on the
common ones (Simpson). Because everything is expressed in the same
currency, results are directly comparable across samples, studies and
methods.
From that one foundation, hilldiv3 provides a unified
toolkit for neutral diversity (abundances only),
phylogenetic diversity (accounting for how related taxa
are) and functional diversity (accounting for how
different their traits are), covering measurement, partitioning,
(dis)similarity, profiles, evenness and redundancy. You call the same
functions for all three — the diversity type is chosen by whether you
supply a tree or a distance matrix.
hilldiv3 is aimed at ecologists and microbiologists
analysing DNA-based community data (metabarcoding, amplicon and shotgun
metagenomics), and more generally anyone who needs comparable alpha,
beta and gamma diversity across taxonomic, phylogenetic and functional
dimensions — including nested multi-scale designs such as individuals
within sites within regions.
Install the released version from CRAN:
install.packages("hilldiv3")To install the version in this repository, which may contain changes not yet available on CRAN:
# install.packages("devtools")
devtools::install_github("alberdilab/hilldiv3")library(hilldiv3)
# Bundled simulated gut-microbiome MAG data.
hilldiv(gut_counts) # neutral Hill numbers q = 0, 1, 2
hilldiv(gut_counts, tree = gut_tree) # neutral + phylogenetic
dist <- traits2dist(gut_traits)
hilldiv(gut_counts, dist = dist) # neutral + functional
hilldiv(gut_counts, tree = gut_tree, dist = dist) # all three types at once
# Attribute Hill power-sum weight to a MAG and a set of MAGs.
sets <- list(C = rownames(gut_counts)[3],
ABC = rownames(gut_counts)[1:3])
hillshare(gut_counts, q = c(0, 1, 2), tree = gut_tree, sets = sets)
hillshare(gut_counts, q = c(0, 1, 2), dist = dist, sets = sets)
# Core diversity results are tidy by default and plot directly.
plot(hillprof(gut_counts)) # diversity profile
hilldiv(gut_counts, out = "matrix") # matrix: samples x q ordersFull documentation lives on the package website: https://alberdilab.github.io/hilldiv3/
vignette("hilldiv3"), a
gentle introduction for anyone using Hill numbers for the first
time.If you have used hilldiv2, v3 is a
full redesign that keeps the familiar function names
(hilldiv(), hillpart(),
hilldiss(), hillsim(),
hillpair(), hillred(), tss(),
traits2dist()) while changing how they work underneath:
match_data() helper.phyloseq and TreeSummarizedExperiment
objects.ape post-order
traversal in place of geiger::tips();
hillpair() computes the shared structure once and reuses it
across all sample pairs.data.frame with
print()/plot()/autoplot()
methods; pass out = "matrix" for a plain matrix.
hillshare() returns a data frame of taxon and set
shares.type = c("auto", "neutral", "phylogenetic", "functional")
argument that asserts and validates the diversity type (auto-detected by
default).hillprof() (diversity profiles),
hilleven() (evenness) and hillshare() (taxon
and set shares), hierarchical multi-scale partitioning in
hillpart(), plus bundled example data
(gut_counts, gut_tree,
gut_traits).See NEWS.md for the full
changelog.
The diversity engine is covered by a testthat suite,
including golden-value tests against independent references
(vegan, hand-computed values and analytical identities such
as Faith’s PD and exact telescoping of nested partitions). Run it
with:
devtools::test()R CMD check runs on Linux, macOS and Windows on every
push via GitHub Actions.
CONTRIBUTING.md
for how to report problems, propose features and submit pull requests,
and for the support we aim to provide.Please note that the hilldiv3 project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
If you use hilldiv3, please cite it using the metadata
in CITATION.cff
(GitHub’s “Cite this repository” button), and the methodological
guide: