hillpart: Hill numbers diversity partitioning

In hilldiv3: Integral Analysis of Diversity Based on Hill Numbers

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 c(0, 1, 2) (richness, Shannon, Simpson).
tree	A phylogenetic tree of class phylo whose tip labels match the taxa in data.
dist	A functional distance matrix (or dist) over the taxa.
tau	Optional functional distance threshold. Defaults to max(dist).
hierarchy	Optional one-sided nesting formula, coarsest to finest, e.g. ~ region / site, requesting multi-scale (nested) partitioning instead of the default single-level partition. One beta is returned per hierarchical transition and the chain telescopes exactly: gamma = alpha_finest * prod(beta). Works for all three diversity types (neutral, phylogenetic, functional); see the partitioning vignette for the shared construction and its assumptions (equal per-sample weighting; one shared tree depth / tau across scales). Grouping variables are resolved against metadata when supplied, otherwise against the calling environment.
metadata	Optional per-sample data.frame supplying the variables named in hierarchy; rows are matched to the count-table columns by name when possible, otherwise by position.
type	Diversity type: "auto" (default) infers it from the inputs (counts only -> neutral, +tree -> phylogenetic, +dist -> functional); an explicit "neutral", "phylogenetic" or "functional" asserts the type and is validated against the inputs (e.g. "phylogenetic" requires a tree; "neutral" ignores any tree/dist carried by the object).
out	Output shape: "tibble" (default) returns a long-format data.frame with columns q, component, value; "matrix" returns the legacy matrix (orders in rows, alpha/gamma/beta in columns). With hierarchy, "tibble" returns one row per ⁠(q, scale)⁠ and "matrix" returns alpha, one ⁠beta_<level>⁠ per nesting level, and gamma.

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)

hilldiv3 documentation built on Oct. 6, 2026, 5:06 p.m.