Skip to contents

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"),
  hierarchy = NULL,
  metadata = NULL,
  weights = "equal",
  depth = NULL
)

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

Similarity metric(s) to return, any of "S", "C", "U", "V". Defaults to all four. Each is one minus the dissimilarity of the same code in hilldiss(), so identical assemblages give 1. "C" at q = 2 is the Morisita-Horn similarity.

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 shape: "tibble" (default) returns a long-format data.frame with columns q, metric, value; "matrix" returns the legacy matrix (orders in rows, metrics in columns, dropped to a vector for a single metric). With hierarchy, the table adds a scale column for each transition above the sample scale. A tau grid adds a tau column. Matrix output has one row per q and transition, with a named list of matrices for a tau grid.

hierarchy

Optional one-sided nesting formula, coarsest to finest, e.g. ~ region / site. Every transition above sample, including total, gets its own dissimilarity metrics. Each run uses one shared tree depth or functional tau; a functional tau grid runs the full hierarchy once per threshold.

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.

weights

Sample weights for hierarchical partitioning: "equal" (default), "abundance" (proportional to each sample's total count), or a positive numeric vector with one value per sample. A named vector is matched to count-table columns; an unnamed vector uses column order. Weights are normalised to sum to one. Requires hierarchy.

depth

Optional positive phylogenetic reference depth for hierarchical partitioning. On an ultrametric tree, use only branch segments within the last depth units before the tips. Must not exceed the tree height. NULL (default) uses the current shared mean-depth normaliser. Requires hierarchy and a phylogenetic tree.

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)
#> similarity from neutral Hill numbers of "q0", "q1", and "q2".
#> <hilldiv3 result: neutral>
#> 12 rows x 3 cols
#> 
#>    q metric     value
#> 1  0      S 0.6666667
#> 2  1      S 0.3918610
#> 3  2      S 0.2691680
#> 4  0      C 0.8000000
#> 5  1      C 0.4770152
#> 6  2      C 0.2691680
#> 7  0      U 0.6666667
#> 8  1      U 0.4770152
#> 9  2      U 0.4241645
#> 10 0      V 0.8000000
#> 11 1      V 0.5630749
#> 12 2      V 0.4241645
plot(hillsim(counts))
#> similarity from neutral Hill numbers of "q0", "q1", and "q2".