skbio.diversity.beta.weighted_unifrac#

skbio.diversity.beta.weighted_unifrac(u_counts, v_counts, taxa=None, tree=None, normalized=False, validate=True, otu_ids=None)[source]#

Compute weighted UniFrac with or without branch length normalization.

Parameters:

u_counts, v_counts: list, np.array: Vectors of counts/abundances of taxa for two samples. Must be equal length.
taxalist, np.array: Vector of taxon IDs corresponding to tip names in tree. Must be the same length as u_counts and v_counts. Required.
treeskbio.TreeNode: Tree relating taxa. The set of tip names in the tree can be a superset of taxa, but not a subset. Required.
normalized: boolean, optional: If True, apply branch length normalization, which is described in [1]. Resulting distances will then be in the range [0, 1].
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.
otu_idslist, np.array: Alias of taxa for backward compatibility. Deprecated and to be removed in a future release.

Returns:

float: The weighted UniFrac distance between the two samples.

Raises:

ValueError, MissingNodeError, DuplicateNodeError: If validation fails. Exact error will depend on what was invalid.

See also

unweighted_unifrac
skbio.diversity
skbio.diversity.beta_diversity

Notes

Weighted UniFrac was originally described in [1], which includes a discussion of unweighted (qualitative) versus weighted (quantitiative) diversity metrics. Deeper mathemtical discussions of this metric is presented in [2].

If computing weighted 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 taxa must be tips in the tree. PyCogent would silently ignore taxa 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 taxa are present in the tree.

This implementation of weighted UniFrac is the array-based implementation described in [3].

If using large number of samples or a large tree, we advise using the optimized UniFrac library [4].

References

[1] (1,2)

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).

[2]

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).

[3]

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).

[4]

biocore/unifrac

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 taxa 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 taxon each count corresponds to, which we’ll provide as taxa.

>>> taxa = ['U1', 'U2', 'U3', 'U4', 'U5', 'U6', 'U7', 'U8']

We also need a phylogenetic tree that relates the taxa to one another.

>>> from io import StringIO
>>> from skbio import TreeNode
>>> tree = TreeNode.read(StringIO(
...                      '(((((U1:0.5,U2:0.5):0.5,U3:1.0):1.0):0.0,'
...                      '(U4:0.75,(U5:0.5,((U6:0.33,U7:0.62):0.5'
...                      ',U8:0.5):0.5):0.5):1.25):0.0)root;'))

Compute the weighted UniFrac distance between the samples.

>>> from skbio.diversity.beta import weighted_unifrac
>>> wu = weighted_unifrac(u_counts, v_counts, taxa, tree)
>>> print(round(wu, 2))
1.54

Compute the weighted UniFrac distance between the samples including branch length normalization so the value falls in the range [0.0, 1.0].

>>> wu = weighted_unifrac(u_counts, v_counts, taxa, tree, normalized=True)
>>> print(round(wu, 2))
0.33