Skip to contents

Faith's Phylogenetic Diversity (PD)

Source: R/alpha_div.r
faith.Rd

Calculates the sum of the branch lengths for all species present in a sample.

Usage

faith(counts, tree = NULL, margin = 1L, cpus = n_cpus())

Arguments

counts

A numeric matrix of count data (samples \(\times\) features). Typically contains absolute abundances (integer counts), though proportions are also accepted.

tree

A phylo-class object representing the phylogenetic tree for the OTUs in counts. The OTU identifiers given by colnames(counts) must be present in tree. Can be omitted if a tree is embedded with the counts object or as attr(counts, 'tree').

margin

The margin containing samples. 1 if samples are rows, 2 if samples are columns. Ignored when counts is a special object class (e.g. phyloseq). Default: 1

cpus

How many parallel processing threads should be used. The default, n_cpus(), will use all logical CPU cores.

Details

Faith's PD is defined as: $$\sum_{i = 1}^{n} L_i A_i$$

Where:

  • \(n\) : The number of branches in the phylogenetic tree.

  • \(L_i\) : The length of the \(i\)-th branch.

  • \(A_i\) : A binary value (1 if any descendants of branch \(i\) are present in the sample, 0 otherwise).

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

  • phyloseq

  • rbiom

  • SummarizedExperiment

  • TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Faith, D. P. (1992). Conservation evaluation and phylogenetic diversity. Biological Conservation, 61(1), 1-10. doi:10.1016/0006-3207(92)91201-3

See also

alpha_div(), vignette('adiv')

Other Phylogenetic metrics: generalized_unifrac(), normalized_unifrac(), unweighted_unifrac(), variance_adjusted_unifrac(), weighted_unifrac()

Examples

    faith(ex_counts, tree = ex_tree)
#> Saliva   Gums   Nose  Stool 
#>    180    191    215    202