SHAMAN USER’S GUIDE SHiny Application for Metagenomic ANalysis 14/08/2019 shaman.pasteur.fr Authors: Stevenn Volant, Amine Ghozlane, Perrine Woringer SUMMARY Introduction ................................................................................................................... 3 Installation ..................................................................................................................... 4 Quick installation instructions ......................................................................................................................... 4 Tutorial............................................................................................................................ 7 Homepage ................................................................................................................................................................... 7 Tutorial and Download ........................................................................................................................................ 8 Raw data ...................................................................................................................................................................... 9 Read preparation ............................................................................................................................................... 9 OTU processing ................................................................................................................................................. 10 Load count and annotation data ................................................................................................................... 18 Statistical Analysis .................................................................................................... 22 Build the statistical model ............................................................................................................................... 22 Loading the experimental design ............................................................................................................ 23 Define the model .............................................................................................................................................. 24 Model options and normalization................................................................................................................ 26 Data filtering (optional) ....................................................................................................................................... 29 Define a contrast vector .................................................................................................................................... 30 Assessing the statistical model...................................................................................................................... 31 Differential analysis ............................................................................................................................................ 36 Visualizations ............................................................................................................. 38 Visualizations of the results ............................................................................................................................ 40 Overall composition ........................................................................................................................................ 40 Fold-change ........................................................................................................................................................ 42 Links between variables ............................................................................................................................... 42 Abundance and taxonomy ........................................................................................................................... 44 Result comparisons ............................................................................................................................................. 45 Comparison of the differentially abundant elements ..................................................................... 46 Comparison of fold change ......................................................................................................................... 49 Comparison of p value ................................................................................................................................... 50 Bibliography ............................................................................................................... 51 Appendix A .................................................................................................................. 52 2 INTRODUCTION SHAMAN is a shiny application for differential analysis of metagenomic data (16S, 18S, 23S, 28S, ITS and WGS) including bioinformatics treatment of raw reads for targeted metagenomics, statistical analysis and results visualization with a large variety of plots (barplot, boxplot, heatmap, …). The statistical analysis performed by SHAMAN is based on DESeq2 R package [Anders and Huber 2010] which robustly identifies the differential abundant features as suggested in [McMurdie and Holmes 2014, Jonsson 2016]. SHAMAN is compatible with standard formats for metagenomic analysis (.csv, .tsv, .biom) and generated figures can be downloaded in several formats. Hereafter is the global workflow of the SHAMAN application: 3 INSTALLATION Quick installation instructions SHAMAN is available for local installation using Docker and R. This installation covers only the statistical analysis. The bioinformatics treatment is deported to the Institut Pasteur galaxy instance for performance reason. - Docker install Docker is the easiest way to use SHAMAN locally. It is a controlled virtual environment where every package required for SHAMAN are already installed and which have no impact on your local R installation. First, download and install Docker from https://www.docker.com/. Docker is available for Windows, Mac and Linux. Run: # Download shaman docker pull aghozlane/shaman # Execute shaman, port 80 and 5438 need to be available docker run --rm -p 80:80 -p 5438:5438 aghozlane/shaman Then, connect with your web browser to: http://0.0.0.0/ or http://localhost/ If port 80 is already allocated, run: docker run --rm -p 3838:80 -p 5438:5438 aghozlane/shaman Then connect to http://0.0.0.0:3838/ or http://localhost:3838/ . You can update your local version of SHAMAN with: docker pull aghozlane/shaman - R install with Packrat SHAMAN is available for R=3.1.2. Packrat framework installation allow an easy installation of all the dependencies. Of note, raw data submission is not possible with this version. First, install R 3.1.2 as local install as follow: 4 # Install R 3.1.2 wget https://pbil.univ-lyon1.fr/CRAN/src/base/R-3/R-3.1.2.tar.gz && tar - zxf R-3.1.2.tar.gz mkdir /some/location/r_bin cd R-3.1.2/ && ./configure --prefix=/some/location/r_bin/ && make && make install && /some/location/r_bin/bin/R # Download SHAMAN package wget ftp://shiny01.hosting.pasteur.fr/pub/shaman_package.tar.gz This installation will not interact with other R installation. Then, you can install shaman with packrat: # Install SHAMAN dependencies mkdir /some/location/shaman /some/location/r_bin/bin/R install.packages(c('devtools', 'codetools', 'lattice', 'MASS', 'survival', 'packrat')) library(devtools) devtools::install_github(c('aghozlane/nlme')) packrat::unbundle("shaman_package.tar.gz", "/packrat/location/shaman") Now you can run SHAMAN: library(packrat) packrat::init("/packrat/location/shaman") library(shiny) system("Rscript -e 'library(\"shiny\");runGitHub(\"pierreLec/KronaRShy\",port=5438)'",wait= FALSE) runGitHub('aghozlane/shaman') - R install (deprecated) SHAMAN is available for R=3.1.2. The installation, download and execution can all be performed with a small R script: 5 # Load shiny packages if(!require('shiny')){ install.packages('shiny') library(shiny) } system("Rscript –e library("shiny"); runGitHub("pierreLec/KronaRShy", port=5438)", wait=FALSE) # Install dependencies, download last version from github, # and run SHAMAN in one command: runGitHub('aghozlane/shaman') Of note, the R version has an impact on the contrast definition. For R>3.2, DESeq2 used non-expanded modeling, hence the creation of contrast vectors slightly differs and some SHAMAN features might be deactivated. 6 TUTORIAL Homepage SHAMAN is available at http://shaman.pasteur.fr/. Hereafter is the homepage: 1 2 3 1 Toolbar. 5 tab are available: Home, Tutorial, Download/Install, Raw data, Upload your data. 2 Description of the application 3 SHAMAN news. 7 Tutorial and Download « Tutorial » and « Download/Install » panels are: 1 2 1 Online tutorial: it provides a description of SHAMAN usage for a set of 16S data. The dataset used is provided for download. 2 Installation guide. It is possible to install shaman with docker and R. 8 Raw data SHAMAN provide access to a bioinformatics workflow for analyzing targeted metagenomics data. This workflow is based on de novo clustering. Operational Taxonomic Unit (OTU) are built from reads in a given experiment and annotated by alignment against reference databases. The aim is to identify among high quality amplicon, OTU sequences that will be representative of one species and considered for annotation and quantification. The workflow can be summaries as follow: Read preparation Cleaning Cleaning step consists in the alignment of reads against the host and PhiX174 reference genome. Reads that did not align are considered for further analysis. This step is facultative but recommended. Very few amount of host DNA or Phi phage (used for calibration in every Illumina sequencing) can be identified in samples. A bowtie2 alignment with parameters (--sensitive) allows to eliminate these reads. Trimming Sequence GATTACA … TTA READ Quality 3031 … 161514 Sequence GATTACA … T READ trimmed Quality 3031 … 16 The trimming step consists to remove nucleotides sequences (adaptors, primers and non-confident nucleotides) in both 5’ and 3’ read ends. A list of every adaptators and primer used in Illumina, Solid, Ion torrent, Truseq, and Nextera adaptators is already 9 included in SHAMAN. But user can specify his own adaptaters. This step is performed by Alientrimmer [Criscuolo 2013]. Merging Se quence GATTACA … TTA TTA … GATTACA When reads are paired, a merging step is performed using Pear [Zhang 2013]. Reads are expected to overlap a given area of the ribosomal RNA. Sequence obtained are called amplicons. OTU processing The OTU clustering step is performed with Vsearch [Rognes 2016]. Dereplication GATTACA … TTA Full length GATTACA … TTA GATTACA … TTA Prefix GATTACA … The dereplication consists in selecting one representative sequence among identical amplicon sequence. Two approaches are available: the full length and the prefix dereplication. Full length approach will group sequence that are identical for their entire length. Prefix will also group sequence of different length. Only the longest sequence will be kept. The number of identical sequences in a given sample is critical. Sequences are re-ordered by this “dereplicated abundance” which will drive the OTU clustering (see clustering section). Sequences with no identical respective are considered as singleton and are excluded of the OTU clustering process. Chimera filtering Biological sequence X Biological sequence Y Chimera formed from X and Y 10