Genomic Viewer

Version: 1.1.0
Description: Genomic Viewer is a cross-platform application for visualizing and analyzing genomic data hosted in a Docker container.

---

Table of Contents

 

1. Overview
2. System Requirements
3. Installation
4. Getting Started
5. Tutorial
6. Source Code

---

Overview

 

Genomic Viewer is a graphical application for the visualization and biological interpretation of next generation sequencing (NGS) data, focusing on easy data integration especially for users with little to no programming background. It combines multiple tools for genomic data exploration, filtering, and generation of publication-ready plots into a single, easy to use program. Genomic Viewer has been designed to be of use for non-programmer users, works offline, allows sessions sharing and performs some basic analyses for data inspection.

---

System Requirements

Software and Hardware

Operating System

• Windows 10 or higher
• macOS with Intel x64 or Apple M1 ARM64 and higher
• Linux (Debian-based or Red Hat-based)

A list of tested platforms is given here.

Hardware Recommendations

• Minimum RAM 4GB
• Minimum disk space 12GB: 4GB Docker Desktop, 7.5GB Genomic Viewer Docker image, 350MB Genomic Viewer Installer, plus space for user defined data to be loaded during program invocation

---

Installation

Installation Instructions

Recommended actions for the user before installing Genomic Viewer and step-by-step instructions on how to get the application running.

For a more detailed description of the recommended Genomic Viewer installation steps refer to this guide.

Windows

Prerequisites:

• Install Docker Desktop for Windows.
• Enable the Windows Subsystem for Linux WSL2 (optional, if not enabled Genomic Viewer installer will do this for you).
• Download windows-x64.zip installer file for Windows from GitHub.

Installation:

1. Extract the windows-x64.zip installer file.
2. Start setup by double-click on genomicviewer-gui-installer-1.1.0 Setup file.
3. Follow the installer wizard instructions.

Uninstallation:

1. Start genomicviewer-gui-installer-1.1.0 Setup file.
2. Follow the "Remove App Data" instructions to remove app-associated data. (Note: user's own data saved in the data folder are preserved).
3. Uninstall application from Windows Start Menu > Settings > Apps > Uninstall.
   
   

macOS

Prerequisites:

• Install Docker Desktop for macOS.
• Download genomicviewer-run-macos.zip file for macOS from GitHub.

Installation:

1. Extract the downloaded folder with configuration, example data and launcher file.
2. Enter the extracted genomicviewer-run-macos directory.
3. Open a Terminal from there and type docker compose up.
4. Once loading finished ctrl+click on http://localhost:8180.

Uninstallation:

1. Drag the genomicviewer-run-macos folder to Trash.
   
   

Linux

Prerequisites:

• Install either Docker Desktop for Linux or Docker Engine.
  Note: Non-root users can still use docker if rootless mode is configured on their system.
• Download linux-x64.zip installer file for Linux from GitHub.
  Note: Linux installer provides both .deb package for Debian-based distributions and .rpm package for Red Hat-based distributions. A self-contained app image is also available for non-root users.

Installation:

To install Genomic Viewer as root user:

1. Extract the linux-64 installer file.

2. Install the GUI installer for Genomic Viewer:

   • genomicviewer-gui-installer-1.1.0_amd64.deb (Debian-based systems)

   • genomicviewer-gui-installer-1.1.0-1.x86_64.rpm (Red Hat-based systems)

3. Launch the application setup by executing genomicviewer-gui-installer command in a terminal.

To install Genomic Viewer as non-root user:

1. Be sure the app image has execution permission:

   • chmod 755 genomicviewer-gui-installer-x86_64.AppImage

   Start the installer from the self-contained app image genomicviewer-gui-installer-x86_64.AppImage by running

   • ./genomicviewer-gui-installer-x86_64.AppImage or

   • ./genomicviewer-gui-installer-x86_64.AppImage --no-sandbox

   based on your Linux setup. Keep this file in case you want to uninstall the application at some pointer later.

2. Follow the installer wizard instructions.

Uninstallation:

For Genomic Viewer installed as root user:

1. Run genomicviewer-gui-installer command in a terminal.

2. Follow the "Remove App Data" instructions.

3. Remove the application package by running

• sudo apt remove genomicviewer-gui-installer (Debian)

• sudo dnf remove genomicviewer-gui-installer (Red Hat)

For Genomic Viewer installed as non-root user:

1. Run the self-contained app image genomicviewer-gui-installer-x86_64.AppImage.

2. Follow the "Remove App Data" instructions.

3. Remove genomicviewer-gui-installer-x86_64.AppImage.

Cross-platform Installer-free

Prerequisites:

• Install Docker Desktop as described in the appropriate section above.
• Download the example_data and GenomicViewer_config.yml file from Github.

Setting up installer-free parameters:

1. Open Docker Desktop. Go to Docker Hub and search for sarlago/shiny-docker-genomicviewer2.

2. Click on the corresponding image and then Pull. Once pulled, the image will appear under Images.

3. Click the Run button ▶️ and under Optional settings enter the following parameters:

   • Container name, optional e.g. GenomicViewer;
   • Ports > Host port, leave the first field emty, type 8180 in the second field;
   • Volumes > Host path, click the three dots and select the local folder with your data and configuration file;
   • Volumes > Container path, type in /data;
   • click Run.
   

4. Once the app is ready, click the link displayed in the Log Listening on http://0.0.0.0:8180 to open the app in your browser. This URL can be pasted to the web browser, too. All these URLs should work:

   • http://0.0.0.0:8180

   • http://127.0.0.1:8180

   • http://localhost:8180

5. After the first setup you can directly start the app from docker Containers, entering the container and clicking Run ▶️.

---

Getting Started

Quick Start

A short hands-on section showing a simple workflow.

1. Configuration and loading data

Data and their annotation are loaded through a configuration file named GenomicViewer_config.yml which is automatically saved in the data/ folder during Genomic Viewer installation in the user selected location.

A default configuration file is pre-filled and ready to use with information related to an example dataset retrieved from public data (accession numbers GEO: GSE212908, GSE212910, GAWS catalog: 26831199 and UCSC Table Browser Regulatory elements). Note: example data are provided only for chr5 to reduce disk space.

For more details on how to fill the Configuration file see the Configuration section. Genomic Viewer determines the data type and label based on the configuration file entries.

See File Formats for information on the supported data formats in the Configuration section. Additional configuration options like track plots alternatives, transcript or gene label annotation and chromosome display are available from the graphical interface and are thoroughly described in the Features and Usage section. Ensure that the data you want to load are saved in the data/ directory that was created upon GenomicViewer installation. Pay attention to load only data files with matching reference genome.

2. Launch Genomic Viewer

Launch Genomic Viewer with the desktop icon that was created upon installation.

After loading all the required R packages Genomic Viewer interface will open as a new tab in your default web browser.

3. Select a reference genome

Genomic Viewer shows data aligned to the genomic coordinates of a selected reference genome. It is essential to choose the correct reference genome to avoid mislabeling of gene/transcript annotation tracks and coordinates. Load only data tracks mapped to the same reference genome, and choose the appropriate reference. When you first launch the Genomic Viewer application, it automatically loads the default reference genome (currently hg19). For instructions on changing to another reference genome, refer to Reference Genomes paragraph in the Features and Usage section.

4. Navigate

The genomic range to be visualized can be specified in different ways thanks to multiple navigation controls provided by the graphical interface. Possible ways are:

• Manual insertion of genomic coordinates.
• Uploading of predefined coordinate sets.
• Lookup by gene name.

Zooming also allows to adjust the view dynamically. Once the visualization is generated through the Go button, a chromosome ideogram will show the position and extent of the displayed region. For more details about genomic navigation, see the Genomic Navigation paragraph in the Features and Usage section.

5. Explore datasets

Genomic Viewer provides three different navigation tabs named Plot, Data and Stats to

• extract and visualize genomic data of a selected region;
• subset the original data to the visualized genomic range, ready for export and external use;
• obtain quantitative and descriptive information to support the biological interpretation.

Further description of each panel is available at the Central Panels in the Features and Usage section paragraph.

6. Export results and coordinates

Genomic Viewer allows to export and save different outputs generated during a working session:

• The genomic visualization can be exported as a high quality plot in different file formats with the Save button.
• A custom list of coordinates dynamically created during the working session can be exported and saved in the Load coordinates panel.
• Raw data corresponding to what is shown in the selected genomic region can be downloaded as individual files in the Data navigation panel.

A more in detail description of these functions is given in the Features and Usage section.

7. Share your session

Collaborative efforts are supported by Genomic Viewer. Be sure the collaborator has all underlying data files and then simply forward the data/GenomicViewer_config.yml to your partner to place it on their installation's data/ directory.

Several configuration files can be stored separately to keep track of multiple working sessions. Just remember to select the proper reference genome in Genomic Viewer.

---

User Interface Overview

Brief description of the Genomic Viewer graphical interface structure.

Main Window

The graphical layout of Genomic Viewer consists of three elements:

• left sidebar - reference genome selection, coordinates (information and input) and buttons for updating and saving the view;
• right sidebar - selection of an entire chromosome for plotting, gene search, advanced graphics options;
• central panel - for showing plots, data, and statistics.

Sidebars

Left sidebar

The left sidebar provides several functions for working with the reference genome and its navigation. First, it is essential to select the reference genome that matches all the data files defined in the configuration file. Coordinates can be entered manually (or are transferred and displayed from the gene search) or can be selected from a custom list. This list of coordinates can be modified over the course of a session and can be exported for later use in a follow-up session or for collaborative sharing. The left sidebar is also where the Go and Save buttons are located, which are used to update the genomic view plot and to export it in different file formats, respectively.

Right sidebar

The right sidebar provides advanced options for genomic navigation and graphical settings. An entire chromosome can be chosen from a graphical overview. Genes can be searched and their coordinates will be transferred to the left sidebar for updating the genomic view. Again, it's imperative to choose the intended reference genome, as the chromosomes, gene IDs and the corresponding coordinates change accordingly. Furthermore, the bigwig data plotting style can be changed, one can decide between viewing gene or transcript isoforms and toggle the visibility of the chromosome ideogram.

Central Navigation Panels

The central area is the core of Genomic Viewer visualizing and summarizing previously selected genomic data. It allows the user to navigate across three different panels showing

• the Plot for the selected genomic region displaying all tracks that were defined in the configuration file. A zoom action bar is used to to adjust the genomic range;
• a preview of the raw Data restricted to the visualized genomic region with the possibility to download them;
• informative plots can be viewed in the Stats tab.

Further details are available in the Features and Usage section.

---

Tutorial

Tutorial

A complete Tutorial showing a usage example with the Genomic Viewer built-in test data is described in the Tutorial section of the reference manual.

---

Source Code

Genomic Viewer and its Electron-based GUI installer source code are freely available through GitHub under the MIT Licence.