How to use the Virome Browser

Before you start

The Virome Browser shiny app makes it easy to import, filter and browse results generated from virome NGS data. The result files necessary to use the viromebrowser app are contig files, tabular formatted contig annotation files, read mapping files.

  • The contig files can be generated with any de-novo or reference based assembly program and should be in FASTA format.

  • The annotation files should be generated with a BLAST like program and should be in BLAST format 6 as described here: http://www.metagenomics.wiki/tools/blast/blastn-output-format-6. In addition a column containing taxonomic identifiers should be available, which, when using BLAST, can be generated by adding the ‘-staxids’ option when running the tool.

  • The read mapping files can be generated by any short read aligner program and should contain the result of mapping the short reads used to generate the contigs to the contig fasta in BAM format.

R version 3.6.3 was used for the development of the Viromebrowser, R version 4.0.0 or later has not been tested. To run the viromeBrowser Rstudio version 1.2.5033 or later is recommended.

Getting started

Run the following code to start the Virome Browser app locally on your computer:

library(viromeBrowser)
viromeBrowser()

This will start the Shiny app server and will indicate from what local address the app can be reached (e.g. http://127.0.0.1:3838 by default) Alternatively you can host the app at a specific IP-address and port by specifying the host and port parameters of the viromeBrowser() function.

If R complains that the packages Biostrings and/or Rsamtools have not been installed install them with these commands:

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("Rsamtools")
BiocManager::install("Biostrings")

Loading data into the Virome Browser

Four types of files must be loaded in the app:

  • Metadata: a metadata file containing a table with sample information. Metadata files must contain a header specifying the variable names and the first column of the table should correspond to the file names of the annotation files (without the file extension).

  • Annotation files: annotation files containing annotation details per analyzed contig. Currently, only BLAST-like tabular format is allowed with a single annotation per contig. The columns in the loaded annotation table have to correspond to the contig id, taxonomic annotations, contig length, etc. Make sure that the names of the annotation files are the same as noted in the metadata file. Also make sure that the contig ids match the names of the contigs in the fasta files. The minimal annotation data needed to use the rest of the application are a contig.id and an annotation, but any other annotations will make it possible to filter based on those annotations.

  • Contig files: fasta files containing the contigs that were annotated. Make sure that the contig names match the contig names in the annotation file and the file names match the file names of the annotation file (without the extension).

  • BAM files: the BAM files containing the results of mapping the reads of each sample to the generated contigs. The names of the contigs should again match the names of the contigs in the contig files. The name of the bam file should also match the name of the contig and annotation file.

After loading all the files press the “Load Data” button to start processing the files.

After loading the data (wait for the loading bars to disappear) the tables under the panel “Metadata”, “Annotation Files”, “Contig Files” and “BAM Files” will be filled. These tables can be used to check whether the imported data was loaded correctly.

Two new menu items will also appear in the sidebar on the left, click on the “Interactive Data Browser” tab to continue.

Filtering and selecting annotation results using the interactive data browser

There are three ways of filtering the annotation results:

  • Metadata Filter Settings: Using the metadata filter settings you can select samples based on metadata parameters and select by which metadata parameter to stratify the displayed heatmap. Here you can also select to fill the heatmap with summed up contig counts, summed absolute read counts or summed relative read counts, scaled to the total number of reads in the mapping BAM file. There is also a selection field to indicate what level of taxonomy should be displayed in the heatmap.

  • Annotation filter setting: By default, annotation quality settings have been chosen to ensure high specificity of the displayed annotations. In order adjust the quality settings filters can be adjusted by adjusting the sliders. It is also possible to type in values for the slides in the “1000 … 2000” notation format.