Skip to main content
`Ctrl`+`K`

# skbio.diversity.alpha.faith_pd

skbio.diversity.alpha.faith_pd(counts, taxa, tree, validate=True)

  Calculate Faith’s phylogenetic diversity (Faith’s PD) metric.

  The Faith’s PD metric is defined as:

  \[PD = \sum_{b \in T \sqcup R} l(b)\]

  where \(T\) is a minimum set of branches (\(b\)) in a rooted tree that connect all taxa in a community. \(R\) is a set of branches from the lowest common ancestor (LCA) of the taxa to the root of the tree. \(PD\) is the sum of lengths (\(l\)) of branches in both sets.

  Parameters:
    counts 1-D array_like, int

      Vectors of counts/abundances of taxa for one sample.

    taxa list, np.array

      Vector of taxon IDs corresponding to tip names in `tree`. Must be the same length as `counts`. Required.

      Changed in version 0.6.0: Renamed from `otu_ids`. The old name is kept as an alias but is deprecated.

    tree skbio.TreeNode

      Tree relating taxa. The set of tip names in the tree can be a superset of `taxa`, but not a subset. Required.

    validate bool, optional

      Whether validate the input data (default: True). 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.

  Returns:
    float

      Faith’s phylogenetic diversity (PD).

  Raises:
    ValueError, MissingNodeError, DuplicateNodeError

      If validation fails. Exact error will depend on what was invalid.

  See also

  `phydiv`
  `skbio.diversity`
  `skbio.diversity.alpha_diversity`

  Notes

  Faith’s phylogenetic diversity, often referred to as PD, was originally described in [1]. It is the total phylogenetic branch length spanning all taxa of a community.

  It was clarified that the calculation should extend to the root of the tree [2], such that a single-taxon community will not have PD = 0. The root should be ancestral to all taxa being considered in the study, but does not need to be the origin of life. One should choose the root according to the scope of the study.

  Unrooted and abundance-weighted variants of PD are implemented in `phydiv`.

  Several other metrics, such as evolutionary history (EH) [3] and functional diversity (FD) [4], are equivalent to PD in calculation.

  When computing Faith’s PD for multiple samples, using `alpha_diversity` will be much faster than calling this function individually on each sample.

  This implementation of Faith’s PD is based on the array-based implementation of UniFrac described in [5].

  Note

  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 Faith PD results from PyCogent with scikit-bio, ensure that your PyCogent Faith PD calculations are performed on a rooted tree and that all taxa are present in the tree.

  References

  [1]

  Faith, D. P. Conservation evaluation and phylogenetic diversity. Biol. Conserv. (1992).

  [2]

  Faith, D. P., & Baker, A. M. (2006). Phylogenetic diversity (PD) and biodiversity conservation: some bioinformatics challenges. Evolutionary bioinformatics, 2, 117693430600200007.

  [3]

  Nee, S., & May, R. M. (1997). Extinction and the loss of evolutionary history. Science, 278(5338), 692-694.

  [4]

  Petchey OL, Gaston KJ. Functional diversity (FD), species richness and community composition. Ecology letters. 2002 May;5(3):402-11.

  [5]

  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 a sample `u`, represented as a counts vector. These counts represent the number of times specific taxa were observed in the sample.

      >>> u_counts = [1, 0, 0, 4, 1, 2, 3, 0]

  Because Faith PD 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 skbio import TreeNode
      >>> tree = TreeNode.read(['(((((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;'])

  We can then compute the Faith PD of the sample.

      >>> from skbio.diversity.alpha import faith_pd
      >>> pd = faith_pd(u_counts, taxa, tree)
      >>> print(round(pd, 2))
      6.95