Skip to contents

Alpha Diversity Wrapper Function

Usage

alpha_div(counts, metric, ...)

Arguments

counts

A numeric matrix of count data where each column is a feature, and each row is a sample. Any object coercible with as.matrix() can be given here, as well as phyloseq, rbiom, SummarizedExperiment, and TreeSummarizedExperiment objects.

metric

The name of an alpha diversity metric. One of c('ace', 'berger', 'brillouin', 'chao1', 'faith', 'fisher', 'inv_simpson', 'margalef', 'mcintosh', 'menhinick', 'observed', 'shannon', 'simpson', 'squares'). Case-insensitive and partial name matching is supported. Programmatic access via list_metrics('alpha').

...

Additional options to pass through to the called function. I.e. cpus or tree.

Value

A numeric vector.

Details

Integer Count Requirements

A frequent and critical error in alpha diversity analysis is providing the wrong type of data to a metric's formula. Some indices are mathematically defined based on counts of individuals and require raw, integer abundance data. Others are based on proportional abundances and can accept either integer counts (which are then converted to proportions) or pre-normalized proportional data. Using proportional data with a metric that requires integer counts will return an error message.

Requires Integer Counts OnlyCan Use Proportional Data
Chao1Observed Features
ACEShannon Index
Squares Richness EstimatorGini-Simpson Index
Margalef's IndexInverse Simpson Index
Menhinick's IndexBerger-Parker Index
Fisher's AlphaMcIntosh Index
Brillouin IndexFaith's PD (presence/absence)

Examples

    # Example counts matrix
    ex_counts
#>        Streptococcus Bacteroides Corynebacterium Haemophilus Propionibacterium
#> Saliva           162           2               0         180                 1
#> Gums             793           4               0          87                 1
#> Nose              22           2             498           2               251
#> Stool              1         611               1           1                 0
#>        Staphylococcus
#> Saliva              0
#> Gums                1
#> Nose              236
#> Stool               1
    
    # Shannon diversity values
    alpha_div(ex_counts, 'Shannon')
#>     Saliva       Gums       Nose      Stool 
#> 0.74119910 0.36684449 1.14222899 0.04824952 
    
    # Chao1 diversity values
    alpha_div(ex_counts, 'c')
#> Saliva   Gums   Nose  Stool 
#>    4.5    Inf    6.0    Inf 
    
    # Faith PD values
    alpha_div(ex_counts, 'faith', tree = ex_tree)
#> Saliva   Gums   Nose  Stool 
#>    180    191    215    202