zAMPExplorer Overview

Sedreh Nassirnia

zAMPExplorer

Lifecycle: experimental R-universe Status

zAMPExplorer is an interactive Shiny application designed to facilitate the downstream analysis of outputs generated by the zAMP pipeline . zAMP itself is a comprehensive DADA2-based bioinformatics pipeline for processing 16S rRNA gene amplicon metagenomic sequences, offering convenient, reproducible, and scalable analysis from raw sequencing reads to taxonomic profiles. The output of zAMP is a phyloseq object, which serves as the input for zAMPExplorer.

A typical phyloseq object contains the following components:

## phyloseq-class experiment-level object
## otu_table()   OTU Table:         [ 5 taxa and 6 samples ]
## sample_data() Sample Data:       [ 6 samples by 4 sample variables ]
## tax_table()   Taxonomy Table:    [ 5 taxa by 7 taxonomic ranks ]
## phy_tree()    Phylogenetic Tree: [ 5 tips and 4 internal nodes ]
## refseq()      DNAStringSet:      [ 5 reference sequences ]

For more information on the phyloseq package, please visit the official phyloseq documentation.

zAMPExplorer enables users to perform a wide range of microbiota and statistical analyses, including compositional barplot, relative abundance heatmap, community diversity (alpha diversity), community similarity through unsupervised (NMDS/PCoA) and supervised (RDA) ordinations, differential abundance testing using MaAsLin, and community typing (or clustering) of microbial profiles using Dirichlet Multinomial Mixtures (DMM). All of these analyses are made accessible through an intuitive graphical interface, bridging the gap between complex command-line bioinformatics processing and user-friendly data exploration.

Prerequisites and installation

Prerequisites

  • Operating system: Windows, macOS, or Linux
  • R: Version 4.3.2 or later
  • RStudio: Recommended for running the Shiny app
  • zAMP: zAMPExplorer is designed to work with output generated from the zAMP pipeline (phyloseq object).

Installation

Method 1: Install from source (GitHub)


# Optional: You can install dependencies using the install_dependencies.R script or install them independently

# Download the install_dependencies.R script to install required dependencies.
# download.file("https://github.com/metagenlab/zAMPExplorer/tree/latest/R/install_dependencies.R",
#               "install_dependencies.R")

# Run the script to install all dependencies
# source("install_dependencies.R")


# If not already installed 
# if (!requireNamespace("remotes", quietly = TRUE)) {
#   install.packages("remotes")
# }

#Install zAMPExplorer
remotes::install_github("metagenlab/zAMPExplorer", ref = "latest", dependencies = TRUE)
#> 
#> ── R CMD build ─────────────────────────────────────────────────────────────────
#> * checking for file ‘/private/var/folders/xs/1s58n__s7038wg03tpt62jm00000gn/T/RtmpIFOZBz/remotese8c95f190fdb/metagenlab-zAMPExplorer-9f6cc62/DESCRIPTION’ ... OK
#> * preparing ‘zAMPExplorer’:
#> * checking DESCRIPTION meta-information ... OK
#> * checking for LF line-endings in source and make files and shell scripts
#> * checking for empty or unneeded directories
#> Omitted ‘LazyData’ from DESCRIPTION
#> * building ‘zAMPExplorer_0.1.0.tar.gz’

Method 2: Install using R-universe


# Install zAMPExplorer from R-universe
# install.packages('zAMPExplorer', repos = c('https://metagenlab.r-universe.dev', 'https://cloud.r-project.org'))

Method 3: Clone the repository and install zAMPExplorer locally

# Clone repository (in bash)
#git clone https://github.com/metagenlab/zAMPExplorer.git

# Navigate to the app's directory
# cd zAMPExplorer
#Install dependencies in R
#source("install_dependencies.R")

# Install zAMPExplorer
#install.packages(".", repos = NULL, type = "source")

#Then load the library and run the app

# Load zAMPExplorer
library(zAMPExplorer)

# Launch the application
zAMPExplorer::zAMPExplorer_app()

Method 4: Docker installation for zAMPExplorer

Step 1: Install Docker

You can run zAMPExplorer as a Docker container without installing R or its dependencies directly on your machine.

Ensure you have Docker installed on your system. You can download it from the Docker website

  • For Windows/Mac: Install docker desktop.
  • For Linux: Follow the platform-specific instructions provided on the Docker website.

#To verify that Docker is installed, run (in bash):
#docker --version

Step 2: Install Docker


#Option1: Pull the pre-Built image. 
#You can pull the pre-built Docker image directly from a container registry (replace with your registry info if applicable):

#docker pull <your-dockerhub-username>/zampexplorer:latest

#Option 2: Build the image locally
#If cloned the zAMPExplorer source code from GitHub, navigate to the directory containing the Dockerfile and run:

#docker build --platform linux/x86_64 -t zampexplorer:latest .

Step 3: Run zAMPExplorer


#docker run --rm -p 3838:3838 zampexplorer:latest

#--rm: Removes the container after it stops.
#-p 3838:3838: Maps the container’s Shiny app port 3838 to your local port 3838.

Step 4: Access the Application


#Open a web browser and navigate to:
#http://localhost:3838

The zAMPExplorer Shiny app will be running and accessible on this URL.

Overview of the interface

zAMPExplorer is divided into several tabs, each dedicated to a specific type of analysis:

Figure 1
Figure 1

Check Phyloseq Components

Upload your phyloseq object here. This object is the output of the zAMP pipeline and serves as the input for all downstream analyses in the app.

Figure 2
Figure 2

Reads QC

Visualize the total number of reads per sample and other read quality metrics.

Figure 3
Figure 3

Taxa Overview

Explore the estimated number of organisms in each sample at different taxonomic levels.

Figure 4
Figure 4

Compositional Barplot

Create interactive barplots to visualize the relative abundance of taxa within your samples.

Figure 5
Figure 5

Heatmap

Generate heatmaps to visualize the relative abundance of taxa across samples and sample groups.

Alpha Diversity

Analyze and visualize alpha diversity metrics, comparing diversity within groups.

Figure 6
Figure 6

Beta Diversity

Explore beta diversity using different distance matrices to assess similarities/differences in microbial communities between samples.

Differential abundance testing (MAaslin2)

Determining associations between microbial features (e.g., taxa) and metadata.

Figure 7
Figure 7

Community Typing (DMM)

Perform community typing using Dirichlet Multinomial Mixture models to infer the optimal number of community types inside the dataset.

Figure 8
Figure 8

RDA Plot

Perform redundancy analysis (RDA) to explore the association between your samples and explanatory variables.

Troubleshooting and FAQ

Common issues

Issue

App fails to launch. - Solution: Ensure all dependencies are installed by running source("Dependencies.R").

Issue

Plots are not displaying correctly. - Solution: Verify your R version is 4.0 or later and that all necessary libraries are installed.

FAQ

References

The following R packages are integral to the functionality of zAMP Explorer. We highly recommend consulting their respective documentation:

References

The following R packages are integral to the functionality of zAMPExplorer. For detailed information about each package, visit the provided links:

For detailed information about each package, visit the provided links.

Contributing

Thank you for using zAMPExplorer. We hope it helps you gain deeper insights into your microbiome data (16S amplicons). Please feel free to contribute, suggest features, or report any issues you encounter.

Acknowledgments

We would like to thank the developers of the R packages and tools integrated into zAMPExplorer. Please make sure to acknowledge their contributions in any publications or projects using this tool.

#> R version 4.3.2 (2023-10-31)
#> Platform: aarch64-apple-darwin20 (64-bit)
#> Running under: macOS Sonoma 14.6.1
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0
#> 
#> locale:
#> [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
#> 
#> time zone: Europe/Zurich
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] shiny_1.10.0       zAMPExplorer_0.1.0
#> 
#> loaded via a namespace (and not attached):
#>   [1] splines_4.3.2                    later_1.4.1                     
#>   [3] bitops_1.0-9                     ggplotify_0.1.2                 
#>   [5] tibble_3.2.1                     MicrobiotaProcess_1.14.1        
#>   [7] InteractiveComplexHeatmap_1.10.0 lifecycle_1.0.4                 
#>   [9] doParallel_1.0.17                processx_3.8.4                  
#>  [11] lattice_0.22-6                   MASS_7.3-60.0.1                 
#>  [13] crosstalk_1.2.1                  magrittr_2.0.3                  
#>  [15] plotly_4.10.4                    sass_0.4.9                      
#>  [17] rmarkdown_2.29                   jquerylib_0.1.4                 
#>  [19] yaml_2.3.10                      remotes_2.5.0                   
#>  [21] httpuv_1.6.15                    pkgbuild_1.4.5                  
#>  [23] chromote_0.3.1                   RColorBrewer_1.1-3              
#>  [25] ade4_1.7-22                      multcomp_1.4-26                 
#>  [27] golem_0.5.1                      abind_1.4-8                     
#>  [29] zlibbioc_1.48.2                  Rtsne_0.17                      
#>  [31] GenomicRanges_1.54.1             purrr_1.0.2                     
#>  [33] BiocGenerics_0.48.1              RCurl_1.98-1.16                 
#>  [35] phyloseq_1.46.0                  yulab.utils_0.1.8               
#>  [37] TH.data_1.1-2                    webshot2_0.1.1                  
#>  [39] sandwich_3.1-1                   circlize_0.4.16                 
#>  [41] GenomeInfoDbData_1.2.11          IRanges_2.36.0                  
#>  [43] S4Vectors_0.40.2                 ggrepel_0.9.6                   
#>  [45] tidytree_0.4.6                   vegan_2.6-8                     
#>  [47] microbiome_1.24.0                svglite_2.1.3                   
#>  [49] permute_0.9-7                    codetools_0.2-20                
#>  [51] coin_1.4-3                       DelayedArray_0.28.0             
#>  [53] DT_0.33                          xml2_1.3.6                      
#>  [55] tidyselect_1.2.1                 shape_1.4.6.1                   
#>  [57] aplot_0.2.4                      farver_2.1.2                    
#>  [59] microViz_0.12.6                  shinyWidgets_0.8.7              
#>  [61] matrixStats_1.4.1                stats4_4.3.2                    
#>  [63] webshot_0.5.5                    jsonlite_1.8.9                  
#>  [65] ggtreeExtra_1.12.0               GetoptLong_1.0.5                
#>  [67] multtest_2.58.0                  survival_3.8-3                  
#>  [69] iterators_1.0.14                 systemfonts_1.1.0               
#>  [71] foreach_1.5.2                    tools_4.3.2                     
#>  [73] ggnewscale_0.5.0                 treeio_1.26.0                   
#>  [75] ggstar_1.0.4                     Rcpp_1.0.13-1                   
#>  [77] glue_1.8.0                       gridExtra_2.3                   
#>  [79] SparseArray_1.2.4                xfun_0.49                       
#>  [81] mgcv_1.9-1                       MatrixGenerics_1.14.0           
#>  [83] GenomeInfoDb_1.38.8              websocket_1.4.2                 
#>  [85] dplyr_1.1.4                      shinydashboard_0.7.2            
#>  [87] fastmap_1.2.0                    clisymbols_1.2.0                
#>  [89] rhdf5filters_1.14.1              callr_3.7.6                     
#>  [91] digest_0.6.37                    R6_2.5.1                        
#>  [93] mime_0.12                        gridGraphics_0.5-1              
#>  [95] colorspace_2.1-1                 config_0.3.2                    
#>  [97] tidyr_1.3.1                      generics_0.1.3                  
#>  [99] data.table_1.16.4                httr_1.4.7                      
#> [101] htmlwidgets_1.6.4                S4Arrays_1.2.1                  
#> [103] pkgconfig_2.0.3                  gtable_0.3.6                    
#> [105] modeltools_0.2-23                ComplexHeatmap_2.18.0           
#> [107] XVector_0.42.0                   htmltools_0.5.8.1               
#> [109] biomformat_1.30.0                clue_0.3-66                     
#> [111] scales_1.3.0                     kableExtra_1.4.0                
#> [113] Biobase_2.62.0                   png_0.1-8                       
#> [115] attempt_0.3.1                    ggfun_0.1.8                     
#> [117] knitr_1.49                       rstudioapi_0.17.1               
#> [119] reshape2_1.4.4                   rjson_0.2.23                    
#> [121] nlme_3.1-166                     curl_6.0.1                      
#> [123] cachem_1.1.0                     zoo_1.8-12                      
#> [125] rhdf5_2.46.1                     GlobalOptions_0.1.2             
#> [127] stringr_1.5.1                    parallel_4.3.2                  
#> [129] libcoin_1.0-10                   desc_1.4.3                      
#> [131] pillar_1.10.0                    grid_4.3.2                      
#> [133] vctrs_0.6.5                      promises_1.3.2                  
#> [135] shinyFiles_0.9.3                 xtable_1.8-4                    
#> [137] cluster_2.1.8                    evaluate_1.0.1                  
#> [139] mvtnorm_1.3-2                    cli_3.6.3                       
#> [141] compiler_4.3.2                   rlang_1.1.4                     
#> [143] crayon_1.5.3                     ggsignif_0.6.4                  
#> [145] ps_1.8.1                         plyr_1.8.9                      
#> [147] fs_1.6.5                         writexl_1.5.1                   
#> [149] stringi_1.8.4                    viridisLite_0.4.2               
#> [151] munsell_0.5.1                    Biostrings_2.70.3               
#> [153] lazyeval_0.2.2                   Matrix_1.6-5                    
#> [155] patchwork_1.3.0                  ggplot2_3.5.1                   
#> [157] Rhdf5lib_1.24.2                  SummarizedExperiment_1.32.0     
#> [159] fontawesome_0.5.3                memoise_2.0.1                   
#> [161] igraph_2.1.2                     bslib_0.8.0                     
#> [163] ggtree_3.10.1                    ape_5.8-1