--- title: "Hill numbers: taxonomic, phylogenetic and functional diversity" output: rmarkdown::html_vignette: toc: true toc_depth: 3 fig_caption: true bibliography: references.bib link-citations: true vignette: > %\VignetteIndexEntry{Hill numbers: taxonomic, phylogenetic and functional diversity} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( fig.align = "center", out.width = "100%", fig.width = 11, fig.height = 7, warning = FALSE, message = FALSE ) ``` `MicroBioMeta` computes diversity and returns the figure ready for publication. This tutorial explains the Hill-number framework and how to use it in the functions that work with it: `alpha_hill_plot()` and `alpha_diversity_plot()` for alpha diversity, and `beta_ord_plot()` and `beta_test_table()` for beta diversity. The calculations with a tree or with traits come from `hilldiv3` [@alberdi2019guide]. ## Why Hill numbers Hill numbers [@hill1973diversity; @jost2007partitioning] express diversity as an **effective number**: how many equally abundant taxa would give the same diversity as the sample. A sample with a value of 10 is twice as diverse as one with a value of 5, a statement that does not hold for the Shannon or Simpson indices. The order $q$ sets how much weight the abundances get: | Order | Weight of the taxa | Equivalent to | |---|---|---| | $q = 0$ | All count the same | Richness | | $q = 1$ | In proportion to their abundance | Exponential of Shannon | | $q = 2$ | Mostly the dominant ones | Inverse of Simpson | The same idea extends to two other dimensions of diversity [@chao2014unifying]. All three are effective numbers, in species or lineage equivalents [@chao2021measuring], but they count different things: taxa, lineages or functional groups. Always say which one you report. | `diversity` | What it takes into account | What you need | Unit | |---|---|---|---| | `"taxonomic"` | Abundances | The table | Effective number of features | | `"phylogenetic"` | How related the taxa are [@chao2010phylogenetic] | Rooted tree | Effective number of lineages | | `"functional"` | How different their traits are [@chao2019attribute] | Traits per taxon | Effective number of functional groups | ## Preparing the data We use the 18S example of the package (microbial eukaryotes, mostly fungi). ```{r data} library(MicroBioMeta) table_fungi <- read.delim( system.file("extdata", "table_fungi.txt", package = "MicroBioMeta"), row.names = 1, check.names = FALSE ) taxonomy_fungi <- read.delim( system.file("extdata", "taxonomy_fungi.txt", package = "MicroBioMeta"), check.names = FALSE ) metadata_fungi <- read.delim( system.file("extdata", "metadata_fungi.txt", package = "MicroBioMeta"), check.names = FALSE ) metadata_fungi <- metadata_fungi[metadata_fungi$SAMPLEID %in% colnames(table_fungi), ] table_fungi <- table_fungi[, metadata_fungi$SAMPLEID] table_fung <- merge_feature_taxonomy(table = table_fungi, taxonomy = taxonomy_fungi) ``` ### The tree The tip labels must be the taxa of the table. With QIIME 2 [@bolyen2019qiime2], the tree comes from the representative sequences, and `exported-tree/tree.nwk` is what you read in R: ```{bash, eval=FALSE} qiime phylogeny align-to-tree-mafft-fasttree \ --i-sequences rep-seqs.qza \ --output-dir phylogeny qiime tools export --input-path phylogeny/rooted_tree.qza --output-path exported-tree ``` ```{r tree} tree_fungi <- ape::read.tree( system.file("extdata", "tree_fungi.nwk", package = "MicroBioMeta") ) ``` Check the tree before you use it: a few spurious sequences on a very long branch can flatten $q = 1$ and $q = 2$, because that branch dominates the tree. In this example we removed three *Unassigned* ASVs (10 reads) for that reason. ### The traits `traits` is a table with taxa in rows and traits in columns. Any measured trait works. For microbial communities a common source is the table of gene families predicted per ASV by PICRUSt2 [@douglas2020picrust2], such as `EC_predicted.tsv`. Those are predictions, not measurements, so report them as such. ```{r traits} traits_fungi <- read.delim( system.file("extdata", "traits_fungi.txt", package = "MicroBioMeta"), row.names = 1, check.names = FALSE ) ``` Taxa that are in the table but not in the tree or the traits are dropped with a warning that says how many. Here that happens with the three ASVs above. ## Alpha diversity with Hill numbers `alpha_hill_plot()` uses the same call for all three types. Only `diversity` and its input change, and the y-axis title follows the unit of each type. ```{r alpha-tax} alpha_hill_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", facet_by = "Treatment", x_axis_title = "Type of soil", show_legend = FALSE, stat = "kruskal.test" ) ``` ```{r alpha-phylo, fig.height=10} alpha_hill_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", facet_by = "Treatment", x_axis_title = "Type of soil", show_legend = FALSE, stat = "kruskal.test", diversity = "phylogenetic", tree = tree_fungi ) ``` ```{r alpha-func, fig.height=10} alpha_hill_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", facet_by = "Treatment", x_axis_title = "Type of soil", show_legend = FALSE, stat = "kruskal.test", diversity = "functional", traits = traits_fungi ) ``` Two details of these values: - The phylogenetic values are read at one common depth, the mean tree depth of the samples [@chiu2014phylogenetic], so samples are comparable. For that reason a sample can fall slightly below 1. `iNEXT.3D` uses the age of the root instead, so its values are not the same. - Functional values depend on a threshold $\tau$: taxa at that distance or more count as different functional groups. By default it is the mean distance between two reads of the pooled samples [@chao2019attribute], and you can change it with `tau`. ## Classic indices `alpha_diversity_plot()` shows the classic indices, also with `diversity`: | `diversity` | Index | Meaning | Unit | |---|---|---|---| | `"taxonomic"` | Chao1, Shannon, Simpson | Richness and evenness | Different in each index | | `"phylogenetic"` | Faith's PD [@faith1992conservation] | Summed branch length up to the root | Branch length | | `"functional"` | Rao's Q [@rao1982diversity] | Mean distance between two random reads | Distance (Gower) | ```{r classic-phylo, fig.width=4.5, fig.height=4.5, out.width="50%"} alpha_diversity_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", x_axis_title = "Type of soil", show_legend = FALSE, stat = "kruskal.test", diversity = "phylogenetic", tree = tree_fungi ) ``` ```{r classic-func, fig.width=4.5, fig.height=4.5, out.width="50%"} alpha_diversity_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", x_axis_title = "Type of soil", show_legend = FALSE, stat = "kruskal.test", diversity = "functional", traits = traits_fungi ) ``` These indices are related to the Hill numbers but they are not the same quantity. Faith's PD is the phylogenetic $q = 0$ before dividing by the depth of the tree, and Rao's Q gives the functional $q = 2$ through $1 / (1 - Q / \tau)$ when $\tau$ is the largest distance between two taxa. Choose the classic index if you need to compare with studies that report it, and the Hill number if you want every type in the same framework. ## Beta diversity ### The metrics `hilldiv3::hillpair()` turns the Hill numbers into dissimilarities between samples [@jost2007partitioning; @chiu2014phylogenetic; @chao2023rarefaction]. In `MicroBioMeta` they are one more option of `distance`, next to `"jaccard"` or `"aitchison"`, with the order set by `q`. They range from 0 (identical samples) to 1 (nothing shared), so they have no unit problem. | `distance` | Type | Taxonomic: $q = 0$, $1$, $2$ | Phylogenetic: $q = 0$, $1$, $2$ | |---|---|---|---| | `"U"` | Jaccard type | Jaccard, Horn, regional overlap | Phylo-Jaccard (unweighted UniFrac), phylo-Horn, phylo-regional-overlap | | `"C"` | Sørensen type | Sørensen, Horn, Morisita-Horn | Phylo-Sørensen (PhyloSor), phylo-Horn, phylo-Morisita-Horn | | `"S"` | Jaccard-type turnover | Jaccard, no name, Morisita-Horn | Phylo-Jaccard, no name, phylo-Morisita-Horn | | `"V"` | Sørensen-type turnover | Sørensen, no name, no name | Phylo-Sørensen, no name, no name | The phylogenetic names come from @chiu2014phylogenetic, and PhyloSor from @bryant2008microbes; UniFrac is from @lozupone2005unifrac. The functional versions have no names of their own: @chao2019attribute calls them Sørensen-type and Jaccard-type functional measures, so report them that way, with $q$ and $\tau$. At $q = 1$, `"U"` is phylo-Horn, not the weighted UniFrac. These metrics describe the differences in Hill-number terms; they are not compositional. If your main analysis uses CLR/Aitchison, keep it there and use these as a complement. ### Ordination The Hill metrics work with `ordination = "PCoA"` or `"NMDS"`, the same as any distance that is not `"compositional"`. `beta_ord_plot()` keeps the same scale on both axes, so the plot gets flat when the first axis explains most of the variation. In the functional example we add `ggplot2::coord_cartesian()` to fill the figure; keep in mind that the axes no longer share a scale. ```{r ord-tax, fig.height=5} beta_ord_plot( table = table_fung, metadata = metadata_fungi, distance = "U", q = 1, ordination = "PCoA", group_col = "Type_of_soil", legend_title = "Type of soil" ) ``` ```{r ord-phylo, fig.height=5} beta_ord_plot( table = table_fung, metadata = metadata_fungi, distance = "U", q = 1, ordination = "PCoA", group_col = "Type_of_soil", legend_title = "Type of soil", diversity = "phylogenetic", tree = tree_fungi ) ``` ```{r ord-func, fig.width=7.5, fig.height=6.5, out.width="75%"} beta_ord_plot( table = table_fung, metadata = metadata_fungi, distance = "U", q = 1, ordination = "PCoA", group_col = "Type_of_soil", legend_title = "Type of soil", diversity = "functional", traits = traits_fungi ) + ggplot2::coord_cartesian() ``` ### PERMANOVA and betadisper `beta_test_table()` takes the same arguments. A PERMANOVA [@anderson2001permanova] tests whether the groups differ, and betadisper [@anderson2006distance] whether their dispersion does. Report both: a significant PERMANOVA with unequal dispersions may reflect differences in dispersion, not in position. We use $q = 1$ and the same model for all three types. At that order soil and treatment differ in all of them, and the interaction only in the phylogenetic one. Taxonomic: ```{r permanova-tax, fig.width=6.5, fig.height=2, out.width="65%"} beta_test_table( table = table_fung, metadata = metadata_fungi, formula_str = "Type_of_soil * Treatment", distance = "U", q = 1 ) ``` Phylogenetic: ```{r permanova-phylo, fig.width=6.5, fig.height=2, out.width="65%"} beta_test_table( table = table_fung, metadata = metadata_fungi, formula_str = "Type_of_soil * Treatment", distance = "U", q = 1, diversity = "phylogenetic", tree = tree_fungi ) ``` Functional: ```{r permanova-func, fig.width=6.5, fig.height=2, out.width="65%"} beta_test_table( table = table_fung, metadata = metadata_fungi, formula_str = "Type_of_soil * Treatment", distance = "U", q = 1, diversity = "functional", traits = traits_fungi ) ``` `test = "betadisper"` works the same way for the three types. Here is the phylogenetic one. At $q = 1$ the dispersions differ between types of soil in all three, so read the PERMANOVA of `Type_of_soil` with that in mind. ```{r betadisper, fig.width=6.5, fig.height=1.2, out.width="65%"} beta_test_table( table = table_fung, metadata = metadata_fungi, formula_str = "Type_of_soil", distance = "U", q = 1, test = "betadisper", diversity = "phylogenetic", tree = tree_fungi ) ``` ## References
## Session info ```{r session} sessionInfo() ```