hilldiv3

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.

Installation

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")
install.packages("hilldiv3", repos = c('https://alberdilab.r-universe.dev', 'https://cloud.r-project.org'))

Quick start

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)

# Rank taxa by their contribution to pairwise or collective dissimilarity.
head(hillcontrib(gut_counts, q = 1, metric = "C"))
head(hillcontrib(gut_counts, q = 1, metric = "C", by = "collective"))

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

Documentation

Full documentation lives on the package website: https://alberdilab.github.io/hilldiv3/

What's new in v3

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:

See NEWS.md for the full changelog.

Testing

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.

Getting help and contributing

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.

Citation

If you use hilldiv3, please cite it using the metadata in CITATION.cff (GitHub's "Cite this repository" button), and the methodological guide:

References