hillpair: Pairwise Hill numbers-based dissimilarity

In hilldiv3: Integral Analysis of Diversity Based on Hill Numbers

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 c(0, 1, 2) (richness, Shannon, Simpson).
metric	Dissimilarity metric(s) to return, any of "S", "C", "U", "V". Defaults to all four.
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).
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 type: "dist" (default) returns a dist object per requested metric/order combination; "tibble" returns a long-format table.
parallel	Logical; if TRUE and furrr is installed, compute pairs in parallel.

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

hilldiss(), hilldiv()

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")

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