name.balance: Name a balance (coordinate) based on taxonomy

In jsilve24/philr: Phylogenetic partitioning based ILR transform for metagenomics data

Name a balance (coordinate) based on taxonomy

Description

For a given ILR balance (coordinate) assigns a name to the balance based on a provided taxonomy table. This is useful for interpretation of the balances.

Usage

name.balance(
  tr,
  tax,
  coord,
  method = "voting",
  thresh = 0.95,
  return.votes = NULL
)

Arguments

tr	an object of class 'phylo'
tax	a matrix/data.frame of taxonomy, rownames should correspond to tr$tip.labels columns should be taxonomic levels (named) with increasing taxonomic resolution from left to right (e.g., Phylum to the left of Genus).
coord	the name of a balance/internal node on the tree (given as a string)
method	currently only 'voting' implemented. See Details.
thresh	threshold for assignment of taxonomy to a given part of a balance (must be greater than 0.5 if method='voting'; see details).
return.votes	whether voting results by taxonomic level should be shown for coord. Note: this is helpful when name.balance does not return a clear winner, as may be the case when a given coord represents more than one taxonomic lineage. votes are returned as a list indexed by colnames(tax) Options include: NULL (default) only returns the combined consensus name of the balance 'up' adds tallied votes for the 'up' node to the output list 'down' adds tallied votes for the 'down' node to the output list 'self' adds tallied votes for coord to the output list

Details

A bit of terminology:

coord

this is the same as the names of the balances which should be the same as the names of the internal nodes of tr

'up'

this is the child node of coord that is represented in the numerator of the coord balance.

'down'

this is the child node of coord that is represented in the denominator of the coord balance

The method 'voting' assigns the name of the each part of a balance (e.g., numerator and denominator / each child of coord) as follows:

1. First Subset tax to contain only descendent tips of the given child of coord

2. Second At the finest taxonomic (farthest right of tax) see if any one taxonomic label is present at or above thresh. If yes output that taxonomic label (at that taxonomic level) as the label for that child of coord. If no then move to coarser taxonomic level (leftward) and repeat.

Value

If return.votes=NULL returns a string of the form (ex. 'Genus_Bacteroides/Phylum_Firmicutes'). Otherwise returns a list with the above string as 'name', see Arguments for show.votes for other optional returned items.

Author(s)

Justin Silverman

See Also

philr

Examples

tr <- named_rtree(40)
tax <- data.frame(Kingdom=rep('A', 40),
               Phylum=rep(c('B','C'), each=20),
               Genus=c(sample(c('D','F'),20, replace=TRUE),
                       sample(c('G','H'), 20, replace=TRUE)))
rownames(tax) <- tr$tip.label
name.balance(tr, tax, 'n1')
name.balance(tr, tax, 'n34')
name.balance(tr,tax, 'n34', return.votes = c('up', 'down'))

jsilve24/philr documentation built on Oct. 17, 2024, 4:59 p.m.