Faith's PD

Faith's phylogenetic diversity metric.

A higher value indicates a greater amount of evolutionary history represented within the community, suggesting higher biodiversity in terms of evolutionary relationships.

Usage

faith(counts, tree, cpus = n_cpus())

Arguments

counts: An OTU abundance matrix where each column is a sample, and each row is an OTU. Any object coercible with as.matrix() can be given here, as well as phyloseq, rbiom, SummarizedExperiment, and TreeSummarizedExperiment objects.
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').
cpus: How many parallel processing threads should be used. The default, n_cpus(), will use all logical CPU cores.

Value

A numeric vector.

Calculation

Given $n$ branches with lengths $L$ and a sample's abundances on each of those branches coded as 1 for present or 0 for absent:

$$\sum_{i = 1}^{n} P_i \times L_i$$

References

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

Examples

    # Example counts matrix
    ex_counts
#>                   Saliva Gums Nose Stool
#> Streptococcus        162  793   22     1
#> Bacteroides            2    4    2   611
#> Corynebacterium        0    0  498     1
#> Haemophilus          180   87    2     1
#> Propionibacterium      1    1  251     0
#> Staphylococcus         0    1  236     1
    
    # Faith diversity values
    faith(ex_counts, tree = ex_tree)
#> Saliva   Gums   Nose  Stool 
#>    180    191    215    202