--- title: "Introduction to ecodive" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to ecodive} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ## Introduction Ecodive calculates ecological diversity metrics. Alpha diversity metrics provide insight about a single sample's diversity, whereas beta diversity metrics indicate how different a pair of samples are from each other. In this guide, we'll use the `ex_counts` dataset included with ecodive. `ex_counts` is a feature table that enumerates how many times each bacterial genera was observed on different body sites. ```r library(ecodive) t(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 ``` In this example, the 'features' in our feature table are genera. However, your own dataset can use whatever feature makes sense - species, OTUs, ASVs, or even something completely unrelated to ecology. ## Alpha Diversity Alpha diversity metrics describe how many different genera are present in a sample. Depending on the metric, this can take into account the number of unique genera (richness), how evenly the population is split among genera (evenness), or how distantly related the genera are (phylogenetic diversity). The available alpha diversity metrics can be listed using `list_metrics()`. ```r list_metrics('alpha')[,1:5] #> name id phylo weighted int_only #> 1 Abundance-based Coverage Estimator (ACE) ace FALSE TRUE TRUE #> 3 Berger-Parker Index berger FALSE TRUE FALSE #> 6 Brillouin Index brillouin FALSE TRUE TRUE #> 8 Chao1 chao1 FALSE TRUE TRUE #> 15 Faith's Phylogenetic Diversity faith TRUE FALSE FALSE #> 16 Fisher's Alpha fisher FALSE TRUE TRUE #> 18 Gini-Simpson Index simpson FALSE TRUE FALSE #> 23 Inverse Simpson Index inv_simpson FALSE TRUE FALSE #> 29 Margalef's Richness Index margalef FALSE TRUE TRUE #> 31 McIntosh Index mcintosh FALSE TRUE TRUE #> 32 Menhinick's Richness Index menhinick FALSE TRUE TRUE #> 37 Observed Features observed FALSE FALSE FALSE #> 40 Shannon Diversity Index shannon FALSE TRUE FALSE #> 45 Squares Richness Estimator squares FALSE TRUE TRUE ``` * Further reading: `vignette('adiv')` ## Beta Diversity Beta diversity metrics describe how different two samples are, based on the genera observed in each.UniFrac metrics incorporate a phylogenetic tree into this calculation. The available alpha diversity metrics can be listed using `list_metrics()`. ```r list_metrics('beta')[,2:6] #> id phylo weighted int_only true_metric #> 2 aitchison FALSE TRUE FALSE TRUE #> 4 bhattacharyya FALSE TRUE FALSE TRUE #> 5 bray FALSE TRUE FALSE FALSE #> 7 canberra FALSE TRUE FALSE TRUE #> 9 chebyshev FALSE TRUE FALSE TRUE #> 10 chord FALSE TRUE FALSE TRUE #> 11 clark FALSE TRUE FALSE TRUE #> 12 sorensen FALSE FALSE FALSE FALSE #> 13 divergence FALSE TRUE FALSE TRUE #> 14 euclidean FALSE TRUE FALSE TRUE #> 17 generalized_unifrac TRUE TRUE FALSE TRUE #> 19 gower FALSE TRUE FALSE TRUE #> 20 hamming FALSE FALSE FALSE TRUE #> 21 hellinger FALSE TRUE FALSE TRUE #> 22 horn FALSE TRUE FALSE FALSE #> 24 jaccard FALSE FALSE FALSE TRUE #> 25 jensen FALSE TRUE FALSE TRUE #> 26 jsd FALSE TRUE FALSE TRUE #> 27 lorentzian FALSE TRUE FALSE FALSE #> 28 manhattan FALSE TRUE FALSE TRUE #> 30 matusita FALSE TRUE FALSE TRUE #> 33 minkowski FALSE TRUE FALSE TRUE #> 34 morisita FALSE TRUE TRUE FALSE #> 35 motyka FALSE TRUE FALSE FALSE #> 36 normalized_unifrac TRUE TRUE FALSE TRUE #> 38 ochiai FALSE FALSE FALSE FALSE #> 39 psym_chisq FALSE TRUE FALSE FALSE #> 41 soergel FALSE TRUE FALSE TRUE #> 42 squared_chisq FALSE TRUE FALSE FALSE #> 43 squared_chord FALSE TRUE FALSE FALSE #> 44 squared_euclidean FALSE TRUE FALSE FALSE #> 46 topsoe FALSE TRUE FALSE TRUE #> 47 unweighted_unifrac TRUE TRUE FALSE TRUE #> 48 variance_adjusted_unifrac TRUE TRUE FALSE TRUE #> 49 wave_hedges FALSE TRUE FALSE FALSE #> 50 weighted_unifrac TRUE TRUE FALSE TRUE ``` ## Example ### Rarefaction The `ex_counts` feature table has 345 saliva observations, but nose has 1011 observations. This unequal sampling depth can cause systematic biases. Specifically, rare genera will be observed more often in samples with greater sampling depths, thereby artificially inflating the observed richness. The first step then is to rarefy `ex_counts` so that all samples have the same number of observations. Rarefying randomly removes observations from samples with more observations. ```r rowSums(ex_counts) #> Saliva Gums Nose Stool #> 345 886 1011 615 counts <- rarefy(ex_counts) rowSums(counts) #> Saliva Gums Nose Stool #> 345 345 345 345 t(counts) #> Saliva Gums Nose Stool #> Streptococcus 162 309 6 1 #> Bacteroides 2 2 0 341 #> Corynebacterium 0 0 171 1 #> Haemophilus 180 34 0 1 #> Propionibacterium 1 0 82 0 #> Staphylococcus 0 0 86 1 ``` ### Classic Metrics These alpha and beta diversity metrics have been around for 50+ years and don't require a phylogenetic tree. The beta diversity functions can take a `weighted = FALSE` argument to use only presence/absence information instead of relative abundances. ```r ## Alpha Diversity ------------------- shannon(counts) #> Saliva Gums Nose Stool #> 0.74119910 0.35692121 1.10615349 0.07927797 ## Beta Diversity -------------------- bray(counts) #> Saliva Gums Nose #> Gums 0.4260870 #> Nose 0.9797101 0.9826087 #> Stool 0.9884058 0.9884058 0.9913043 ``` ### Phylogenetic Metrics A phylogenetic tree enables alpha and beta diversity metrics to take into account evolutionary relatedness between the observed genera, generally giving higher diversity values for samples with more distantly related genera. Faith (for alpha diversity) and UniFrac (for beta diversity) are examples of phylogenetic metrics. The `ex_tree` object included with ecodive provides the phylogenetic tree for the genera in `ex_counts`. For your own datasets, you can use ecodive's `read_tree()` function to import a phylogenetic tree from a newick formatted string or file. ```r ## Alpha Diversity ------------------- faith(counts, tree = ex_tree) #> Saliva Gums Nose Stool #> 180 155 101 202 ## Beta Diversity -------------------- normalized_unifrac(counts, tree = ex_tree) #> Saliva Gums Nose #> Gums 0.4328662 #> Nose 0.7928701 0.6767840 #> Stool 0.9677535 0.9829736 0.9936121 ``` ### Distance Matrices Beta diversity functions return a `dist` object. You can convert this to a standard R matrix with the `as.matrix()` function. ```r dm <- bray(counts) dm #> Saliva Gums Nose #> Gums 0.1428571 #> Nose 0.5000000 0.7142857 #> Stool 0.3333333 0.2500000 0.3333333 mtx <- as.matrix(dm) mtx #> Saliva Gums Nose Stool #> Saliva 0.0000000 0.1428571 0.5000000 0.3333333 #> Gums 0.1428571 0.0000000 0.7142857 0.2500000 #> Nose 0.5000000 0.7142857 0.0000000 0.3333333 #> Stool 0.3333333 0.2500000 0.3333333 0.0000000 mtx['Saliva', 'Nose'] #> [1] 0.5 ``` ## Performance with Large Datasets `ecodive` is designed to be fast out-of-the-box. However, if you are working with very large datasets (e.g., thousands of samples), you can gain additional performance by following the recommendations in our performance guide. * Further reading: `vignette('performance')`