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). Everything runs in the browser — nothing is uploaded.

This guide tours the live app. Every figure below links to the app in that exact state via the ?data= URL parameter — click any screenshot to open and explore it yourself.

Getting started

Open the app and you land on the import form.

The import form, with 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 any example to load it, or supply your own data with the file/URL/paste 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 pasted string, a local file, or a remote URL for each of the alignment, the tree, and (optionally) a domain-annotation track.

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
DomainsInterProScan GFF3 (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 the corresponding position across rows (and on the tree), making it easy to read a single 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 rather than from a fixed per-letter table:

clustalx_protein_dynamic — ClustalX-style coloring driven by per-column composition.
percent_identity_dynamic — columns shaded by their percent identity, so conserved sites stand out.

Working with the tree

Click a branch node to collapse that subtree. Collapsing also hides any alignment columns that consist only of gaps introduced by the collapsed rows, so the alignment tightens up 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.

The tree settings menu toggles branch-length rendering, right-aligned vs tree-adjacent labels, and clickable branch bubbles. You can also compute a neighbor-joining tree (BLOSUM62) directly from an alignment that arrived without one.

Protein domains

Load a GFF3 annotation file from the import form, or query InterProScan from within the app under the Annotations menu, to overlay domains on the alignment. Any GFF3 works — InterProScan output is the common case, not a requirement — and the same overlay draws exon and gene models. Each row’s annotation coordinates are translated into MSA coordinate space, so they line up across the family even where alignment gaps shift the underlying sequence positions.

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

Translating into MSA coordinate space is the whole point, and the difference is easiest to see by taking it away. Both panels below are the same twelve NLRP1 orthologs, the same domain GFF, the same component and palette, and the same tree — the only difference is whether the 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 two are drawn in alignment columns 370 and 371.

That is what makes a domain overlay comparable across a family rather than a row of independent cartoons.

The same alignment at base resolution. The five rows with a pyrin (PYD) domain carry it over real sequence; the rows without one are not empty there — cow, pig, horse and zebrafish have residues in those columns with no PYD called over them, and only the rodents are mostly gap. An overview zoomed out to whole- protein scale cannot distinguish “no domain annotated” from “no sequence”, which is what the base-resolution view is for.

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 — choose the whole alignment or just the current viewport, and whether to include the minimap and tracks.

Tracks

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 one and turns it on or off; a track’s own dropdown arrow, on its label at the left, also closes it and shows its details.

The sequence logo over the IL2RA alignment. The tall single letters are the columns the family holds constant, the short stacks are the columns it varies, and the gap-only stretch in the middle draws nothing — matching the run of - in the rows below it.

Tracks are included in an SVG export when you check “include tracks” in the export dialog.

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 — the Tracks submenu, draw letters, color letters instead of tile backgrounds, show per-column statistics on hover, and enable hiding gappy columns. The tree settings menu beside it carries the branch-length, label and clickable-bubble toggles.

Scaling to large data

Both axes are tiled, so memory and draw time scale with what’s on screen rather than with the size of the file.

A real ~60-sequence ncRNA family (the Rfam Lysine riboswitch, RF00168) rendered with its full inferred tree and secondary-structure annotation, both extracted straight from the Stockholm file — the canvas tiling holds up well past toy- sized data.