skbio.diversity.beta.
unweighted_unifrac
(u_counts, v_counts, otu_ids, tree, validate=True)[source]¶Compute unweighted UniFrac
State: Experimental as of 0.4.1.
v_counts (u_counts,) – Vectors of counts/abundances of OTUs for two samples. Must be equal length.
otu_ids (list, np.array) – Vector of OTU ids corresponding to tip names in tree
. Must be the
same length as u_counts
and v_counts
.
tree (skbio.TreeNode) – Tree relating the OTUs in otu_ids. The set of tip names in the tree can
be a superset of otu_ids
, but not a subset.
validate (bool, optional) – If False, validation of the input won’t be performed. This step can
be slow, so if validation is run elsewhere it can be disabled here.
However, invalid input data can lead to invalid results or error
messages that are hard to interpret, so this step should not be
bypassed if you’re not certain that your input data are valid. See
skbio.diversity
for the description of what validation entails
so you can determine if you can safely disable validation.
The unweighted UniFrac distance between the two samples.
float
ValueError, MissingNodeError, DuplicateNodeError – If validation fails. Exact error will depend on what was invalid.
Notes
Unweighted UniFrac was originally described in 1. A discussion of unweighted (qualitative) versus weighted (quantitative) diversity metrics is presented in 2. Deeper mathematical discussions of this metric is presented in 3.
If computing unweighted UniFrac for multiple pairs of samples, using
skbio.diversity.beta_diversity
will be much faster than calling this
function individually on each sample.
This implementation differs from that in PyCogent (and therefore QIIME versions less than 2.0.0) by imposing a few additional restrictions on the inputs. First, the input tree must be rooted. In PyCogent, if an unrooted tree was provided that had a single trifurcating node (a newick convention for unrooted trees) that node was considered the root of the tree. Next, all OTU IDs must be tips in the tree. PyCogent would silently ignore OTU IDs that were not present the tree. To reproduce UniFrac results from PyCogent with scikit-bio, ensure that your PyCogent UniFrac calculations are performed on a rooted tree and that all OTU IDs are present in the tree.
This implementation of unweighted UniFrac is the array-based implementation described in 4.
References
Lozupone, C. & Knight, R. UniFrac: a new phylogenetic method for comparing microbial communities. Appl. Environ. Microbiol. 71, 8228-8235 (2005).
Lozupone, C. A., Hamady, M., Kelley, S. T. & Knight, R. Quantitative and qualitative beta diversity measures lead to different insights into factors that structure microbial communities. Appl. Environ. Microbiol. 73, 1576-1585 (2007).
Lozupone, C., Lladser, M. E., Knights, D., Stombaugh, J. & Knight, R. UniFrac: an effective distance metric for microbial community comparison. ISME J. 5, 169-172 (2011).
Hamady M, Lozupone C, Knight R. Fast UniFrac: facilitating high- throughput phylogenetic analyses of microbial communities including analysis of pyrosequencing and PhyloChip data. ISME J. 4(1):17-27 (2010).
Examples
Assume we have the following abundance data for two samples, u
and
v
, represented as a pair of counts vectors. These counts represent the
number of times specific Operational Taxonomic Units, or OTUs, were
observed in each of the samples.
>>> u_counts = [1, 0, 0, 4, 1, 2, 3, 0]
>>> v_counts = [0, 1, 1, 6, 0, 1, 0, 0]
Because UniFrac is a phylogenetic diversity metric, we need to know which
OTU each count corresponds to, which we’ll provide as otu_ids
.
>>> otu_ids = ['OTU1', 'OTU2', 'OTU3', 'OTU4', 'OTU5', 'OTU6', 'OTU7',
... 'OTU8']
We also need a phylogenetic tree that relates the OTUs to one another.
>>> from io import StringIO
>>> from skbio import TreeNode
>>> tree = TreeNode.read(StringIO(
... '(((((OTU1:0.5,OTU2:0.5):0.5,OTU3:1.0):1.0):0.0,'
... '(OTU4:0.75,(OTU5:0.5,((OTU6:0.33,OTU7:0.62):0.5'
... ',OTU8:0.5):0.5):0.5):1.25):0.0)root;'))
We can then compute the unweighted UniFrac distance between the samples.
>>> from skbio.diversity.beta import unweighted_unifrac
>>> uu = unweighted_unifrac(u_counts, v_counts, otu_ids, tree)
>>> print(round(uu, 2))
0.37