Skip to contents

Beta Diversity Wrapper Function

Usage

beta_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 a beta diversity metric. One of c('aitchison', 'bhattacharyya', 'bray', 'canberra', 'chebyshev', 'chord', 'clark', 'divergence', 'euclidean', 'generalized_unifrac', 'gower', 'hamming', 'hellinger', 'horn', 'jaccard', 'jensen', 'jsd', 'lorentzian', 'manhattan', 'matusita', 'minkowski', 'morisita', 'motyka', 'normalized_unifrac', 'ochiai', 'psym_chisq', 'soergel', 'sorensen', 'squared_chisq', 'squared_chord', 'squared_euclidean', 'topsoe', 'unweighted_unifrac', 'variance_adjusted_unifrac', 'wave_hedges', 'weighted_unifrac'). Flexible matching is supported (see below). Programmatic access via list_metrics('beta').

...

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

Value

A numeric vector.

Details

List of Beta Diversity Metrics

Option / Function NameMetric Name
aitchisonAitchison distance
bhattacharyyaBhattacharyya distance
brayBray-Curtis dissimilarity
canberraCanberra distance
chebyshevChebyshev distance
chordChord distance
clarkClark's divergence distance
divergenceDivergence
euclideanEuclidean distance
generalized_unifracGeneralized UniFrac (GUniFrac)
gowerGower distance
hammingHamming distance
hellingerHellinger distance
hornHorn-Morisita dissimilarity
jaccardJaccard distance
jensenJensen-Shannon distance
jsdJesen-Shannon divergence (JSD)
lorentzianLorentzian distance
manhattanManhattan distance
matusitaMatusita distance
minkowskiMinkowski distance
morisitaMorisita dissimilarity
motykaMotyka dissimilarity
normalized_unifracNormalized Weighted UniFrac
ochiaiOtsuka-Ochiai dissimilarity
psym_chisqProbabilistic Symmetric Chi-Squared distance
soergelSoergel distance
sorensenDice-Sorensen dissimilarity
squared_chisqSquared Chi-Squared distance
squared_chordSquared Chord distance
squared_euclideanSquared Euclidean distance
topsoeTopsoe distance
unweighted_unifracUnweighted UniFrac
variance_adjusted_unifracVariance-Adjusted Weighted UniFrac (VAW-UniFrac)
wave_hedgesWave Hedges distance
weighted_unifracWeighted UniFrac

Flexible name matching

Case insensitive and partial matching. Any runs of non-alpha characters are converted to underscores. E.g. metric = 'Weighted UniFrac selects weighted_unifrac.

UniFrac names can be shortened to the first letter plus "unifrac". E.g. uunifrac, w_unifrac, or V UniFrac. These also support partial matching.

Finished code should always use the full primary option name to avoid ambiguity with future additions to the metrics list.

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
    
    # Bray-Curtis distances
    beta_div(ex_counts, 'bray')
#>          Saliva      Gums      Nose
#> Gums  0.4265973                    
#> Nose  0.9713843 0.9720256          
#> Stool 0.9909509 0.9911046 0.9915177
    
    # Generalized UniFrac distances
    beta_div(ex_counts, 'GUniFrac', tree = ex_tree)
#>          Saliva      Gums      Nose
#> Gums  0.4471644                    
#> Nose  0.8215129 0.7607876          
#> Stool 0.9727827 0.9784242 0.9730332