--- title: "Metabarcoding" output: rmarkdown::html_vignette: toc: true toc_depth: 3 fig_caption: true bibliography: references.bib link-citations: true vignette: > %\VignetteIndexEntry{Metabarcoding} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( fig.align = "center", out.width = "100%", fig.width = 7, fig.height = 5, dpi = 96 ) ``` 🧬 MicroBioMeta is an R package to explore, analyze and visualize microbiome data. This tutorial walks through an example of its use with metabarcoding data. ## Installation `MicroBioMeta` is not on Bioconductor yet. For now, install it from GitHub: ```{r install-github, eval=FALSE} # install.packages("remotes") remotes::install_github("Steph0522/MicroBioMeta") ``` Once it is accepted in Bioconductor, it will be installed with: ```{r install-bioc, eval=FALSE} if (!requireNamespace("BiocManager", quietly = TRUE)) { install.packages("BiocManager") } BiocManager::install("MicroBioMeta") ``` ## Example data For this example, we will use data sequenced using the 16S barcode for bacteria and 18S barcode for microbial eukaryotes (mostly fungi, but also ciliates, cercozoans and other protists). The data is taken from: For 16S 🦠: [Hereira-Pacheco, S.E., Navarro-Noya, Y.E. & Dendooven, L. The root endophytic bacterial community of Ricinus communis L. resembles the seeds community more than the rhizosphere bacteria independent of soil water content. Sci Rep 11, 2173 (2021). https://doi.org/10.1038/s41598-021-81551-7](https://doi.org/10.1038/s41598-021-81551-7) For 18S: [Hereira-Pacheco, S. E., Estrada-Torres, A., Dendooven, L., & Navarro-Noya, Y. E. (2023). Shifts in root-associated fungal communities under drought conditions in Ricinus communis. Fungal Ecology, 63, 101225.](https://www.sciencedirect.com/science/article/abs/pii/S1754504823000028) ## Loading data First, let's load the `MicroBioMeta` package: ```{r load, message=FALSE} library("MicroBioMeta") ``` Let's also load the other packages we'll need: ```{r data-1, warning=FALSE, message=FALSE} library(tidyverse) ``` [`tidyverse`](https://tidyverse.org/) is used for all the data wrangling and visualizations. Next, we load the data and reformat it. This dataset was processed in [`QIIME2`](https://qiime2.org/) [@bolyen2019qiime2], so its `.qza` artifacts were originally imported into R with the [`qiime2R`](https://github.com/jbisanz/qiime2R) package [@bisanz2018qiime2r] (MIT License, © 2018 Jordan Bisanz), whose `read_qza()` `MicroBioMeta`'s own taxonomy parser is adapted from. If you have your own `.qza` artifacts, `qiime2R::read_qza()` (`devtools::install_github("jbisanz/qiime2R")`) is the way to bring them into R. For this vignette, that same data is shipped with the package already exported as plain `.txt` files (under `inst/extdata/`), so building it doesn't require `qiime2R` (a GitHub-only package) to be installed: First, let's load all the table and taxonomy data for each data set: ```{r data-2} bacteria_table <- read.delim( system.file("extdata", "table_bacteria.txt", package = "MicroBioMeta"), row.names = 1, check.names = FALSE ) fungi_table <- read.delim( system.file("extdata", "table_fungi.txt", package = "MicroBioMeta"), row.names = 1, check.names = FALSE ) taxonomy_bacteria <- read.delim( system.file("extdata", "taxonomy_bacteria.txt", package = "MicroBioMeta"), check.names = FALSE ) %>% rename(taxonomy = Taxon) %>% dplyr::select(-Confidence) %>% column_to_rownames(var = "Feature.ID") taxonomy_fungi <- read.delim( system.file("extdata", "taxonomy_fungi.txt", package = "MicroBioMeta"), check.names = FALSE ) %>% rename(taxonomy = Taxon) %>% dplyr::select(-Consensus) %>% column_to_rownames(var = "Feature.ID") ``` ⚠️ Let's notice that we renamed the column called Taxon for taxonomy before join this two data: ```{r data-3} colnames(taxonomy_bacteria) ``` Now, let's call the metadata for data set: ```{r data-4} bacteria_metadata <- read.delim( system.file("extdata", "metadata_bacteria.txt", package = "MicroBioMeta"), check.names = FALSE ) %>% filter(Month == "2") fungi_metadata <- read.delim( system.file("extdata", "metadata_fungi.txt", package = "MicroBioMeta"), check.names = FALSE ) ``` Then, let's filter and manage the data. It is good practice to use a table and metadata that contain the same samples, in the same order. So basically at this point, we are going to filter tables to match with the metadata. For bacteria: ```{r data-5} samples_bac <- bacteria_metadata$SAMPLEID[ bacteria_metadata$SAMPLEID %in% colnames(bacteria_table) ] table_bacteria <- bacteria_table[, samples_bac] metadata_bacteria <- bacteria_metadata[ bacteria_metadata$SAMPLEID %in% samples_bac, ] ``` and for microbial eukaryotes: ```{r data-6} samples_fun <- fungi_metadata$SAMPLEID[ fungi_metadata$SAMPLEID %in% colnames(fungi_table) ] table_fungi <- fungi_table[, samples_fun] metadata_fungi <- fungi_metadata[ fungi_metadata$SAMPLEID %in% samples_fun, ] ``` ## Pre-processing data `MicroBioMeta` functions need the data in `biom` format (taxa in rows, samples in columns), with a **taxonomy** column at the end. If your data is not already in that form, `merge_feature_taxonomy()` combines an abundance table and a taxonomy table into this format. Keeping taxonomy as a column of the same table means most functions can look up taxonomic identity without requiring a separate object. ```{r prep} table_bac <- merge_feature_taxonomy( table = table_bacteria, taxonomy = taxonomy_bacteria ) table_fung <- merge_feature_taxonomy( table = table_fungi, taxonomy = taxonomy_fungi ) ``` ⚠️ Notice that this warning reports how many taxonomy IDs did not match the feature table and were excluded from the result. ⚠️ Every function that uses the taxonomy shows bacterial phyla with their validly published names (e.g. *Proteobacteria* as *Pseudomonadota*, *Firmicutes* as *Bacillota*, *Actinobacteriota* as *Actinomycetota*), the names used by NCBI Taxonomy since 2021. A message lists the names that were changed (once per session). ## Composition exploration `MicroBioMeta` has several functions to explore composition, taxonomic identity, and abundance. Let's explore each of them. ### Abundance barplots Abundance barplots are useful to identify patterns in community composition based on taxonomic identity.\ This function generates stacked barplots of relative abundances using an abundance table and a metadata file as input. The `taxonomy_db` parameter specifies the taxonomic reference database used for taxonomic assignment: `"silva"` (default), `"gg2"` (Greengenes2), `"unite"` or `"Kraken2"`.\ The `x_col` parameter indicates the column in the metadata used for grouping samples along the x-axis, while `facet_by` defines the metadata column used to split the plot into facets. The `level` parameter allows us to choose the taxonomic level to collapse. The `top_n` parameter controls the number of most abundant taxa displayed in the barplot. If `add_remained = TRUE`, the relative abundances are completed to 100% by adding a gray category representing the remaining taxa not explicitly displayed; if `FALSE`, only the selected taxa are shown.\ The `label` parameter defines the legend title displayed in the plot. The x-axis tick labels can be rotated with `x_label_angle` (default `0`, horizontal), useful when sample or group names are long enough to overlap, as in the examples below. `strip_text_bold` controls whether facet strip titles are bold (default `FALSE`), and `aspect_ratio` fixes the height/width ratio of the panel when you need consistent proportions across figures. Finally, when `save_table = TRUE`, the function also saves a tab-delimited file (named with `table_filename`) with the relative abundances (percentages) used to generate the plot. ```{r bar-1, fig.width=9, fig.height=6} abundance_bar_plot( table = table_bac, metadata = metadata_bacteria, taxonomy_db = "silva", level = "phylum", top_n = 15, x_col = "Type_of_soil", facet_by = "Treatment", add_remained = TRUE, label = "Phylum", x_label_angle = 45, save_table = FALSE ) ``` ```{r bar-2, fig.width=9, fig.height=6} abundance_bar_plot( table = table_fung, metadata = metadata_fungi, x_col = "Treatment", facet_by = "Type_of_soil", add_remained = TRUE, label = "Genera", x_label_angle = 45, save_table = FALSE ) ``` `palette` changes the colors of the taxa: `"default"` (the bright colors above), `"brewer"` (the qualitative RColorBrewer palettes joined, without greys; many distinct colors, but not colorblind-friendly) or `"safe"` (the colorblind-friendly "Safe" palette; it has 11 colors, so keep `top_n` at 11 or less, otherwise the colors are interpolated). The most abundant taxon gets the first color. `taxa_colors` fixes the color of specific taxa (a named vector, e.g. `c(Fusarium = "#E31A1C")`), which keeps the same color for a taxon across figures: ```{r bar-3, fig.width=9, fig.height=6} abundance_bar_plot( table = table_fung, metadata = metadata_fungi, x_col = "Treatment", facet_by = "Type_of_soil", add_remained = TRUE, label = "Genera", x_label_angle = 45, palette = "brewer" ) ``` ```{r bar-4, fig.width=9, fig.height=6} abundance_bar_plot( table = table_fung, metadata = metadata_fungi, x_col = "Treatment", facet_by = "Type_of_soil", top_n = 10, add_remained = TRUE, label = "Genera", x_label_angle = 45, palette = "safe" ) ``` ### Abundance heatmaps Notice that the input files are the same as the previous function and this is consistent with all functions from now on. The parameters `condition1`, `condition2`, and `condition3` define the three metadata variables to be displayed as horizontal annotations above the heatmap.\ Custom color palettes for each annotation can be specified using `colors_condition1`, `colors_condition2`, and `colors_condition3`, respectively.\ Legend titles for these annotations can be customized with `name_legend_condition1`, `name_legend_condition2`, and `name_legend_condition3`. The `top_n` argument controls the number of most abundant features included in the heatmap.\ If `cluster = TRUE`, rows are hierarchically clustered; if `FALSE`, features are ordered by decreasing relative abundance.\ The `show_column_names` parameter determines whether sample names are displayed in the heatmap. Row labels default to just the feature's rank number (`"1"`, `"2"`...); `feature_prefix` prepends whatever fits the data - `"ASV"` here, since this table's features are QIIME2/DADA2 amplicon sequence variants. SILVA composite names of three or more genera are shortened to the last genus plus "group" (e.g. *Allorhizobium-Neorhizobium-Pararhizobium-Rhizobium* is shown as "Rhizobium group"; two-genus names such as *Escherichia-Shigella* stay whole), here and in the barplots, Sankey diagrams and ALDEx2 figures. Other labels longer than `max_label_length` (default `35`) characters are cut with "...". Set `composite_names = FALSE` to show the full names. The soil types keep the package's default colorblind-friendly Okabe-Ito colors (Bulk soil orange, Rhizosphere blue, Roots green, Uncultivated yellow). For the treatments we use colors from the colorblind-friendly "Safe" palette, so the two variables don't share colors: ```{r colors} treatment_colors <- c(TC = "#CC6677", TD = "#332288", TED = "#999933") ``` ```{r heat-1, warning=FALSE, fig.width=14, fig.height=6} abundance_heatmap_plot( table = table_bac, metadata = metadata_bacteria, top_n = 20, show_column_names = FALSE, condition1 = "Type_of_soil", condition2 = "Treatment", colors_condition2 = treatment_colors, feature_prefix = "ASV" ) ``` ```{r heat-2, warning=FALSE, fig.width=14, fig.height=6} abundance_heatmap_plot( table = table_fung, metadata = metadata_fungi, top_n = 20, show_column_names = FALSE, condition1 = "Type_of_soil", condition2 = "Treatment", colors_condition2 = treatment_colors, feature_prefix = "ASV" ) ``` ### Sankey diagram of taxonomic flow `abundance_sankey_plot()` visualizes how relative abundance flows across taxonomic ranks: from Kingdom to Species as an interactive Sankey diagram. It is useful for getting a quick overview of which lineages dominate the community. The `taxRanks` argument specifies which ranks to include as nodes, `maxn` caps the number of taxa kept per rank and `taxonomy_db` tells the function how the taxonomy strings are formatted (e.g. `"silva"`, `"gg"`, `"kraken2"`). This function depends on [`networkD3`](https://CRAN.R-project.org/package=networkD3), available on CRAN: ```{r sankey-1, eval=FALSE} install.packages("networkD3") ``` ⚠️ Unlike the other functions, this one doesn't return a `ggplot` object but an interactive `sankeyNetwork` (htmlwidget) object. Nothing is written to disk by default; set `output_file` (e.g. `output_file = "sankey_bacteria.html"`) to **save the diagram as an HTML file**. ```{r sankey-2, warning=FALSE} sankey_bacteria <- abundance_sankey_plot( table = table_bac, maxn = 10, width = 950, height = 650, taxRanks = c("P", "C", "O", "F", "G"), taxonomy_db = "silva" ) sankey_bacteria ``` ## Alpha diversity Alpha diversity describes the diversity within individual samples. With `MicroBioMeta`, alpha diversity can be explored using several different metrics, like classic metrics such as Chao1 and Simpson. Also, the package implements functions based on the **Hill numbers framework** [@chao2014hill; @li2018hillr], which provides a unified way to represent different units. Hill numbers are parameterized by the order *q*, which regulates the weight given to the abundance. For example, *q*=0 corresponds to species richness (total species), *q*=1 to the exponential of Shannon entropy (frequent species), and *q*=2 to the inverse Simpson index (dominant species). ### Correlation among Hill numbers The `alpha_hill_corr_plot()` function calculates Hill numbers for different orders (typically, 𝑞=0,1,2) and visualizes the correlations among them using a correlation plot, and evaluates how strongly diversity metrics of different orders are related to the sequencing depth. This is the first step before analyzing alpha diversity metrics. For the bacteria 🦠, we can observe that at all orders of *q* there is a strong correlation with sequencing depth. When this happens, differences in diversity between samples may partly reflect differences in sequencing effort, so it is worth keeping in mind (or rarefying) before comparing groups. ```{r hill-corr, warning=FALSE, fig.width=12, fig.height=4.5} alpha_hill_corr_plot(table = table_bac) ``` ### Alpha diversity visualization The `alpha_hill_plot()` function calculates Hill numbers and visualizes alpha diversity patterns across experimental conditions using boxplots. The `x_col` parameter specifies the metadata column used on the x-axis, while `fill_col` controls the grouping used to color the boxplots. The `facet_by` argument allows splitting the plot according to a metadata variable, and `facet_orientation` controls whether facets are arranged horizontally or vertically. If `save_table = TRUE`, the function also saves a tab-delimited file with the alpha diversity values calculated for each sample. ```{r alpha-1, warning=FALSE, fig.width=9, fig.height=8} alpha_hill_plot( table = table_bac, metadata = metadata_bacteria, x_col = "Treatment", fill_col = "Treatment", group_colors = treatment_colors, facet_by = "Type_of_soil", facet_orientation = "horizontal", save_table = FALSE ) ``` The same function can swap the roles of the variables. For the microbial eukaryotes we put the soil compartment on the x-axis and split the panels by treatment, which highlights how diversity changes from bulk soil to roots within each treatment: ```{r alpha-2, warning=FALSE, fig.width=9, fig.height=7} alpha_hill_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", facet_by = "Treatment", facet_orientation = "horizontal", show_legend = FALSE, save_table = FALSE ) ``` `palette` sets the group colors in `alpha_hill_plot()`, `alpha_diversity_plot()`, `alpha_decay_plot()`, `beta_ord_plot()` and `beta_decay_plot()`: `"colorb"` (default, the colorblind-friendly Okabe-Ito palette), `"safe"` (the colorblind-friendly CARTO "Safe" palette; as in `rcartocolor::carto_pal()`, with 3 to 11 groups the last one is grey), `"earth"` (CARTO "Earth", brown to teal; best for two groups or ordered groups, since the middle colors are pale), `"grey"`, `"viridis"` or `"brewer"`. `group_colors` overrides `palette` with your own colors. Here the microbial eukaryote example above with `"safe"`: ```{r alpha-pal, warning=FALSE, fig.width=9, fig.height=7} alpha_hill_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", facet_by = "Treatment", facet_orientation = "horizontal", show_legend = FALSE, palette = "safe" ) ``` Also, we can visualize other metrics considering classic alpha diversity indexes: ```{r alpha-3, warning=FALSE, fig.width=9, fig.height=7} alpha_diversity_plot( table = table_fung, metadata = metadata_fungi, x_col = "Treatment", fill_col = "Treatment", group_colors = treatment_colors, facet_by = "Type_of_soil", facet_orientation = "horizontal", stat = "anova", free_y = TRUE, save_table = FALSE ) ``` Each panel is automatically labeled (A, B, C, ...) so it can be referenced. When `stat` is set, p-values are added to each panel as well. `"wilcox.test"` or `"t.test"` compare every pair of groups, each with its own bracket, and correct the p-values for multiple comparisons within the panel with `p_adjust_method` (default `"holm"`; `"none"` shows the raw p-values). `"kruskal.test"` or `"anova"` give one global p-value per panel. Only significant comparisons are drawn. `panel_label_case` switches between upper and lowercase labels, `panel_label_bold` for bold labels and `panel_labels` lets you supply custom labels(e.g. `c("(a)", "(b)", "(c)")`) instead of the auto-generated ones. `free_y` lets each panel use its own y-axis scale instead of a shared one, as below: ```{r alpha-4, warning=FALSE, fig.width=9, fig.height=7} alpha_diversity_plot( table = table_fung, metadata = metadata_fungi, x_col = "Treatment", fill_col = "Treatment", group_colors = treatment_colors, facet_by = "Type_of_soil", facet_orientation = "horizontal", stat = "anova", free_y = TRUE, x_label_angle = 45, panel_label_bold = FALSE, save_table = FALSE ) ``` With `facet_orientation = "vertical"` the Hill orders (*q*) go in rows and the `facet_by` groups in columns: ```{r alpha-vertical, warning=FALSE, fig.width=8, fig.height=8} alpha_hill_plot( table = table_fung, metadata = metadata_fungi, x_col = "Type_of_soil", fill_col = "Type_of_soil", facet_by = "Treatment", facet_orientation = "vertical", show_legend = FALSE, save_table = FALSE ) ``` ### Alpha diversity along a continuous gradient `alpha_decay_plot()` regresses Hill numbers against a **continuous** metadata variable (e.g. pH, elevation, distance). Each Hill order (*q*=0, 1, 2) gets its own panel with a regression line and an annotation reporting the correlation coefficient (Spearman's rho by default), its p-value and, when `show_lm_stats = TRUE`, the linear model's R² and slope. The `cont_var` parameter names the continuous metadata column to place on the x-axis, and the optional `group_col` fits a separate regression line per group instead of a single global one. Here we use soil `pH` as the gradient, restricted to `Bulk soil` and `Rhizosphere` for a cleaner comparison: ```{r alpha-gradient, warning=FALSE, fig.height=4, fig.width=10} metadata_bacteria_decay <- metadata_bacteria %>% filter(Type_of_soil %in% c("Bulk soil", "Rhizosphere")) alpha_decay_plot( table = table_bac, metadata = metadata_bacteria_decay, cont_var = "pH", group_col = "Type_of_soil", x_axis_title = "Soil pH" ) ``` ### Shared taxa between sample groups Another way to explore alpha diversity patterns is by examining **which taxa are shared or unique among groups of samples**. The function `venn_plot()` generates Venn diagrams that summarize the overlap of taxa between groups defined in the metadata. We generate a Venn diagram grouping samples according to the treatment (TC, TD and TED). ```{r venn, fig.width=5, fig.height=4} venn_plot( table = table_fung, metadata = metadata_fungi, merge_by = "Treatment", min_prevalence = 0 ) ``` #### Collapsing the table by taxonomic level Microbial community tables are often generated at the **ASV or OTU level**, which can contain hundreds or thousands of features. For interpretation and visualization, it is often useful to group these features at a higher **taxonomic level**, such as genus. The function `collapse_table()` performs this aggregation by grouping features that are at the same taxonomy level and summing their counts. The function returns a **list with two elements**: - **`collapsed_table`**: a wide-format abundance table where rows correspond to taxa collapsed at the selected level and columns correspond to samples. - **`long_format`**: the same information in long format, which is useful for downstream plotting or statistical analyses. For example, the following code collapses the microbial eukaryote abundance table to the **genus level**, and then we make a Venn diagram to visualize the shared genera. ```{r collapse, fig.width=7, fig.height=6} table_genus <- collapse_table( table = table_fung, level = "genus" ) venn_plot( table = table_genus$collapsed_table, metadata = metadata_fungi, merge_by = "Treatment" ) ``` By default, `collapse_table()` returns the **raw counts** summed at the selected taxonomic level. However, microbial community data are often visualized or analyzed as **relative abundance**. Setting `rel_abun = TRUE` converts the counts of each sample into **percentages**, where the total abundance per sample sums to 100%. #### Filtering taxa by prevalence Sometimes it is useful to visualize only taxa that occur frequently within each group. This can be done using the `min_prevalence` parameter. For example, the following diagram includes only taxa present in **at least 20% of the samples within each group**. The default is 0, which means that no filtering is applied. ```{r prevalence, fig.width=5, fig.height=4} venn_plot( table = table_fung, metadata = metadata_fungi, merge_by = "Treatment", min_prevalence = 0.2 ) ``` #### Customizing group colors The function also allows custom colors for the groups. ```{r venn-colors, fig.width=5, fig.height=4} venn_plot( table = table_fung, metadata = metadata_fungi, merge_by = "Treatment", min_prevalence = 0, group_colors = treatment_colors ) ``` #### Alternative plotting method By default the function uses the package **ggvenn**, but it can also generate the diagram using **ggVennDiagram**. ```{r venn-alt, fig.width=5, fig.height=4} venn_plot( table = table_fung, metadata = metadata_fungi, merge_by = "Treatment", method = "ggvenndiagram" ) ``` ## Beta diversity Beta diversity describes the differences in community composition and structure among samples. These analyses help determine whether microbial communities vary across environmental conditions, treatments, or experimental groups, and how samples cluster or group. `MicroBioMeta` has several functions to explore beta diversity, including ordination plots, statistical tests for community differences and partitioning approaches that separate shared and unique components of diversity. These functions allow both visual exploration and formal hypothesis testing. ### Ordination of community composition The `beta_ord_plot()` function calculates pairwise dissimilarities among samples and visualizes the results using an ordination method. By default, the function uses common ecological distance metrics (e.g., Bray–Curtis or Euclidean) and dimensionality reduction techniques such as **PCoA**, **PCA**, or **NMDS**. To account for the compositional nature of the data, the `aitchison` and `compositional` distances can be used. `compositional` uses the *clr* (centered log-ratio) transformation computed by the `ALDEx2` package. The `group_col` parameter specifies the metadata column used to color the samples, while `shape_col` allows an additional metadata variable to be displayed using different point shapes. The `distance` argument defines the dissimilarity metric used to calculate beta diversity (e.g., **bray, jaccard, aitchison**, etc.), and `ordination` (options: **PCA, PCoA** or **NMDS**) specifies the ordination method applied to visualize the distances among samples. ⚠️ **NOTE: `distance = "compositional"` uses one of the Monte Carlo instances that `ALDEx2` draws at random, so the result changes slightly from run to run. If you want to get the same result every time, we suggest running `set.seed()` before the function**, as in the examples below. The same applies to `beta_test_table(distance = "compositional")`, to the ALDEx2 functions and to the p-values of `cca_rda_biplot()`. By default (`mc_samples = 1`) a single instance is used, which is fast; for final analyses we suggest `mc_samples = 128` (ALDEx2's default), which averages the clr values over 128 instances and gives almost the same result in every run, at the cost of a longer computation. ```{r ord-1, warning=FALSE, message=FALSE, fig.width=8, fig.height=6} set.seed(123) beta_ord_plot( table = table_bac, metadata = metadata_bacteria, distance = "compositional", mc_samples = 128, ordination = "PCA", group_col = "Type_of_soil", shape_col = "Treatment" ) ``` For the microbial eukaryotes we use a different combination: the **Aitchison** distance (Euclidean distance between clr-transformed abundances, with a pseudocount of 0.5 for the zeros), which respects the compositional nature of the data, with an **NMDS** ordination. NMDS starts from random configurations, so `set.seed()` is used here too: ```{r ord-2, fig.width=8, fig.height=6} set.seed(123) beta_ord_plot( table = table_fung, metadata = metadata_fungi, group_col = "Type_of_soil", shape_col = "Treatment", distance = "aitchison", ordination = "NMDS" ) ``` The same `palette` options apply to the ordination. With `"earth"` and two groups (here only rhizosphere and roots) the samples are brown and teal: ```{r ord-pal, fig.width=8, fig.height=6} set.seed(123) two_soils <- metadata_fungi[metadata_fungi$Type_of_soil %in% c("Rhizosphere", "Roots"), ] beta_ord_plot( table = table_fung, metadata = two_soils, group_col = "Type_of_soil", shape_col = "Treatment", distance = "aitchison", ordination = "NMDS", palette = "earth" ) ``` ### Statistical tests for beta diversity The `beta_test_table()` function performs statistical tests to evaluate whether community composition differs among experimental groups. The `formula_str` argument specifies the experimental design using a formula syntax similar to linear models in R or as it is used for the `vegan` package [@oksanen2024vegan]. The `distance` parameter defines the distance metric used to calculate dissimilarities, and the `test` argument specifies the statistical test (options: **PERMANOVA** [@anderson2001permanova] or **BETADISPER**). The `permutations` parameter determines the number of permutations used to estimate statistical significance. The `strata_var` is used as in `vegan` package to block for a parameter. The first column of `metadata` must hold the sample IDs. The functions never match samples by position: metadata rows are matched to the table by ID (and reordered if needed, with a message), samples missing from the metadata are left out with a message, and the function stops if no ID matches. This applies to the functions that run PERMANOVA, betadisper, ALDEx2, CCA/RDA or random forest. `table` can also be a precomputed distance (e.g. from `vegan::vegdist()`), which is used as-is. ⚠️ **NOTE: Each function has a `save_table` option that saves the values behind the plot as a tab-delimited file**. `distance` matches the ordination of each dataset above (`compositional` for bacteria, `aitchison` for microbial eukaryotes), so the significance test evaluates the same notion of dissimilarity shown in the plot. The result is a table figure (a ggplot), so it can be combined with other plots (e.g. `cowplot::plot_grid()`) or saved with `ggplot2::ggsave()`. Use `save_table = TRUE` to also get the results as a text file. ```{r permanova-1, fig.width=8, fig.height=4} set.seed(123) beta_test_table( table = table_bac, metadata = metadata_bacteria, formula_str = "Type_of_soil*Treatment", distance = "compositional", mc_samples = 128, test = "permanova", permutations = 999 ) ``` ```{r permanova-2, fig.width=8, fig.height=4} set.seed(123) beta_test_table( table = table_fung, metadata = metadata_fungi, formula_str = "Type_of_soil*Treatment", distance = "aitchison", test = "permanova", permutations = 999 ) ``` ### Beta diversity partitioning Beta diversity can also be decomposed into different components. The `beta_partition_ord_plot()` function partitions beta diversity into the turnover and nestedness components based on selected dissimilarity indices [@baselga2012betapart]. The `family` argument specifies the dissimilarity family used for the partition (e.g., Jaccard or Sørensen). The `group_col` and `shape_col` parameters define how samples are visualized according to metadata variables. ```{r partition-1, fig.width=14, fig.height=5.5} beta_partition_ord_plot( table = table_bac, metadata = metadata_bacteria, family = "jaccard", group_col = "Type_of_soil", shape_col = "Treatment", save_table = FALSE ) ``` ```{r partition-2, fig.width=14, fig.height=5.5} beta_partition_ord_plot( table = table_fung, metadata = metadata_fungi, family = "jaccard", group_col = "Type_of_soil", shape_col = "Treatment", save_table = FALSE ) ``` ### Pairwise beta diversity visualization The `beta_dissimilarity_plot()` function summarizes pairwise beta diversity values using boxplots, allowing comparison of diversity patterns among groups of samples. This function uses betapart on incidence data using Sorensen or Jaccard index: shared, turnover or nestedness. The `condition1_col` and `condition2_col` parameters specify metadata variables used to define the groups being compared. `condition2_col` splits the comparisons into facets: each facet keeps only pairs of samples from the same value (e.g. both samples from treatment TC), so treatments are not mixed. The `partition` argument determines which component of beta diversity is displayed (`"shared"`, `"turnover"` or `"nestedness"`), while `family` defines the dissimilarity index used. By default `beta_dissimilarity_plot()` keeps every pairwise combination possible of `condition1_col`, including a group compared against itself (e.g. `"Roots_vs_Roots"`). The `comparison_condition1` argument restricts the plot to specific `"value1_vs_value2"` labels (the two values sorted alphabetically and joined with `"_vs_"`). Here we build that list programmatically to keep only the comparisons of every other compartment **against Roots**, dropping self-comparisons: ```{r dissim-1} groups_bac <- setdiff(unique(as.character(metadata_bacteria$Type_of_soil)), "Roots") vs_roots_bac <- paste0(pmin(groups_bac, "Roots"), "_vs_", pmax(groups_bac, "Roots")) # each comparison takes the color of the group compared with Roots vs_roots_colors <- c( "Bulk soil_vs_Roots" = "#E69F00", "Rhizosphere_vs_Roots" = "#56B4E9", "Roots_vs_Uncultivated" = "#F0E442" ) vs_roots_bac ``` As with the alpha diversity plots, `x_label_angle` rotates the x-axis tick labels (default `0`), `strip_text_bold` toggles bold facet strip titles (default `FALSE`), and `aspect_ratio` fixes the panel's height/width ratio. As with the alpha plots, `stat` (e.g. `"wilcox.test"`, `"kruskal.test"`, `"anova"`) adds a statistical comparison across the boxplots of each facet, with the same pairwise or global behavior and `p_adjust_method` as in the alpha plots. If `save_table = TRUE`, the function also saves a tab-delimited file with the beta diversity values used to generate the plot. ```{r dissim-2, fig.width=9, fig.height=6} beta_dissimilarity_plot( table = table_bac, metadata = metadata_bacteria, comparison_condition1 = vs_roots_bac, group_colors = vs_roots_colors, condition1_col = "Type_of_soil", condition2_col = "Treatment", x_axis_title = "Samples", show_x_labels = FALSE, stat = "kruskal.test", partition = "shared", family = "jaccard", save_table = FALSE ) ``` For the microbial eukaryotes we look at a different component: `partition = "turnover"` keeps only the replacement of taxa between samples (not the differences due to one sample holding a subset of the other), here with the Sørensen family: ```{r dissim-3} groups_fung <- setdiff(unique(as.character(metadata_fungi$Type_of_soil)), "Roots") vs_roots_fung <- paste0(pmin(groups_fung, "Roots"), "_vs_", pmax(groups_fung, "Roots")) ``` ```{r dissim-4, fig.width=9, fig.height=6} beta_dissimilarity_plot( table = table_fung, metadata = metadata_fungi, comparison_condition1 = vs_roots_fung, group_colors = vs_roots_colors, condition1_col = "Type_of_soil", condition2_col = "Treatment", x_axis_title = "Samples", show_x_labels = FALSE, stat = "kruskal.test", partition = "turnover", family = "sorensen", save_table = FALSE ) ``` ### Pairwise turnover: between-group vs. within-group `beta_turnover_plot()` reports the ASV turnover component of Hill-number-based beta diversity (*q*=0, 1, 2), one facet row per Hill order. `beta_turnover_plot()` answers a different question than `beta_dissimilarity_plot()`: for **one reference group** (e.g. Rhizosphere), is its turnover **against another group** (e.g. Roots, a between-group comparison) greater than its turnover **against itself** (Rhizosphere-vs-Rhizosphere pairs, a within-group baseline)? If between-group turnover is significantly higher, that's evidence the two compartments really do host distinct communities, beyond the variability already present among replicates of the same compartment. So the plot below has one purple (this color can be set) strip on top per treatment (**TC**, **TD**, **TED**: only `condition2_col` is given, so each facet keeps the pairs of samples from that same treatment) and, inside each, two boxes: **"Rhizosphere_vs_Roots"** (between-group) and **"Rhizosphere_vs_Rhizosphere"** (the within-group baseline). The names in `group_colors` must match these comparison labels exactly; otherwise the boxes are drawn grey (the function warns about it). `comparison_condition1` selects which `"value1_vs_value2"` combinations to keep always with the reference group (`Rhizosphere`) first. `comparison_condition2` keeps only the same treatment pairs, so turnover isn't confounded by comparing samples from different treatments. Giving only `condition2_col` (without `comparison_condition2`) does the same for every treatment: it keeps the same-treatment pairs and facets by treatment. `facet_colors` colors the top facet strips (one per `comparison_condition2` pair) and `group_colors` colors the boxes (one per `comparison_condition1` pair). Tick labels are hidden by default since the groups are already identified in the legend. Set `show_x_labels = TRUE` to bring them back. `stat` adds a statistical comparison between the boxes of each facet, as in `beta_dissimilarity_plot()`. ```{r turnover, warning=FALSE, fig.width=8, fig.height=6} beta_turnover_plot( table = table_fung, metadata = metadata_fungi, comparison_condition1 = c("Rhizosphere_vs_Roots", "Rhizosphere_vs_Rhizosphere"), condition1_col = "Type_of_soil", condition2_col = "Treatment", facet_colors = "#5D478B", group_colors = c( "Rhizosphere_vs_Roots" = "#56B4E9", "Rhizosphere_vs_Rhizosphere" = "grey75" ), stat = "wilcox.test" ) ``` ### Distance-decay of community similarity The function `beta_decay_plot()` tests whether communities that are geographically closer are also more similar in composition. It computes pairwise community dissimilarity (`distance`, e.g. `"jaccard"`, `"bray"`, `"horn"`) and pairwise geographic distances from sample coordinates, runs a Mantel test [@mantel1967test] between them, and plots similarity (1 − dissimilarity) against distance with a fitted regression line. `lat_col`/`lon_col` name the latitude/longitude columns in `metadata` (decimal degrees), and the optional `group_col` runs a separate Mantel test and regression line per group instead of one global test. We construct example data for this part: ```{r decay-1, warning=FALSE, fig.width=8, fig.height=6} loc_coords <- data.frame( Loc = 0:8, lat = 19.0 + seq(0, 0.8, length.out = 9), lon = -99.0 + seq(0, 0.8, length.out = 9) ) metadata_bacteria$lat <- loc_coords$lat[match(metadata_bacteria$Loc, loc_coords$Loc)] metadata_bacteria$lon <- loc_coords$lon[match(metadata_bacteria$Loc, loc_coords$Loc)] # filtering uncultivated metadata_bacteria_decay <- metadata_bacteria %>% filter(Type_of_soil != "Uncultivated") ``` ```{r decay-2, warning=FALSE, fig.width=6.5, fig.height=4.5, out.width="65%"} beta_decay_plot( table = table_bac, metadata = metadata_bacteria_decay, lat_col = "lat", lon_col = "lon", distance = "jaccard", group_col = "Type_of_soil" ) ``` ## Differential abundance analysis `MicroBioMeta` has several functions to explore **differentially abundant taxa**. These analyses help identify microbial features that vary significantly across experimental groups. Two functions rely on the **compositional data analysis framework implemented in the package** [ALDEx2](https://bioconductor.org/packages/ALDEx2/) [@fernandes2014aldex2], which accounts for the compositional nature of sequencing data [@gloor2017compositional] by using Monte Carlo Dirichlet instances and centered log-ratio transformations. A third one uses ANCOM-BC2 [@lin2024ancombc2], from the [ANCOMBC](https://bioconductor.org/packages/ANCOMBC/) package, an alternative differential abundance method that explicitly models compositional bias and structural zeros. The functions: - `aldex_volcano_plot()` visualizes differential abundance results using a **volcano plot**. - `aldex_heatmap_plot()` visualizes significant taxa in a **heatmap**. - `ancombc_plot()` returns a bar plot (when 2 groups) and a heatmap (when 3+ groups). Additionally, two complementary approaches help identify **important taxa that discriminate between groups**: - `ratios_bubble_plot()` visualizes taxa based on **log-ratio differences between conditions**. - `random_forest_lollipop_plot()` uses a **Random Forest model** [@breiman2001randomforest] to identify features that best predict a given variable or condition, visualized as a **lollipop plot of feature importance**. ### Example: Bacterial data First, we keep only two soil compartments, **Bulk soil** and **Roots**, since the ALDEx2 functions compare two groups. ```{r bact-data} metadata_bacteria_compar <- metadata_bacteria %>% filter(Type_of_soil == "Roots" | Type_of_soil == "Bulk soil") table_bacteria_compar <- table_bacteria[match(metadata_bacteria_compar$SAMPLEID, colnames(table_bacteria))] table_bac_compar <- merge_feature_taxonomy(table_bacteria_compar, taxonomy_bacteria) ``` We can visualize differential abundance using a **volcano plot**. Significant taxa are labeled with their name; `label_size` controls the font size of these labels, and `filter_uncultured = TRUE` drops "uncultured"/"unculture" taxa from the labels (they are still plotted as points, just not labeled). By default significance uses the Benjamini-Hochberg adjusted p-value (`p_adjust_method = "BH"`), since thousands of taxa are tested at once. Between bulk soil and roots many taxa remain significant after the correction (colored points); `p_adjust_method = "none"` would use the raw p-values instead. ```{r volcano, message=FALSE, warning=FALSE, fig.width=6, fig.height=4.5, out.width="60%"} set.seed(123) aldex_volcano_plot( table = table_bac_compar, metadata = metadata_bacteria_compar, group_col = "Type_of_soil", type = "volcano", label_size = 3, filter_uncultured = TRUE ) ``` ### ANCOMBC2 as an alternative method `ancombc_plot()` provides an alternative to the ALDEx2-based functions above. This function depends on the Bioconductor package `ANCOMBC`: ```{r ancombc-1, eval=FALSE} # install.packages("BiocManager") BiocManager::install("ANCOMBC") ``` `level` groups the table to a taxonomic rank before testing (default `"Genus"`), and `p_adjust_method`/`min_prevalence` control the multiple-testing correction and prevalence filter. With two groups the result is a **bar plot**: one bar per significant taxon with its log fold change (LFC) between the two groups and its standard error, colored by the group where the taxon is more abundant. The reference group is the first level of `group_col` (here **Bulk soil**), so positive values mean more abundant in **Roots**. Here `min_prevalence = 0.5` keeps the phyla present in at least half of the samples. ⚠️ With a low `min_prevalence`, rare/sparse taxa can trigger a `"Zero variances have been detected..."` error from ANCOMBC2's internal bias-correction step on some runs (it doesn't always happen, it depends on which taxa the bootstrap iteration happens to keep). Raising `min_prevalence` filters those sparse taxa out before testing and avoids it. ```{r ancombc-2, message=FALSE, warning=FALSE, fig.width=7, fig.height=5, out.width="60%"} ancombc_plot( table = table_bac_compar, metadata = metadata_bacteria_compar, group_col = "Type_of_soil", level = "Phylum", min_prevalence = 0.5, p_adjust_method = "BH" ) ``` With **3 or more groups**, `ancombc_plot()` returns a **heatmap** instead: one column per group compared against the reference level (the first factor level, here **Bulk soil**; it can be changed with `ref_level`), and one row per taxon that is significant in at least one comparison. Here we keep the three compartments (dropping **Uncultivated**) and group to `"Phylum"` so the heatmap stays readable: ```{r ancombc-3, message=FALSE, warning=FALSE, fig.width=7, fig.height=4.5, out.width="60%"} metadata_bacteria_3 <- metadata_bacteria %>% filter(Type_of_soil != "Uncultivated") table_bac_3 <- table_bac[, c(match(metadata_bacteria_3$SAMPLEID, colnames(table_bac)), ncol(table_bac))] ancombc_plot( table = table_bac_3, metadata = metadata_bacteria_3, group_col = "Type_of_soil", level = "Phylum", min_prevalence = 0.3, p_adjust_method = "holm" ) ``` **How to read the heatmap:** each column is one group compared with the reference (here **Rhizosphere** vs **Bulk soil** and **Roots** vs **Bulk soil**), and each row is a taxon. The color and the number in each cell are the log fold change (LFC, natural logarithm) estimated by ANCOMBC2: positive values (orange) mean the taxon is more abundant in that group than in bulk soil, negative values (blue) that it is less abundant, and white means no change. For example, an LFC of 1 means about 2.7 times more abundant (*e*^1^), and -1 about 2.7 times less. A taxon is shown when it is significant in at least one of the comparisons, so a cell can be colored even if that particular comparison is not significant; `save_table = TRUE` saves the adjusted p-value (`q_`) and the significance (`diff_`) of every comparison. ### Example: Microbial eukaryote data We follow the same procedure, comparing **Bulk soil** and **Roots**, but visualize the results with a **heatmap**. This function uses `ComplexHeatmap` [@gu2016complexheatmap]. ```{r fung-data} metadata_fungi_compar <- metadata_fungi %>% filter(Type_of_soil == "Bulk soil" | Type_of_soil == "Roots") table_fungi_compar <- table_fung[match(metadata_fungi_compar$SAMPLEID, colnames(table_fung))] table_fung_compar <- merge_feature_taxonomy(table_fungi_compar, taxonomy_fungi) ``` As in the volcano plot, by default the heatmap keeps the taxa with a Benjamini-Hochberg adjusted p-value below 0.05 (`pval_threshold = 0.05`, `p_adjust_method = "BH"`); `effect_threshold` can additionally filter by effect size. Each row shows the median clr values per group, with side annotations for the effect size, the p-value class and the difference between groups: ```{r aldex-heat, fig.width=9, fig.height=5, message=FALSE, warning=FALSE} set.seed(123) aldex_heatmap_plot( table = table_fung_compar, metadata = metadata_fungi_compar, group_col = "Type_of_soil" ) ``` ### Identifying important taxa The functions `random_forest_lollipop_plot()` and `ratios_bubble_plot()` can also be used to highlight taxa that contribute most strongly to the observed differences between conditions. For example, a **Random Forest model** can be used to identify the taxa that best predict the soil compartment: ```{r rf-1, fig.width=7, fig.height=5, out.width="60%"} random_forest_lollipop_plot( table = table_bac, metadata = metadata_bacteria, top_n = 10, variable_to_predict = "Type_of_soil" ) ``` Alternatively, taxa with the strongest **log-ratio differences between two conditions** can be visualized using: ```{r rf-2, fig.width=10, fig.height=9} ratios_bubble_plot( table = table_fung_compar, metadata = metadata_fungi_compar, group_col = "Type_of_soil", top_n = 20, condition_A = "Roots", condition_B = "Bulk soil" ) ``` ## Environmental analyses `MicroBioMeta` provides two functions to explore the relationship between **environmental variables** and **microbial community composition**: - `corr_env_abund_plot()` — computes correlations between taxonomic abundance and environmental variables. - `cca_rda_biplot()` — performs constrained ordination using **Canonical Correspondence Analysis (CCA)** or **Redundancy Analysis (RDA)**. ### Choosing the environmental variables The environmental variables are read directly from the **metadata** (one column per variable), so no separate table is needed: just pass the names of the columns to use in `env_vars`. If your variables are in a different table, give it in `env_data` (rows = samples, as row names). Here we use the soil physicochemical variables: ```{r env-table} env_vars_fung <- c("pH", "Silt", "WHC", "TN", "EC", "Sand", "Clay") ``` ### Correlation between environmental variables and taxonomic abundance The function `corr_env_abund_plot()` calculates correlations between **environmental variables** and **taxonomic relative abundances** at a selected taxonomic level and returns a **correlation heatmap** showing how environmental variables relate to taxonomic abundances. Example using **phylum-level abundances**: ```{r corr-env, fig.width=11, fig.height=9} corr_env_abund_plot( table = table_fung, metadata = metadata_fungi, env_vars = env_vars_fung, level = "phylum", save_table = FALSE ) ``` #### Alternative visualization Correlations can also be displayed using circle markers instead of tiles: ```{r corr-env-alt, fig.width=11, fig.height=9} corr_env_abund_plot( table = table_fung, metadata = metadata_fungi, env_vars = env_vars_fung, level = "phylum", save_table = FALSE, geom = "circle" ) ``` ### Constrained ordination (CCA / RDA) The function `cca_rda_biplot()` performs a constrained ordination analysis to evaluate how environmental variables explain variation in microbial community composition. `scale_arrows` is a parameter that helps you to visualize better the environmental vectors: ```{r cca, fig.width=8, fig.height=6} cca_rda_biplot( table = table_fung, metadata = metadata_fungi, env_vars = c("pH", "TN", "WHC", "EC", "Clay"), analysis = "RDA", show_all_env_vectors = TRUE, group_col = "Type_of_soil", scale_arrows = 3 ) ``` This analysis produces a **biplot** where: - **Points** represent samples - **Colors** indicate sample groups defined in the metadata. - **Arrows** represent environmental variables and their direction of influence on community structure. - Environmental vectors pointing in similar directions indicate **positive associations**, while vectors pointing in opposite directions suggest **negative relationships** ## References
## Session info ```{r session} sessionInfo() ```