| Title: | Integral Analysis of Diversity Based on Hill Numbers |
| Version: | 3.0.0 |
| Description: | Measures and compares the diversity of biological communities (e.g. tables of operational taxonomic units (OTUs), amplicon sequence variants (ASVs) or metagenome-assembled genomes (MAGs)) based on Hill numbers, in a unified framework for neutral, phylogenetic and functional diversity measurement, diversity partitioning, (dis)similarity measurement, diversity profiles, evenness and redundancy. The statistical framework encompasses richness, Shannon and Simpson diversity, Faith's phylogenetic diversity (PD), Rao's quadratic entropy and Sorensen- and UniFrac-type dissimilarities, all grounded in a single Hill-number framework. Methods are described in Jost (2007) <doi:10.1890/06-1736.1>, Chao et al. (2010) <doi:10.1098/rstb.2010.0272>, Chiu et al. (2014) <doi:10.1890/12-0960.1> and reviewed in Alberdi & Gilbert (2019) <doi:10.1111/1755-0998.13014>. Optional import adapters interoperate with the Bioconductor packages 'phyloseq', 'SummarizedExperiment' and 'TreeSummarizedExperiment', which are available from https://bioconductor.org. |
| License: | GPL-3 |
| Language: | en-GB |
| URL: | https://github.com/alberdilab/hilldiv3, https://alberdilab.github.io/hilldiv3/ |
| BugReports: | https://github.com/alberdilab/hilldiv3/issues |
| Depends: | R (≥ 4.1.0) |
| Imports: | ape, cli, grDevices, graphics, methods, rlang, stats, utils |
| Suggests: | cluster, furrr, future, ggplot2, knitr, patchwork, phyloseq, progressr, rmarkdown, SummarizedExperiment, testthat (≥ 3.0.0), tibble, TreeSummarizedExperiment, vegan |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | no |
| Packaged: | 2026-09-26 03:27:49 UTC; anttonalberdi |
| Author: | Antton Alberdi |
| Maintainer: | Antton Alberdi <antton.alberdi@sund.ku.dk> |
| Repository: | CRAN |
| Date/Publication: | 2026-10-06 16:40:02 UTC |
hilldiv3: Integral Analysis of Diversity Based on Hill Numbers
Description
Measures and compares the diversity of biological communities (e.g. tables of operational taxonomic units (OTUs), amplicon sequence variants (ASVs) or metagenome-assembled genomes (MAGs)) based on Hill numbers, in a unified framework for neutral, phylogenetic and functional diversity measurement, diversity partitioning, (dis)similarity measurement, diversity profiles, evenness and redundancy. The statistical framework encompasses richness, Shannon and Simpson diversity, Faith's phylogenetic diversity (PD), Rao's quadratic entropy and Sorensen- and UniFrac-type dissimilarities, all grounded in a single Hill-number framework. Methods are described in Jost (2007) doi:10.1890/06-1736.1, Chao et al. (2010) doi:10.1098/rstb.2010.0272, Chiu et al. (2014) doi:10.1890/12-0960.1 and reviewed in Alberdi & Gilbert (2019) doi:10.1111/1755-0998.13014. Optional import adapters interoperate with the Bioconductor packages 'phyloseq', 'SummarizedExperiment' and 'TreeSummarizedExperiment', which are available from https://bioconductor.org.
Author(s)
Maintainer: Antton Alberdi antton.alberdi@sund.ku.dk (ORCID)
See Also
Useful links:
Report bugs at https://github.com/alberdilab/hilldiv3/issues
Simulated gut microbiome MAG count table
Description
A small, simulated example data set representing metagenome-assembled
genome (MAG) abundances across host samples from two groups (control and
treatment), where a block of MAGs is enriched in the treatment group so
that beta diversity is non-trivial. Generated by data-raw/make-data.R.
Usage
gut_counts
Format
An integer matrix with 24 rows (MAGs, mag01..mag24) and 12
columns (samples, ctrl01..ctrl06 and trt01..trt06).
See Also
Examples
hilldiv(gut_counts, q = c(0, 1, 2))
Functional traits for the simulated gut MAGs
Description
A trait table for the 24 MAGs in gut_counts, mixing continuous, categorical
and binary traits. Convert it to a functional distance with traits2dist()
for the functional-diversity paths.
Usage
gut_traits
Format
A data frame with 24 rows (MAGs) and 4 columns:
- genome_size
Approximate genome size in Mbp (numeric).
- gc_content
GC content as a proportion (numeric).
- oxygen
Oxygen tolerance: aerobe, anaerobe or facultative (factor).
- motility
Motility indicator, 0/1 (integer).
See Also
gut_counts, gut_tree, traits2dist()
Examples
d <- traits2dist(gut_traits)
hilldiv(gut_counts, q = c(0, 1), dist = d)
Phylogeny for the simulated gut MAGs
Description
An ultrametric coalescent tree over the 24 MAGs in gut_counts, scaled to unit depth. Use it for the phylogenetic-diversity paths.
Usage
gut_tree
Format
A phylo object (see the ape package) with 24 tips whose
labels match the rows of gut_counts.
See Also
Examples
hilldiv(gut_counts, q = c(0, 1), tree = gut_tree)
Tidy result objects for hilldiv3
Description
Internal helpers that turn the engine's wide matrices into the long-format
(tidy) data frames returned by the user-facing hill* functions, and the S3
print() / plot() / autoplot() methods for those results. Every result
carries a common parent class hill_result plus a specific subclass, so the
shared machinery (printing, line plots) is written once.
Hill numbers-based dissimilarity
Description
Compute overall (multi-sample) dissimilarity metrics from the Hill-number
beta diversity following Chiu et al. (2014). These are the complements of the
similarities returned by hillsim().
Usage
hilldiss(
data,
q = c(0, 1, 2),
metric = c("S", "C", "U", "V"),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
out = c("tibble", "matrix")
)
Arguments
data |
A count table (taxa x samples) or a supported object; a single sample is not meaningful for partitioning. |
q |
Numeric vector of diversity orders (>= 0). Defaults to
|
metric |
Dissimilarity metric(s) to return, any of |
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type: |
out |
Output shape: |
Value
A long-format data.frame of class hill_dissimilarity (default,
with a plot() method), or a matrix/vector of dissimilarities when
out = "matrix".
See Also
hillsim(), hillpair(), hillpart()
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1), nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
hilldiss(counts)
plot(hilldiss(counts))
Hill numbers computation
Description
Compute neutral, phylogenetic and/or functional Hill numbers (alpha
diversity) from a single sample or a count table. By default the computation
is cumulative: every diversity type whose inputs are present is returned.
Counts are always available, so neutral is always computed; a tree adds
phylogenetic and a dist adds functional. Supplying both a tree and a
dist therefore returns neutral, phylogenetic and functional side by side in
a single tibble (with a type column). Use type to restrict the output to
a subset.
Usage
hilldiv(
data,
q = c(0, 1, 2),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
reference = c("pool", "sample"),
out = c("tibble", "matrix")
)
Arguments
data |
Counts: a numeric vector (one sample), a matrix/data.frame
(taxa x samples), a |
q |
Numeric vector of diversity orders (>= 0). Defaults to
|
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type(s) to compute. |
reference |
Reference tree depth for phylogenetic Hill numbers
(ignored for neutral and functional types). |
out |
Output shape: |
Value
A long-format data.frame of class hill_diversity (default). With
out = "matrix", a matrix of Hill numbers (samples in rows, diversity
orders q0, q1, ... in columns) for a single type, or a named list of
such matrices when several types are computed.
References
Chao, A., Chiu, C.-H. & Jost, L. (2010). Phylogenetic diversity measures
based on Hill numbers. Phil. Trans. R. Soc. B, 365, 3599-3609.
Alberdi, A. & Gilbert, M.T.P. (2019). A guide to the application of Hill
numbers to DNA-based diversity analyses. Mol. Ecol. Resour., 19, 804-817.
See Also
hillpart(), hilldiss(), hillprof()
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1), nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
hilldiv(counts)
hilldiv(counts, q = c(0, 1, 2))
plot(hilldiv(counts, q = c(0, 1, 2)))
# Supplying both a tree and a distance matrix returns neutral, phylogenetic
# and functional diversity together, distinguished by a `type` column.
tree <- ape::read.tree(text = "((t1:1,t2:1):1,t3:2);")
dist <- as.matrix(stats::dist(c(t1 = 0, t2 = 1, t3 = 4)))
hilldiv(counts, tree = tree, dist = dist)
# Restrict the output with `type` (a scalar or a vector):
hilldiv(counts, tree = tree, dist = dist, type = c("neutral", "functional"))
Hill-number evenness
Description
Evenness expressed through Hill numbers as the ratio of diversity of order
q to richness (qD / 0D), which ranges from 0 to 1.
Usage
hilleven(
data,
q = c(1, 2),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
out = c("tibble", "matrix")
)
Arguments
data |
Counts: a numeric vector (one sample), a matrix/data.frame
(taxa x samples), a |
q |
Numeric vector of diversity orders (> 0 are meaningful for
evenness). Defaults to |
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type: |
out |
Output shape: |
Value
A long-format data.frame of class hill_evenness (default) with a
plot() method, or a matrix of evenness values (samples in rows, orders in
columns) when out = "matrix".
See Also
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1), nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
hilleven(counts)
plot(hilleven(counts, q = c(1, 1.5, 2)))
Pairwise Hill numbers-based dissimilarity
Description
Compute dissimilarity metrics for every pair of samples, returning distance objects suitable for ordination (e.g. NMDS, PCoA).
Usage
hillpair(
data,
q = c(0, 1, 2),
metric = c("S", "C", "U", "V"),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
out = c("dist", "tibble"),
parallel = FALSE
)
Arguments
data |
A count table (taxa x samples) or a supported object; a single sample is not meaningful for partitioning. |
q |
Numeric vector of diversity orders (>= 0). Defaults to
|
metric |
Dissimilarity metric(s) to return, any of |
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type: |
out |
Output type: |
parallel |
Logical; if |
Details
The type-specific structure (per-sample normalisation, the tree traversal or
the functional similarity product) is computed once over all samples via
the partitioning engine; each pair then only combines its two precomputed
columns into beta, which is turned into the requested overlap metrics. The
maths are therefore identical to hilldiss() on two samples, without
re-running the full engine per pair. When parallel = TRUE and the furrr
package is installed, pairs are computed in parallel via the active future
plan. A progressr progress bar is reported when that package is installed
and a handler is active.
Value
For out = "dist", a named list of dist objects (one per
order/metric, named e.g. "q0S"), collapsed to a single dist when only
one combination is requested. For out = "tibble", a long-format
data.frame with columns first, second, q, metric, value.
See Also
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1, 3, 4, 0, 6, 2, 7), nrow = 3,
dimnames = list(c("t1", "t2", "t3"),
c("s1", "s2", "s3", "s4")))
hillpair(counts, q = 1, metric = "C")
Hill numbers diversity partitioning
Description
Partition neutral, phylogenetic or functional Hill-number diversity into
alpha, gamma and beta components across a set of samples. With a hierarchy
formula it instead performs multi-scale (nested) partitioning, returning
one beta per hierarchical level.
Usage
hillpart(
data,
q = c(0, 1, 2),
tree = NULL,
dist = NULL,
tau = NULL,
hierarchy = NULL,
metadata = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
out = c("tibble", "matrix")
)
Arguments
data |
A count table (taxa x samples) or a supported object; a single sample is not meaningful for partitioning. |
q |
Numeric vector of diversity orders (>= 0). Defaults to
|
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
hierarchy |
Optional one-sided nesting formula, coarsest to finest, e.g.
|
metadata |
Optional per-sample |
type |
Diversity type: |
out |
Output shape: |
Value
A long-format data.frame of class hill_partition (default) with a
plot() method, or a matrix with columns alpha, gamma, beta and
diversity orders in rows when out = "matrix". With hierarchy, a
hill_hierarchy long-format data.frame (with its own plot() method) or
the corresponding wide matrix.
See Also
hilldiv(), hilldiss(), hillsim()
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1), nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
hillpart(counts)
plot(hillpart(counts))
# Multi-scale partitioning across a nested design.
set.seed(1)
tab <- matrix(rpois(12 * 8, 5), nrow = 12,
dimnames = list(paste0("t", 1:12), paste0("s", 1:8)))
md <- data.frame(region = rep(c("N", "S"), each = 4),
site = rep(c("a", "b", "c", "d"), each = 2),
row.names = paste0("s", 1:8))
hillpart(tab, hierarchy = ~ region / site, metadata = md)
Diversity profile across a range of orders
Description
Compute a diversity profile: Hill numbers evaluated over a fine sweep of
diversity orders q. Profiles are the standard diagnostic for comparing the
diversity of assemblages, since the ranking of samples can change with q.
Usage
hillprof(
data,
q = seq(0, 3, by = 0.1),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
reference = c("pool", "sample"),
out = c("tibble", "matrix")
)
Arguments
data |
Counts: a numeric vector (one sample), a matrix/data.frame
(taxa x samples), a |
q |
Numeric vector of diversity orders to evaluate. Defaults to a fine sweep from 0 to 3. |
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type: |
reference |
Reference tree depth for phylogenetic Hill numbers
(ignored for neutral and functional types). |
out |
Output type: |
Value
A long-format data.frame of class hill_profile (columns q,
sample, value) with a plot() method, or a matrix
(samples in rows, orders in columns) when out = "matrix".
See Also
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1), nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
prof <- hillprof(counts)
plot(prof)
Hill numbers redundancy
Description
Estimate phylogenetic or functional redundancy by fitting the saturating
relationship between neutral diversity and phylogenetic/functional diversity
across samples: y = -a * 2^(-x / b) + c. Redundancy is summarised as
1 - b / max(x).
Usage
hillred(
data,
q = c(0, 1, 2),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "phylogenetic", "functional"),
reference = c("pool", "sample"),
out = c("tibble", "matrix")
)
Arguments
data |
A count table (taxa x samples); requires either |
q |
Numeric vector of diversity orders (>= 0). Defaults to
|
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type: |
reference |
Reference tree depth for phylogenetic Hill numbers
(ignored for neutral and functional types). |
out |
Output shape: |
Value
A data.frame of class hill_redundancy (default) with a
plot() method, or a matrix with columns
redundancy, a, b, c (one row per q) when out = "matrix". The
tibble carries the per-sample neutral and phylogenetic/functional diversity
used for the fit as a "hill_fit" attribute, which the plot method draws.
See Also
hilldiv(), plot.hill_redundancy()
Examples
d <- traits2dist(gut_traits)
red <- hillred(gut_counts, dist = d)
red
plot(red)
Hill numbers-based similarity
Description
Compute overall similarity metrics from the Hill-number beta diversity
(Chiu et al. 2014). These are 1 - the dissimilarities from hilldiss().
Usage
hillsim(
data,
q = c(0, 1, 2),
metric = c("S", "C", "U", "V"),
tree = NULL,
dist = NULL,
tau = NULL,
type = c("auto", "neutral", "phylogenetic", "functional"),
out = c("tibble", "matrix")
)
Arguments
data |
A count table (taxa x samples) or a supported object; a single sample is not meaningful for partitioning. |
q |
Numeric vector of diversity orders (>= 0). Defaults to
|
metric |
Dissimilarity metric(s) to return, any of |
tree |
A phylogenetic tree of class |
dist |
A functional distance matrix (or |
tau |
Optional functional distance threshold. Defaults to |
type |
Diversity type: |
out |
Output shape: |
Value
A long-format data.frame of class hill_similarity (default, with
a plot() method), or a matrix/vector of similarities when
out = "matrix".
See Also
Examples
counts <- matrix(c(10, 0, 5, 2, 8, 1), nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
hillsim(counts)
plot(hillsim(counts))
Match and align a count table to a tree or distance matrix
Description
Subsets and reorders a count table so that its taxa match those of a
phylogenetic tree or a functional distance matrix, dropping taxa absent from
the reference. This realises the match_data() helper that hilldiv2's
documentation referred to but never provided.
Usage
match_data(data, tree = NULL, dist = NULL)
Arguments
data |
A count matrix/data.frame (taxa x samples) with row names. |
tree |
A |
dist |
A distance matrix (optional). |
Value
The count matrix restricted to and ordered by the shared taxa.
Examples
counts <- matrix(1:6, nrow = 3,
dimnames = list(c("t1", "t2", "t3"), c("s1", "s2")))
tree <- ape::read.tree(text = "((t1:1,t2:1):1,t4:2);")
match_data(counts, tree = tree)
Plot a diversity profile
Description
Base-graphics plot of a hillprof() result: one line per sample showing the
Hill number against the diversity order q.
Usage
## S3 method for class 'hill_profile'
plot(x, ...)
Arguments
x |
A |
... |
Further arguments passed to |
Value
The hill_profile object, invisibly.
Plot a redundancy fit
Description
Base-graphics plot of a hillred() result. For each diversity order q it
shows the per-sample neutral diversity (x) against phylogenetic/functional
diversity (y), overlaid with the fitted saturating curve
y = -a * 2^(-x / b) + c. A curve that bends sharply and plateaus well below
the points' spread indicates high redundancy; a near-linear fit indicates
low redundancy. This mirrors the profile plot of hillprof().
Usage
## S3 method for class 'hill_redundancy'
plot(x, ...)
Arguments
x |
A |
... |
Further arguments passed to |
Value
The hill_redundancy object, invisibly.
See Also
hillred(), plot.hill_profile()
Convert a trait table into a distance matrix
Description
Build a pairwise functional distance matrix from a table of taxon traits,
suitable as the dist argument of hilldiv() and friends.
Usage
traits2dist(traits, method = c("gower", "euclidean", "manhattan"))
Arguments
traits |
A table with taxa (OTUs/ASVs/MAGs) in rows and traits in columns. Traits may be continuous, binary or proportional. |
method |
Distance metric passed to |
Value
A numeric distance matrix.
Examples
traits <- data.frame(body = c(1, 0.2, 0.9), diet = c(0L, 1L, 1L),
row.names = c("t1", "t2", "t3"))
traits2dist(traits)
Total Sum Scaling normalisation
Description
Normalise a numeric vector or count matrix so that each sample (column) sums
to one. Columns that sum to zero are returned as all-zero (the 0/0 = NaN
case is mapped to 0).
Usage
tss(abund)
Arguments
abund |
A numeric vector or a matrix/data.frame of counts with taxa (OTUs/ASVs/MAGs) in rows and samples in columns. |
Value
A normalised object of the same shape as abund (vector in, vector
out; matrix/data.frame in, matrix out).
Examples
tss(c(a = 1, b = 3))
tss(matrix(c(1, 0, 3, 0, 0, 2), nrow = 3))