
Compare two taxon allocations of the same function with unassigned mass
Source:R/taxa_contribution.R
compare_taxa_contributions.RdCompares 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.
Arguments
- x, y
Data frames with columns
sample,taxon_labelandcontribution, such as the output ofaggregate_taxa_contributions. Afunction_idcolumn is used whenfunction_idsis 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 atop_nlarge 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 byaggregate_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)