Examples

Example sessions

JSON specification for the selected session:

A session can be used through URL too, for example:

https://v2.genomeribbon.com/?session=https://42basepairs.com/download/s3/giab-data/ribbon-json/ribbon-hg008-cov-bedpe.json&locus=chr1:23272628#splitthreader

Ribbon-specific examples

These use the older permalink structure, giving a specific snapshot of an analysis, but they may not be connected to the original files necessary to navigate to new loci.

Getting started

Ribbon is especially useful for viewing complex alignments, like long-read sequencing around large structural variants, alignments/variants that span more than one chromosome, or assembly/assembly alignments.

Start by loading a BAM file and navigating to a position. You can also load a VCF or BED file with variants or regions of interest.

Ribbon can be used for long reads, short reads, paired-end reads, and assembly/genome alignments. Instructions for each data format are available by clicking on "instructions" in each tab on the right.

SplitThreader

SplitThreader is now available within Ribbon! Just click "SplitThreader" in the top navigation bar, and you can load your own coverage and structural variant files to visualize them. There are also some examples to get you started.

Paper and code

Please cite the Ribbon paper in Bioinformatics:

Ribbon: intuitive visualization for complex genomic variation: https://doi.org/10.1093/bioinformatics/btaa680

Also see the preprint on the BioRxiv for Ribbon.

And the preprint for SplitThreader.

The code is open-source at https://github.com/MariaNattestad/Ribbon

Local installation:

You can install Ribbon locally from Github by following the instructions here: https://github.com/MariaNattestad/Ribbon

Navigate to a position:

Ribbon Settings

Make sure the bam file exists and that it has a corresponding index (.bai or .csi) file with an identical filename except for the addition of the .bai or .csi suffix.

You can also load multiple bams, comma-separated.

Here are some sample BAMs to play with:

Select bam and corresponding index (bai/csi)

To use a .delta file from aligning assemblies/genomes with MUMmer's nucmer, run MUMmer's 

show-coords -lTH
on it to get coordinates to load here.

Instructions

The coordinates must be the same as MUMmer's show-coords -lTH. This means 11 tab-separated columns without a header:
  1. Ref start
  2. Ref end
  3. Query start
  4. Query end
  5. Ref alignment length
  6. Query alignment length
  7. Percent Identity
  8. Total reference length
  9. Total query length
  10. Reference name(chromosome)
  11. Query_name

Information about the data and settings

(No region selected)
(No bam file queried)

Settings for the reference

Filter reference chromosomes
Zoom to chromosome

all
Minimum number of alignments:

1
Maximum chromosome length:
Reference settings
Color scheme:
Collapse reference sequences within distance:
Draw black border on selected region

Settings for read alignments

Filter reads
Number of alignments:
Minimum read length:
Minimum mapping quality: 0
Read settings
Sort reads vertically:
Orient reads by:
Color reads by:
Fetching from a bam file
Margin around a locus where reads will be pulled from a bam file: bp
Alignments that overlap this locus or within those number of basepairs of the locus will be loaded when a region is navigated to. Use this parameter carefully as importing too much data can crash your web browser due to memory overload. This takes effect when a new locus is navigated to.

Filter features by type

Indels
Show indels as:
Features
Show features as:
Variants
Show only the chosen variant when others are in view

Settings for the single-read (bottom) view

Selected read
Search reads:
Match reference from region view
Highlight selected read
Minimum indel size to split: inf
Alignment outlines on ribbon plot:
Colors on dotplot:

Filter alignments

Minimum mapping quality: 0
Minimum alignment length: inf

Upload a .vcf

Upload a vcf file of variants to look at.

Requirements: columns:

  1. chromosome (reference)
  2. position (reference)
  3. ID (optional)
The 8th column may contain optional information including STRAND (+/-), TYPE or SVTYPE, and END (the end position where the 2nd column is the start). All optional fields can be used for filtering or showing tooltips with information, but only the first 2 columns are required for basic functionality.

Upload a bed file with genes, repeats, or any other types of elements you want to annotate

Please load large variants through SplitThreader, then they will appear here.

Large variants are those that split reads into multiple alignments, e.g. translocations and other variants between positions more than around 1kb apart. These are shown as connections. The smaller variants can be loaded under the "Small variants" tab.

Showing only the first 1000 variants. Sort by clicking column names, and filter by typing into the text boxes for each column. For instance, type >20 or =chr2. Separate multiple filters in a single column using spaces. For bam files, click on a row in the table to fetch reads around that feature.

Automate Ribbon

Make Ribbon automatically go to each variant in a bedpe file and take pictures of the multi-read view and a selection of reads. Instructions: Load a bedpe file and a bam file first, set all the settings below and in the other tabs to include any data, filters, or other settings that you want applied on all loci during automation. Then click Run below.

Prefix for image files
Number of reads to take pictures of (randomly selected)
Print variant coordinates onto multi-read view
Download a file with info and coordinates for each variant alongside the images
Only select reads with alignments that start or end near the bedpe variant
Margin for selecting reads as being "near" the variant of interest (bp). Check box above for this to take effect.
If a region is too large for the browser to load, automatically subsample

Upload a coverage file

Upload a bed file of coverage

We recommend using mosdepth to generate a bed file of coverage. The bed file should have the first three columns as chromosome, start, and end, and the fourth column as the coverage. 

mosdepth -n --fast-mode --by 10000 output_file_prefix read_alignments.bam

Upload structural variants

There are two formats supported for variants: VCF and BEDPE.

VCF

.vcf or .vcf.gz are both fine.

Upload a VCF of structural variants

Or, load a VCF from a URL

Bedpe

Upload a bedpe file of structural variants

Some variant callers produce bedpe files, so you can load that instead of a VCF. The bedpe file should have the following columns (comma or tab separated both work).

Here's an example:

chrom1,start1,stop1,chrom2,start2,stop2,variant_name,score,strand1,strand2,variant_type,split
1,168186489,168186572,1,182274072,182274331,540,-1,+,+,INV,15
1,152555137,152555830,1,152587256,152588236,671,-1,+,-,DEL,34
Click on a variant to show detail

Tools

(click to show/hide)
    Divide coverage by:
    Show features
    Publication style plot
    Minimum variant size:
    Minimum split reads:
    Minimum discordant pairs:
    Minimum miscellaneous read evidence:

    Database: hg19

    Top:

    Bottom:

    (change database in Genes tab under annotation)

    Distance threshold for CNV matching and nearby variant count:
    Distance threshold for reciprocal pair of variants:

    Showing up to 1000 variants out of . Unfiltered, there are variants

    Filter in text boxes by =,>, or <, and click column names to sort. Click on a row in the table to see that variant in the visualizer

    Enter gene names

    Gene 1
    Gene 2
    Selected: (none)
    Selected: (none)

    Start typing a gene name into the input box and click on the gene you want (or use the arrow genes to walk up and down the list and press enter on the gene you want). Select two genes and then click the Submit button to search the rearrangement graph for a connection between the two genes.

    Upload a list

    Upload a list of gene fusions

    The file should have a pair of genes on each line separated by tabs, commas, or spaces, with the gene names in the first two columns matching the annotation.

    Shortest paths found:

    Click on a row in the table to jump to each gene fusion in the visualizer. "distance" is the number of basepairs in the path between the two genes. "num_variants" indicates the number of variants this path threads through in the graph. "path_chromosomes" shows all the chromosomes found along the path. If the genes have a direct connection that intersects both genes, the distance will be 0, num_variants will be 1, and path_chromosomes will be only the chromosomes the genes themselves reside on.

    Parameters

    Max bp distance to search:

    From

    Number of starting points:

    To

    Number of target end-points:

    Calculate distances across the graph

    Use the tables in the "From" and "To" panels above to filter down to the intervals you want to search between. Then click "Calculate" to get a result for each interval in "From", finding its closest interval among all the possible intervals in the "To" table.

    Click on one of the results in the table to show the path in the visualizer.

    Found results for X out of N total intervals in the "From" table. Showing a subset, but filter and sort works on the whole set (as with all tables in SplitThreader).

    Export table as csv

    Upload a bed file

    Upload a bed file of features

    Upload a bed file containing features to calculate distances between any sets of features and genes.