Tutorial

VIPER tutorial

This tutorial shows you how to use VIPER for some example .bam files and variant calls.

Starting VIPER

Step 1: Check requirements

To run VIPER and IGV, a Java version of at least 1.8 is required. You can check your Java version by running java -version in a console. If you are using Windows, you may skip this step as the provided startup script checks if a matching Java version is installed. You also need a modern web browser for a proper functioning VIPER web interface. If you are running Linux, it is recommended to install Xvfb to run IGV in a headless environment:

sudo apt-get install xvfb

Step 2: Download VIPER and example data

Go to VIPER GitHub releases and download the latest .zip file. This file contains the VIPER and IGV jar files as well as some configuration files and a windows start script. Then download the example .bam files and variant calls.

Extract both archives into a single folder (this eases configuration later on). Your folder should now contain the following files and directories:

• bam/
  • SIM1.bam
  • SIM1.bam.bai
  • SIM2.bam
  • SIM2.bam.bai
• config.json
• example-variant-calls.csv
• igv.jar
• igv.properties
• start.bat
• VIPER.jar

Step 3: Configuration

VIPER may be configured using the config.json file. A detailed overview over possible parameters can be found in the repositories README. For the example data it is sufficient to specify only the required parameters:

{
  "analysisFile": "example-variant-calls.csv",
  "workDir": "workdir",
  "bamDir": "bam"
}

The workDir parameter defines the directory VIPER uses to store the decision making progress and temporary visualization data, so make sure to not delete this directory.

Step 4: Starting and accessing VIPER

To start VIPER, execute

java -jar VIPER.jar

If there is no Xvfb installation, this will open an IGV window to visualize variants. This window must not be closed as VIPER is using it for visualization purposes. If you are using Windows, you can also simply double click on the provided start.bat file. Once IGV and VIPER are successfully started, you can open the web interface by accessing http://localhost:8090.

Using VIPER

VIPER eases manual inspection of variant calls to decide which calls are true and which are false positives. This decision making process is mainly performed using the Inspector page. The Filtering page offers a variant table overview and means to filter calls based on the information supplied in the input analysis file. The Export page enables exporting calls as .csv or .xlsx files.

Inspector

The Inspector page shows a single variant call at a time with each call possibly sharing multiple similar calls from the input that were grouped together by VIPER. IGV images are precomputed for the next variants to minimize waiting time and displayed for each breakpoint region. Based on these images and the raw call data experts can mark each variant as approved, discard, or leave the decision open with maybe. Don't forget to save your progress every now and then!

Filtering

This page shows all variants in a table, allowing to gain a quick overlook at the variants from the input file. Hyperlinks are provided to open every variant in the inspector.

Below the table filters are provided to quickly limit the number of variant calls to inspect. Each filter corresponds to a column of the variant table. Filters may be targeted at numerical or character values, depending on the values found in the columns.

Numerical filters consist of a range slider where the target interval can simply be chosen. NA values are also considered numerical and may be filtered out using the provided checkboxes. Character filters may be configured using the dropdown and search list provided. Empty character filters consider every variant passing. However, for performance reasons, only up to 50 entries are displayed in the dropdown list, so using the search function is advised.

If a single cell has multiple values, a filter considers the variant passing if any of the values passes the filter.

To speed up decision making for variant calls matching arbitrary filtering criteria, it is also possible to set a decision for all variants passing the current filters.

Example

We assume any tool (e.g. Socrates) yields calls confidently enough to blindly approve all calls by this tool. In a first step, the tool column filter is set to the tool's name. Then all variants by this tool calls are approved using the controls below the table. By resetting the filters and setting the viperDecision column filter to NA, only those variants without the previously approved calls are left for inspection using the Inspector. Once all variants have been inspected, progress is saved and calls are exported.

Export

The Export page allows downloading variants in .csv and .xlsx format. Either all variants or those passing the current filters may be exported.

Advanced usage

Partner visualization

VIPER also supports usage of ''partnering'' information such as control-tumor pairs or trios. To enable visualization of ''partners'' you have to provide a file containing the partnering information and setting the partnerFile attribute appropriately in the config.json. You may set the partnerDelimiter configuration parameter if necessary.

Examples for partnering files:

Control-tumor pairs (with tumor samples T1/T2 and control samples C1/C2)

T1,C1
T2,C2

Trios (with father, mother and child samples F1/F2, M1/M2, C1/C2)

F1,M1,C1
F2,M2,C2

Improve visualization speed

VIPER uses the IGV hg19 reference genome. This does not require explicit download of a reference for visualization but has the disadvantage that it might be slower than using a .fasta file. Setting VIPER's fastaRef configuration parameter to a local .fasta file might significantly increase visualization speed as a result.