Advanced settings

Fetching from a bam file
Margin around a variant or manually entered coordinate where reads will be pulled from a bam file (use this parameter carefully as importing too much data can crash your web browser due to memory overload) bp
Automation
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 the settings below and in the right-side panel as you want them and click Run!
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
If a region is too large for the browser to load, automatically subsample
Distance:

Information about Ribbon

Ribbon is made by Maria Nattestad with support from Pacific Biosciences and Cold Spring Harbor Laboratory.

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

Please cite our paper on the bioRxiv:

Ribbon: Visualizing complex genome alignments and structural variation: http://biorxiv.org/content/early/2016/10/20/082123

Ribbon stands on the shoulders of giants:

  • Visualizations created using D3 from Mike Bostock
  • Panel and navigation bar created using styles from Bootstrap
  • Remote bam files are read from any publicly accessible URL using a library from Bam.iobio by the Gabor Marth lab.
  • Local bam files are read using Samtools compiled into WebAssembly.

Ribbon also uses two D3 plug-ins created by Maria Nattestad:

  • Variant table with advanced filtering and sorting created using D3-superTable
  • Live search for chromosome and read names created using D3-livesearch

Getting started

Please cite our paper in Bioinformatics:

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

Also see the preprint on the bioRxiv:

Examples:

PacBio, Illumina, and genome/assembly examples shown in the Examples tab above.

Visualize your own alignment data:

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.

Local installation:

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

Information

(No region selected)
(No bam file queried)

Multi-read settings

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
Filter reads
Number of alignments:
Minimum read length:
Minimum mapping quality: 0
Read settings
Sort reads vertically:
Orient reads by:
Indels
Show indels as:
Features
Show features as:
Variants
Show only the chosen variant when others are in view

Single-read settings

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

Input alignments

Select bam and corresponding index (bai/csi)

Instructions

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. If the bam file does not exist or cannot be read, a header will fail to appear but there will be no error message. If the header of the bam file does not show up within about 10 seconds, loading the bam file has probably failed and you should check to make sure it actually exists at the given address. (To test for this, put the url into your web browser. If it starts downloading the bam file, then also check whether adding .bai or .csi to the url downloads the index file. If one of these does not start a download, then the file does not exist.)

Note that the bam file does not get read into memory, but the index file does, so if the index file is huge, it will take a while the first time you fetch reads from the bam file.

Upload a show-coords file:

Instructions

Upload variants

Upload a .vcf or .bed file

Instructions for .vcf file

Instructions for .bed file

Upload a .bedpe file

Upload features

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

Instructions for .bed file

Inspect variants

Showing only the first 30 variants. Sort by clicking column names. Filter by typing =chr20, >2000, etc. for each column. For bam files, click on a row in the table to fetch reads around that feature.

Inspect rearrangements

Showing only the first 30 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.

Inspect features

Showing only the first 15 features. Sort by clicking column names. Filter by typing queries into text input boxes, e.g. =17, >200.

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

Temporarily, only a special bedpe format is allowed. VCF will be supported soon.

There's a python script in the github that may help convert a VCF from a structural variant caller to this bedpe-like format. The bedpe file should have the following columns (comma separated). 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

Tools

(click to show/hide)
    Click on a variant to show detail
    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)

    Ribbon (genomeribbon.com) is a long-read alignment viewer that allows you to see all the reads mapping near a variant including their other alignments across the genome, and you can see detailed alignments for each read to determine which parts of the read are mapping where.

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

    Showing 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.

    Export table as csv

    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 at most 30, 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.

    Navigation

    Switch chromosomes by dragging chromosome names from the circos plot onto either the top or bottom coverage bar charts to switch that plot to the new chromosome.

    Zoom by double-clicking the coverage bar charts and move around by dragging when you are zoomed in. Also click the + and - buttons to zoom in and out.