Ribbon

Info about Ribbon

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 picking a locus

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.

Paper and code

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:

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

Acknowledgements

Ribbon stands on the shoulders of giants:

Visualizations created using D3 from Mike Bostock
Panel and navigation bar created using styles from Bootstrap
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

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

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:

Ref start
Ref end
Query start
Query end
Ref alignment length
Query alignment length
Percent Identity
Total reference length
Total query length
Reference name(chromosome)
Query_name

Information about the data and settings

Notes

Alignment file

Variant file

Selected region

(No region selected)

Bam file queried

(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:
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

Ribbon plot Dot plot

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 or .bed file

Bed instructions

Upload a bed file of variants or other features to look at.

Columns:

chromosome (reference)
start position (reference)
end position (reference)
name (optional)
score (optional)
strand (optional)
type/category (optional)

All optional fields can be used for filtering or showing tooltips with information, but only the first 3 columns are required for basic functionality.

VCF instructions

Upload a vcf file of variants to look at.

Requirements: columns:

chromosome (reference)
position (reference)
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

Upload a .bedpe file

This is for those large variants 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 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:

Upload a coverage file

Upload a bed file of coverage

Instructions: 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.

Instructions: 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

Annotation:

Label genes:

Genes labeled: (click to show/hide)

Hide gene names for types selected in table above

Filter variants:

Variant details:

Click on a variant to show detail

Divide coverage by:
Show features
Color scheme:
Publication style plot

Filter variants:
Minimum variant size:
Minimum split reads:
Minimum discordant pairs:
Minimum miscellaneous read evidence:

Send to UCSC genome browser

Database: hg19

Top:

Bottom:

(change database in Genes tab under annotation)

Send to Ribbon long-read browser

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.

Mean coverage:

Total number of variants:

Number of interchromosomal variants:

Number of variants after filtering in table below:

Categorization parameters
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

Export table as csv

Enter gene names by hand or upload a list, and SplitThreader will use its rearrangement graph to search for genomic connections between each pair of genes.

Enter gene names

Gene 1

Gene 2

Selected: (none)

Instructions:

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

Instructions:

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:

Instructions:

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 gene fusions

Export table as csv

Send to Ribbon to visualize alignments

Parameters

Max bp distance to search:

From

Genes Bed file

Number of starting points:

To

Genes Bed file

Number of target end-points:

Calculate distances across the graph

Instructions:

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 gene fusions

Export table as csv

Upload a bed file

Upload a bed file of features

Instructions: 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.