Shiny FoodMicrobionet v2.
Thank you for downloading the ShinyFMBN app. The app was created using R and Shiny and is currently designed to run locally on your machine. The app will allow you to
a. explore studies[1] and samples[2] in FoodMicrobionet using the Explore tab.
b. select a subset of samples using a combination of filters with the Filter tab.
c. (optionally) aggregate samples or taxa with the Aggregate tab.
d. export the data in a variety of formats and visualize them in tables and plots[3] with the Export tab.
e. access external resources (SRA/ENA, NCBI Taxonomy, LPSN, Florilege)
A few additions were made to version 1.2 of the app. They are in bold italics.
Requisites.
To run the app you need R version 4 or above (download from CRAN) and RStudio. Make sure that the software can be run with your system. Please note that the app will display large tables: you will be better off if you use a large display (21.5 inches). Using smaller displays is feasible but may require some horizontal and vertical scrolling.
Launching
the app.
The app includes the code for installing a number of R packages, including Shiny. However, you may want to install and load Shiny before running the app for the first time. If you are not familiar with R or RStudio, the easiest way is to use the <Install> button of the File tab of the Plots pane (the pane on the lower right of your screen).
Otherwise, just type in the R console
>install.packages("shiny")
>library("shiny")
There are several ways to launch the app (for more info and options visit this page: https://shiny.rstudio.com/articles/running.html):
A. use the runShinyFMBN_2 script.
This is probably the best way to run the app when you use it for the first time, because you will be able to check that all the packages are installed correctly. The script will perform all needed installations and launch the app for you.
1. set the working directory to the folder containing the app folder (look here for instructions)
2. open the script (in RStudio use the File->Open file menu)
3. run the script using the Run or Run app command in the header bar of the script
B. launching the app from
the console
1. set the working directory to the folder containing the app folder (look here for instructions)
2. at the R console type
>runApp("ShinyFMBN2_1_4")[4]
3. the app will open by default in a new window in RStudio
4. to get help on runApp() at the R console type
>help("runApp")
C. launching the app from
the source pane
1. use the File>Open menu to open the app (you may have to navigate to the app folder if it is not in your working directory)
2. use the Run App button to run the app (if you want you can select the run mode)
Please remember: when you run the app the R session will be busy. There are several ways to terminate the app (see the RStudio article on running an app). The easiest is probably clicking the red stop button in the console.
Using the app.
The use of the app is quite straightforward and instructions are provided in each pane. The app is self-contained:
a. FoodMicrobionet data are in the /data subfolder: do not alter or move this folder or the data files;
b. external, static images are in the /www subfolder: do not alter or move this folder;
c. files will be saved in subfolders in the /output subfolder: see the Export tab for further details.
The Explore tab.
The Explore tab lets you explore studies and samples in FoodMicrobionet, as a preliminary step before filtering.
On the right of your display you will find:
1. a table with information on studies included in FoodMicrobionet[5]; in this and other tables in the app you can:
1.1. use the Show menu to select the number of entries to be shown
1.2. use the Search box to enter text and show records which include the text in any of the fields
1.3. reorder the records by clicking on the headings of each field
1.4. use hyperlinks to access external information (here you can access the sequences on SRA/ENA[6] or the papers using the DOI link)
1.5. use the navigation menu at the bottom to show other records
2. summary statistics on the version of FoodMicrobionet you are accessing with the app
3. a table with samples in one or more studies (use the dropdown menu on the left to select or remove studies)
Please note that selections made in the Explore tab do not have any effect on subsequent filtering.
The Filter tab.
This tab allows you to select a subset of samples for further analysis. Initially, all samples are shown and the selection can be narrowed down using different approaches.
1. use the drop-down menus (studies, food groups, food codes[7]) to select studies, then food groups and then food codes); check or uncheck the apply checkboxes to apply/remove your selection. As you proceed, the table on the right will be updated;
2. lists in the dropdowns are created dynamically, but, because of the hierarchic nature of fields in FoodMicrobionet, if you want to start your selection using food groups (or food codes) you should leave the study selection empty (or uncheck the apply checkbox);
3. once you are done, you can narrow your search using the filters at the bottom of the table: sample type (Environment for environmental samples, Sample for food samples), number of reads (use the slider to filter out samples with a low number of sequences after clean up; however, this can be easily done at a later stage), nature, process or spoilage. Please note that the options in the filters are updated every time you make a selection using the drop-down menus on the right or the filters at the bottom of the table, so not all options might be available as you proceed with the selection. Be aware that to remove a filter from a column you have to delete the option you have selected manually, while for the drop-down menus you can quickly remove all selections by unchecking the apply boxes.
You should use at least
one of the filters before you move to the Aggregate and Export tabs[8].
The
Aggregate tab.
The aggregate tab will display all the relevant tables from FoodMicrobionet after the application of your filters[9].
On the right of the screen you will find:
a. summary information on your selection.
b. the studies which include the samples in your selection.
c. samples in your selection (the table will be affected by the Show drop down menu, see below).
d. taxa in your selection: taxa are shown at different taxonomic levels and reflect the original taxonomic annotation of OTUs (or pooled ASVs in most recent versions[10]) of the studies included in FoodMicrobionet. Therefore, higher taxa (for example Enterobacteriaceae) indicate OTUs/ASVs for which annotation was not possible below the family level. The table will be affected by the Show drop down menu, see below. The relative abundance is calculated on the fly and corresponds to the relative abundance of the taxa in your selection (and not in individual samples). By default, the table is ordered by descending abundance, but you can reorder the table if you so wish (see instructions for the Explore tab). Hyperlinks to external resources (NCBI taxonomy, the List of Prokaryotic Names with Standing in Nomenclature) and the Florilege database[11] are provided for convenience.
e. a convenience list of references (this will be exported with your data)
The drop-down menus on the left allows you to perform:
a. aggregation of samples: there are two options, samples and exp. code. Using the first, samples will not be aggregated[12]; using the second, samples will be aggregated on the basis of the extended food code which includes information on the food code (from the FoodEx2 classification), the nature of the sample, the process, spoilage/ fermentation and the target (DNA vs. cDNA)[13]. Please be aware that if you choose <samples> graphical and statistical analysis may become messy or cumbersome (in case you have too many samples) while if you choose ext. code you may end up aggregating samples which were analysed using different combinations of wet and dry laboratory protocols, platforms and bioinformatic pipelines. Use the information in the study table to guide the choice of the aggregation level at this stage.
b. aggregation of taxa: taxa can be aggregated at the species (no aggregation), genus, family or class level. Abundances of OTUs belonging to the same taxon are summed[14].
Using the Show drop down menu you can choose to visualize samples and taxa before or after aggregation (if any).
The Export tab.
Here you will be able to export your selection in a variety of formats and generate (and export) some further summary tables and graphs of the data after aggregation. You just need to provide a prefix for the filenames and click on the action buttons. Files will be saved in different subfolders in the /output subfolder in the app. Please note that every time you click an action button a new file is saved whose name will include the file prefix, an integer (which is incremented by 1 every time you click on the action button) and a file suffix identifying the content of the file(s).
The files are saved in different formats:
a. urFMBN will save a list in .rds format including your selection of studies, samples, edges, taxa, and additional information on the references, version, sample Ids and sample and taxa aggregation.
b. aggFMBN will save a list in .rds format including (after aggregation, if any), your selection of studies, an OTU table with absolute abundances, an OTU table with relative abundances, sample and taxa metadata, edges and node tables, an igraph object with the bipartite sample-taxa network, and additional information on the references, version, sample Ids and sample and taxa aggregation. In the future the list will be used by an interactive Shiny app for statistical and graphical analysis.
c. phyloseq will save a phyloseq class object in .Rdata format. The object is suitable for use with Shiny-phyloseq[15] for statistical and graphical analysis.
d. conet will save a OTU table (absolute abundance) and a sample metadata table (both after aggregation, if any), ready for use with the Conet app of Cytoscape.
e. gml will save the bipartite igraph object in .gml format. This format can be easily imported in either Gephi or Cytoscape for further visualization and analysis.
f. mba will save OTU, sample metadata and taxonomy tables in a format suitable for use with MicrobiomeAnalyst[16].
g. ref will save the table for the references (in case you donÕt want to save a or b above)
Please note that although a few tables and plots can generated in the app you are much better off by exporting your data and performing analyses using Microbiome Analyst or Phyloseq.
Default filters.
Some "taxa" are removed by default (Mitochondria and Chloroplasts, other Eukaryotic sequences, taxa for which only information at the domain level is available) before any tabular or graphical result is presented.
The OTU table.
Using this tab you can visualize an OTU table for the top n taxa (n<100) in decreasing order of relative abundance. Use the slider to select n. Please realize that no rarefaction is performed: therefore samples/studies with more sequences will have a larger influence on the results. Use the <Save> button to save the table in tab delimited format.
The prevalence and abundance table.
This table shows prevalence and average, minimum and maximum relative abundance for all the taxa in your dataset. As above, no rarefaction is performed. Use the <Save> button to save the table in tab delimited format.
The prevalence and
abundance plot.
This tab shows a prevalence and abundance plot. Minimum prevalence and abundance (initially both are set to 0) can be chosen using two sliders. The graph is recalculated and the subtitle shows the number of taxa retained at different taxonomic resolutions. The results will affect both the bar and box plot. Use the <Save> button to save the graph as a 5x7 in, 150 dpi .jpg image[17].
The bar plot.
The bar plot tab features a stacked bar plot of abundance of the top (in terms of prevalence and/or abundance, see below) x taxa (with x<25). You can choose the number of taxa to display, their taxonomic aggregation level and the sample aggregation level (both are affected by choices in the aggregate tab. The app will automatically select the aggregation level for sample/sample groups and for taxa in such a way that the lowest aggregation level compatible with showing no more than 25 samples/sample groups or taxa is selected. The two drop down menus are generated on the fly in such a way that the use of too many taxa or samples/sample groups is prevented. If you want to select a lower taxa aggregation level you can use the filters in the prevalence and abundance graph tab (i.e. increase min. prevalence and/or abundance until the taxonomic level of your interest has <=25 categories, this is shown in the graph subtitle). Use the <Save> button to save the graph (see above for details).
The box plot tab.
This tab features a box plot (the default, or a violin plot, selected using the plot type menu) of the relative abundance of the top most abundant 25 taxa. Choices made for sample aggregation in the bar plot tab will be reflected here, but you can use the sliders to choose the taxa aggregation level and the taxa to display[18]. Use the <Save> button to save the graph (see above for details).
The About tab.
The About tab provides information on FoodMicrobionet and the app, and displays the license (currently a MIT license).
Known issues.
Because of rounding when assembling absolute abundance OTU tables it is theoretically possible that a taxon will have an abundance of 0 for all samples. This is highly unlikely, and can be fixed at a later stage.
It might have been better to add an option for rarefaction, and add some further personalization for the graphs, but I decided to leave this for later.
License.
This document is under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license.
New in this version.
There are a few major and minor changes over version 1.2.
Major changes:
á changed the procedure for importing FoodMicrobionet data in the app (now a list is used instead than individual files for studies, samples, taxa, edges, references and version)
á added a pipeline column to study tables
á added an export feature for MicrobiomeAnalyst
á added a button to export references for selected samples
á completely redesigned the Export tab, with new summary tables and graphs
á fixed an issue which prevented aggregation in the rare case the user selected a set of studies with only one exp. code category[19]
á fixed and issue which hanged the app if the used forgot to select at least one of the checkboxes in the Filter tab
Minor changes:
á fixed menus for number of rows to display for tables in the Explore and Aggregate tab
á fixed minor inconsistencies in samples and studies
á fixed a minor issue with filtering of Mitochondria and Chloroplasts (2.1.3)
á provided links to the Florilege database
Testing.
Testing of the app is in progress. As of today (June 11th, 2020) it has been successfully tested on the following systems:
á iMac 21.5 inches late 2013, 2.7 GHz Intel Core i5, quad core, MacOS 10.13.6, R 4.0.1, Rstudio Version 1.3.959, Safari 13.1
á MacBook Pro Retina 13" early 2015, 2.7 GHz Intel Core i5, dual core, MacOS 10.13.6, R 4.0.1, Rstudio Version 1.3.959, Safari 13.1
However, changes over previous version (2.1.3) are minimal and I can't see why it shouldn't work on other systems.