Skip to contents

Compares how two contribution profiles allocate the same functional total to taxa within each sample, for example a PICRUSt2 prediction and a stratified shotgun profile, or one prediction at two taxonomic support thresholds. Unassigned contributions are kept in each denominator rather than renormalized away. Because unassigned mass could belong to any taxon, the total variation (TV) distance between the two allocations is reported as an interval.

Usage

compare_taxa_contributions(
  x,
  y,
  function_ids = NULL,
  unassigned_label = "Unclassified"
)

Arguments

x, y

Data frames with columns sample, taxon_label and contribution, such as the output of aggregate_taxa_contributions. A function_id column is used when function_ids is supplied. Taxon labels must denote the same categories in both inputs; the function does not harmonize taxonomies. Neither input may contain the lumped "Other" category, because it pools different taxa; aggregate with a top_n large enough to keep every assigned taxon.

function_ids

Optional character vector. When supplied, only these functions are summed into the per-sample total, in both inputs.

unassigned_label

Label of unassigned contributions. Default "Unclassified", as produced by aggregate_taxa_contributions.

Value

A data frame with one row per sample present in both inputs: sample, x_total, y_total, x_unassigned, y_unassigned (unassigned shares), tv_lower, tv_upper and tv_unassigned_as_category. Samples with a zero total in either input have NA distances.

Details

Let \(p\) and \(q\) be the assigned shares and \(u_x\), \(u_y\) the unassigned shares, so that each allocation sums to one. The smallest achievable TV distance fills opposing deficits with unassigned mass: \(\max(0, \sum (p - q)_+ - u_y, \sum (q - p)_+ - u_x)\). The largest places unassigned mass in categories absent from the other allocation: \(\min(1, 1 - \sum \min(p, q))\). tv_unassigned_as_category treats "unassigned" as one shared category, which lies between the two. A narrow interval means the comparison is decided by assigned mass; a wide one means it depends on where unassigned contributions really belong. The bounds describe missing allocation, not misclassification.

Examples

x <- data.frame(sample = "S1", taxon_label = c("A", "B", "Unclassified"),
                contribution = c(5, 3, 2))
y <- data.frame(sample = "S1", taxon_label = c("A", "B"),
                contribution = c(5, 5))
compare_taxa_contributions(x, y)