JBrowseMSA

JBrowseMSA user guide

JBrowseMSA (the react-msaview package) renders a phylogenetic tree alongside a protein or nucleotide alignment on HTML5 canvas, tiled so it stays responsive on very large inputs (up to the 230k-node UCSC SARS-CoV-2 sample tree). The viewer runs entirely in the browser and uploads nothing.

This guide tours the live app. Every figure below links to the app in that exact state through the ?data= URL parameter, so clicking a screenshot opens the same view to explore.

Getting started

Open the app and you land on the import form.

The import form lists preloaded examples: a 230k-node COVID tree from UCSC, CLUSTAL-formatted alignments, RNA and protein Stockholm files, and a large tree+MSA generated by MAFFT. Click an example to load it, or supply your own data with the file and URL inputs below.

You can load an alignment on its own, a tree on its own, or both together. When both are present, rows are ordered and connected to match the tree.

Loading your own data

The import form accepts a local file or a remote URL for each of the alignment, the tree, and (optionally) a domain-annotation track. If you do not have those files yet, the tutorials build them from sequences, with the commands for the alignment, the tree and the annotations.

InputFormats
AlignmentFASTA (gaps already inserted), Stockholm (.stock, single or multi-alignment, may embed a tree and SS), Clustal (.aln), A3M, EMF
TreeNewick (.nh), or the tree embedded in a Stockholm/EMF file
DomainsGFF3, such as InterProScan output (generate it with the CLI)

Stockholm files may carry both the tree and a secondary-structure annotation inline, so a single file can populate the whole view. A “multi-Stockholm” file with several alignments is supported too.

A tour of the viewer

Once data is loaded the view has four parts:

Hovering a column highlights that position down every row of the alignment, so you can read one site down the whole family.

Color schemes

Open the palette menu in the header to switch schemes live.

The color-scheme menu, with protein and nucleotide palettes (the embedding guide lists them all).

Two schemes are dynamic: they color each column from statistics about the residues in that column, where the other schemes use a fixed color per letter.

clustalx_protein_dynamic colors residues ClustalX-style from the composition of each column.
percent_identity_dynamic shades each column by its percent identity, so conserved sites stand out.

Working with the tree

Click a branch node to collapse that subtree. Collapsing also hides any alignment column that holds only gaps once the collapsed rows are gone, so the alignment narrows as you fold clades away.

A collapsed subtree, drawn as a triangle labeled with its tip count (here 3). The rows beneath it are hidden and the gap-only columns they introduced are removed.

A branch node’s menu also has Show only this node, which narrows the view to that subtree: the rows below it are the whole alignment until Disable show only this node puts the rest back.

Tree settings → Show tree overview puts the whole tree in a band above the tree panel, small enough that a few hundred tips fit in 120 pixels, with the focused subtree drawn as a box on it and the clades highlights in place. A click on the band focuses the deepest subtree covering the rows under the pointer, and a click inside the box clears the focus, so the band reaches a clade of a tree far taller than the screen in one click. The overview keeps drawing every tip while the view shows a subtree, so it shows where the focused clade sits in the whole tree. The SVG export draws the band too.

With branch lengths on, a scale bar sits in the gutter above the tree: a round number of substitutions per site, drawn to the same scale as the branches. The scale bar is hidden in cladogram mode, where horizontal position shows topology rather than branch length. The SVG export carries the bar too, so a published figure states the scale its branches are drawn to.

The tree settings menu toggles branch-length rendering, right-aligned vs tree-adjacent labels, and clickable branch bubbles. Advanced → Calculate neighbor joining tree (BLOSUM62) builds a quick tree for an alignment loaded without one, up to 500 rows. On a larger alignment the calculation would freeze the page for several seconds or more, so the menu item explains the limit and does not run. Build a tree that size with FastTree or IQ-TREE and open it beside the alignment; the protein family tutorial covers the whole path.

Protein domains

Load a GFF3 annotation file from the import form, or from Annotations → Open annotation file…, to overlay domains on the alignment. The overlay accepts any GFF3, including exon and gene models; InterProScan output is the most common input. The dialog also takes the JSON an InterProScan run returns and converts it to GFF3 as it loads. Either way the annotations travel in the shared link with the rest of the view. The viewer translates each row’s annotation coordinates into alignment columns, so they line up across the family even where gaps shift the underlying sequence positions.

The CLI builds the file: react-msaview-cli interpro reads InterPro’s precomputed matches for UniProt accessions in seconds, and interproscan scans sequences InterPro has not seen. The protein family tutorial walks through both, and Annotations → How to get a domain file… opens it from the app.

A real Src-family kinase family (SRC, YES, FYN, FGR, HCK, LYN, LCK, BLK) with its tree and real InterProScan domains generated by react-msaview-cli interproscan. Zoomed out to full length, the shared SH3, SH2, and tyrosine-kinase catalytic domain architecture lines up across every member.

Why the overlay is column-locked

The two panels below show what the translation into alignment columns changes. Both hold the same twelve NLRP1 orthologs, domain GFF, component, palette and tree; only the bottom panel’s input was aligned.

In the top panel there are no alignment gaps, so column N is residue N and each protein’s domains sit at its own residue positions. The shared domains scatter into a staircase, because the proteins differ in length and in what they carry at the N terminus. In the bottom panel the same domains land in the same columns: NACHT starts at residue 328 in human and residue 93 in hamster, 235 residues apart, and the viewer draws the two in alignment columns 371 and 372. Because the overlay uses the alignment’s columns, you can compare a domain across the whole family in one column range.
The same alignment at base resolution. The five rows with a pyrin (PYD) domain carry it over real sequence. The rows without one still have sequence there: cow, pig, horse and zebrafish have residues in those columns with no PYD called over them, and only the rodents are mostly gap. At whole-protein zoom the two cases look alike, so zoom to base resolution to tell “no domain annotated” from “no sequence”.

Viewing metadata

Alignment file headers and per-sequence information are available from the Metadata dialog (file menu).

The metadata dialog showing the CLUSTAL header and the raw sequences, with options to copy them and to show/hide gaps.

Sharing and exporting

The Export SVG dialog, with a choice between the whole alignment and the current viewport, and checkboxes for the minimap and tracks.

Besides copying the URL from the address bar, a script can build a link. The app reads one query parameter, ?data=, holding the URL-encoded JSON of the view:

const view = {
  type: 'MsaView',
  msaFilehandle: { uri: 'https://example.org/kinase.aln' },
  colorSchemeName: 'clustalx_protein_dynamic',
  highlights: [{ row: 'SRC_HUMAN', start: 530, end: 530, label: 'Y530' }],
}
const url = `https://gmod.org/JBrowseMSA/demo/?data=${encodeURIComponent(JSON.stringify(view))}`

Either that bare MsaView snapshot or the {"msaview": {...}} wrapper the app writes back to the address bar works. The layers reference and the model API docs list every field. When the app cannot read a snapshot, it opens on an error naming the problem, not on the import form.

Three things decide whether the link works for the person who opens it:

Tracks

Tracks are strips drawn above the alignment, sharing its columns and its horizontal scroll. The Tracks submenu at the top of the MSA settings menu lists every track and turns each on or off. The dropdown arrow on a track’s label, at the left, also closes it and shows its details.

Hovering a track reads out what it draws at that column: the two conservation scores, the sequence logo’s information content and residue composition, the columns an arc joins, the letter on a text track. Show track values on hover in the MSA settings menu turns the readout off. Over the alignment itself, the tooltip carries the domains and insertions under the cursor, and the header reads out the hovered row, residue and position.

The sequence logo over the IL2RA alignment. Tall single letters mark the columns the family holds constant, short stacks mark the columns that vary, and the gap-only stretch in the middle is blank, matching the run of - in the rows below it.

Check “Include tracks?” in the export dialog to include tracks in an SVG export.

A host can also supply a track as data. A columnTracks entry in the shared URL or session carries per-column values drawn as bars, a per-column string drawn like a Stockholm annotation line, or pairs of positions drawn as arcs. Values can index alignment columns or the residues of one row, and each track gets a name, a color and its own menu entry. Use an arc track for a pairing: a disulfide bond, a residue contact from a structure, a base pair the file does not already annotate. The layers reference lists the fields.

Settings reference

Layout options live in two dropdowns in the header: MSA settings and tree settings, beside the color-scheme palette.

The MSA settings menu holds the Tracks submenu and the toggles Draw letters, Color letters, not cells, Show track values on hover and Hide gappy columns. The tree settings menu beside it holds the branch-length, label and clickable-bubble toggles.

Scaling to large data

The viewer tiles both axes, so memory and draw time grow with the visible area, not with the size of the file.

The whole Globin family from Pfam (PF00042) as the InterPro API serves it: 20,705 sequences over 672 columns, 20 MB of Stockholm behind a 3 MB gzipped response. The first column paints about four seconds after the link opens. After that the canvas draws only the tiles on screen, so scrolling and zooming stay interactive.