Data layers
Every field below is a property of the MsaView model, so a host can write it
into the standalone app’s #data= URL, pass it to MSAModelF().create, set it
through MSAViewer props, or give it to the R widget. The viewer draws each
layer as given, keeps it in a shared URL, and includes it in the SVG export.
Wherever a layer names a row, positions are that row’s residues, 1-based and
inclusive, as in GFF, and the viewer projects them through the alignment’s gaps.
Without a row, positions are alignment columns.
Every figure below links to the app in the state it shows. Each one is an
MsaView snapshot. To open one, put its JSON in #data=, either bare or
wrapped as {"msaview": {...}}, the form the app writes back to the address
bar. The JSON can go in as typed:
https://gmod.org/JBrowseMSA/demo/#data={"type":"MsaView","msaFilehandle":{"uri":"data/p53/p53-vertebrates.afa"},"relativeTo":"Human"}
A script can URL-encode it instead. The encoded link survives a chat message or a markdown file that would cut a link short at a quote or a space:
const snapshot = {
type: 'MsaView',
data: { msa: '>human\nMKAANSE\n>mouse\nMKA-NSE' },
}
const url = `https://gmod.org/JBrowseMSA/demo/#data=${encodeURIComponent(JSON.stringify(snapshot))}`
The user guide covers what else a link needs: file URIs, CORS, and the size limit on inline data.
Shorthand
A link or a script can write a view in short forms, which expandSpec (exported
from react-msaview) turns into the snapshot. The app’s #data= and
jbrowse-plugin-msaview’s session spec both apply it, and a full snapshot passes
through unchanged.
{
"type": "MsaView",
"msa": "https://gmod.org/JBrowseMSA/demo/data/p53/p53-vertebrates.afa",
"tree": "https://gmod.org/JBrowseMSA/demo/data/p53/p53-vertebrates.nh",
"query": "Human",
"highlights": ["102-292 DNA-binding", 175, 248, 273],
"region": "170-290",
"columnTracks": [
{
"name": "ClinVar",
"color": "#c0392b",
"encoding": { "y": { "scale": { "domainMax": 8 } } },
"start": 104,
"values": [2, 1, 0, 0, 2, 4]
}
]
}
| Short form | Expands to |
|---|---|
msa |
msaFilehandle for a url, data.msa for text spanning more than one line |
tree |
treeFilehandle for a url, data.tree for newick text starting with ( |
query |
relativeTo, and the row of every highlight, region and column track that names none |
a highlight 175 |
residue 175 of the query row, labeled with its letter and number, “R175” |
a highlight "102-292 DB" |
residues 102-292 labeled “DB”; "248" is residue 248 and "248 hotspot" labels it |
region: "170-290" |
{row, start: 170, end: 290} |
a column track’s id |
taken from name when absent, “ClinVar pathogenic” becoming clinvar-pathogenic |
a column track’s kind |
bar for values, text for data, arc for arcs, features for features |
a column track’s start |
the position its values or data begins at, so leading zeros stay out of the link |
Without query, the same highlight forms are alignment columns and a single one
gets no label. "row": null on an object entry takes it off the query row onto
alignment columns. A highlight’s label may name {residue} and {position},
which the viewer fills from the row’s letter at start: 175 expands to the
label {residue}{position}. A malformed string, such as "R175" or
"170..290", opens the view on an error naming it.
columnTracks
A track above the alignment, supplied as data. kind picks what it draws: bar
and strip read values, text reads data, arc reads arcs, features
reads features. row makes any of them index that row’s residues instead of
alignment columns, so the first one is residue 1 and the viewer fills in the
row’s gaps. A data track appears in the Tracks menu, toggles like any other, and
exports to SVG.

{
"type": "MsaView",
"data": { "msa": ">human\nMKAANSE\n>mouse\nMKA-NSE" },
"columnTracks": [
{
"id": "dnds",
"name": "dN/dS",
"kind": "bar",
"values": [0.1, 0.4, 1.8, 0.2, 0.3, 0.1],
"encoding": {
"y": { "scale": { "domainMax": 2 } },
"color": {
"scale": {
"type": "threshold",
"domain": [1],
"range": ["#2c7fb8", "#d7301f"]
}
}
},
"row": "human"
},
{
"id": "frame",
"name": "Codon frame",
"kind": "text",
"data": "1231231",
"encoding": {
"color": {
"scale": {
"domain": ["1", "2", "3"],
"range": ["#ddd", "#bbb", "#999"]
}
}
}
},
{
"id": "disulfides",
"name": "Disulfide bonds",
"kind": "arc",
"arcs": [
{ "start": 31, "end": 96 },
{ "start": 43, "end": 109 }
],
"color": "#b8860b",
"row": "human"
}
]
}
| Field | Kind | Meaning |
|---|---|---|
id |
all | Unique key. The Tracks menu and turnedOffTracks use it |
name |
all | Label beside the track, and the title of its legend when legend.title is unset |
values |
bar, strip | One number per column, or per residue of row; null draws nothing |
encoding.y |
bar | {scale: {type, domainMin, domainMax, domainQuantile}}, how a value maps onto the bar’s height |
encoding.color |
bar, strip | {value}, one color, or {scale, legend}, a color per value |
encoding.color |
text | {value}, or {scale, legend} over the upper-case characters, painted on the channel residueColor names |
encoding.color |
arc | {value}, or {scale, legend} over each arc’s value |
color |
bar, text, arc | Shorthand for encoding.color: {value}, read while encoding.color is unset (default gray bars, theme-colored arcs) |
data |
text | One character per column, or per residue of row |
arcs |
arc | {start, end, color?, value?, name?} pairs; each end is a column or a residue |
features |
features | {start, end, strand?, ...} spans; see the features track |
row |
all | Row name whose residues the values or characters index |
height |
all | Pixel height (default 40 for a bar, 12 for a strip, 50 for an arc, the row height for text, 18 per lane for features) |
A row on an arc track carries both ends of every arc, so a contact map
computed in a protein’s own numbering lands on the alignment without conversion.
The viewer draws arcs on one baseline in the order given, and a color on an
individual arc overrides the track’s and its scale’s, as a GFF color=
attribute does, so one track can separate nested helices from a pseudoknot. The
tooltip over an arc’s stroke lists the arcs under the pointer, each with its
name and its two ends as given, and those arcs draw at 2px while the pointer
is on them.
Column track scales
encoding.color on a column track is the color object of
encodings, with the track’s own values in place of a field: a
bar’s or a strip’s numbers, each arc’s value, a text track’s characters. It
holds one color as {"value": "#6a51a3"}, or a scale and a legend that read
the values, and the bare color member is shorthand for the first. A {value}
keeps the object one color even beside a scale.
The dN/dS bar above reads its values through a threshold at 1, so a codon above
1 draws red and one below draws blue, and the legend lists the two intervals. A
scale over the track’s values lists a legend while the track is shown, titled by
legend.title or else the track’s name, and two tracks declaring the same
scale and title share one legend and one set of colors.
Scale problems name the record as
columnTracks[0].encoding.color.
A strip track draws one cell per column, the full track height, in the color
encoding.color gives its value, which makes a heatmap row of a per-residue
score: AlphaFold’s pLDDT, a disorder prediction, a hydropathy scale. A column
with no value draws nothing. A strip with no encoding.color reads its values
through the default ordinal scale, one color per distinct value, and its legend
notes that scale: {"type": "linear"} draws them on a ramp.
{
"id": "plddt",
"name": "pLDDT",
"kind": "strip",
"row": "human",
"values": [96.2, 94.8, 71.3, 48.0, 33.5],
"encoding": {
"color": {
"scale": {
"type": "threshold",
"domain": [50, 70, 90],
"range": ["#ff7d45", "#ffdb13", "#65cbf3", "#0053d6"]
},
"legend": {
"title": "pLDDT",
"labels": ["very low", "low", "confident", "very high"]
}
}
}
}
An arc track’s scale reads each arc’s value, such as a contact probability,
and an arc with no value draws in the track’s color. Under
scale: {"type": "identity"} an arc track reads each arc’s own color, so
domain and legend.labels give the arcs’ colors a legend, as they give a
GFF’s color= one. On a bar, strip or text track an identity scale paints each
value that names a color and leaves the rest undrawn.
encoding.y.scale is the value scale of a bar row panel’s encoding.x,
mapping a bar’s value onto its height. A linear scale, the default, draws
domainMin (default 0) at no height and domainMax (default 1) at the full
height, so values are fractions of 1 until domainMax says otherwise. A log
scale spaces the values by orders of magnitude and takes an unset end from the
track’s positive values, clipped at domainQuantile as a color ramp’s end is. A
value past an end draws at that end, and a value at or below 0 on a log scale
draws no bar.
Hovering a bar or a strip prints the value as given, and hovering an arc’s end
prints each partner with its value.
An RNA Stockholm file needs no arc track, because #=GC SS_cons already pairs
the columns. The viewer draws a Base pairs track from it and gives
pseudoknot pairs their own color. WUSS writes a pseudoknot pair as A/a
because it crosses a helix, and brackets can only nest.
A track over 50 kB serialized stays in the live model but leaves the snapshot,
under the same size rule
that applies to inline alignments. The demo app raises the limit to 1 MB, as
much as its links hold, and MSAModelF({ maxInlineSnapshotBytes }) sets it for
another host. To go past it, host the values and set them at runtime with
model.setColumnTracks(...).
The features track
A features track draws spans over the columns with the mark a features row
panel draws in each row: an arrow where a span carries a strand, a box
otherwise, labeled where the text fits. Spans that overlap pack into lanes, and
the track is 18 pixels tall per lane until a height or a drag sets it.
Secondary-structure blocks, the Pfam domains of the reference row and the exons
along a DNA alignment each make one.
The insulin example in the examples catalog draws two: the precursor’s signal, B chain, C peptide and A chain from UniProt P01308, and the helices and strand UniProt takes from PDB 3W7Y.
{
"id": "ss",
"name": "Secondary structure",
"kind": "features",
"row": "Human",
"features": [
{ "start": 33, "end": 43, "type": "helix" },
{ "start": 48, "end": 50, "type": "strand", "strand": "+" },
{ "start": 91, "end": 97, "type": "helix", "color": "#9467bd" }
],
"encoding": {
"fill": {
"field": "type",
"scale": {
"domain": ["helix", "strand"],
"range": ["#e15759", "#edc948"]
},
"legend": { "title": "Secondary structure" }
},
"text": { "field": "type" }
}
}
| Field | Meaning |
|---|---|
features |
spans with a start and an end, 1-based and inclusive, in columns or in residues of row |
encoding |
{fill: {field, scale, legend}, text: {field}} over the spans’ fields, or fill: {value} |
color |
shorthand for encoding.fill: {value}, read while fill is unset (default light grey) |
position |
identity packs overlapping spans into lanes; strandpile puts forward spans above reverse ones |
A span’s strand of + or - draws it as an arrow pointing that way. A span’s
own color wins over the scale and the track’s color, as a GFF color=
attribute does, so the last helix above draws purple. Every other field, such as
type, name or a host’s own source, is one the encoding reads, as a string.
encoding.fill is the color object of encodings and of a features row
panel. While the track is shown its scale lists a legend, titled by
legend.title or else the field, and a track and a panel declaring the same
scale share one legend and one set of colors. A value the scale gives no color
draws grey. encoding.text names the field drawn inside each span.
Hovering the track lists every span at that column with its fields. Hiding gappy
columns moves each span onto the visible columns, shrinks one that crosses
hidden columns, and drops one lying on hidden columns alone. An end past the end
of row clamps to its last residue.
highlights
A labeled band over a column range or a residue range, or a tint over a set of
rows. label and color are optional; color is any CSS color and paints the
band, its border, or the row tint.

rows entry over the
five non-mammals, labeled in the tree gutter."highlights": [
{ "row": "human", "start": 248, "end": 248, "label": "R248Q · 651/658 R" },
{ "start": 40, "end": 60, "label": "NES", "color": "rgba(0,120,255,0.25)" },
{ "rows": ["beluga", "dolphin"], "label": "frameshift carriers" }
]
row plus start/end is a residue range of that row, start/end alone is
a column range, and rows marks whole rows across the tree labels and the
alignment. A range that lands entirely on hidden gappy columns draws nothing;
one that straddles them shrinks to the visible part. The viewer ignores row
names that match no row.
"mark": "bracket" draws a range as an outline over the alignment, which keeps
the residue and domain colors under it, plus a labeled bracket in a Highlights
strip above the first row. Nested and overlapping brackets stack into lanes, and
a single residue draws as a triangle. Hovering a bracket outlines its columns; a
click selects them and a double click zooms to them. The default, "band",
fills the range and labels it at the top. Hovering a cell lists every range
covering it, with its residues and its alignment columns, for either mark.
Turning the Highlights strip off draws the brackets as bands.
"highlights": [
{ "row": "SARS-CoV-2", "start": 319, "end": 541, "label": "RBD", "mark": "bracket" },
{ "row": "SARS-CoV-2", "start": 437, "end": 508, "label": "RBM", "mark": "bracket" }
]
React: the highlights prop on MSAViewer, or model.setHighlights(list). R:
msaview(highlights = list(list(row = "human", start = 248, end = 248))).
For a transient highlight, such as one following a hover in a structure viewer
or a genome browser, call model.applyHighlight(owner, list) and
model.clearHighlight(owner). They take the same shape, draw over the persisted
highlights, and stay out of the snapshot. clearHighlight(owner) removes only
that owner’s highlights, so two sources can highlight at once.
region takes the same coordinates and names where the view opens:
{"row": "Human", "start": 170, "end": 290} zooms onto those residues and
scrolls the Human row to the middle, once the alignment and any tree file have
loaded. The viewer then clears it, so a reloaded session keeps the reader’s own
scroll. model.revealRegion(region) does the same at runtime, and
model.zoomToRegion(region) zooms without touching the vertical scroll.
selection
A block of the alignment, selected: columns start to end of the file,
1-based and inclusive, across the rows rows names, or across every row where
rows is absent. The viewer draws it as a bordered blue band, and a shift-drag
in the viewer replaces it, so a link can open on a block and a script can read
back the block a person chose.
{
"type": "MsaView",
"data": { "msa": ">human\nMKAANSE\n>mouse\nMKA-NSE\n>chicken\nMKSANSE" },
"selection": { "start": 2, "end": 5, "rows": ["human", "mouse"] }
}
Open this snapshot in the app.
start and end count every column of the file, hidden gappy ones included,
the way a column highlight does, so hiding gaps leaves the band on the same
residues. A selection that lies entirely on hidden columns draws nothing. The
header’s selection menu copies the block as FASTA across those columns, gaps
kept, zooms to it, and trims the view to it.
trimToSelection: true hides every column outside the selection, the way
hideGaps hides gappy ones, and the two combine. The tracks, the highlights,
the minimap, the structure panel and the SVG export draw the remaining columns,
and the position ruler and the “Find” box keep the file’s column numbers.
Clearing the selection clears the trim. The trim leaves every row in place,
since hiding rows by name would prune the tree; a focus clade hides rows.
The SVG export’s Selection only choice draws the block: its columns, and the
rows from the first selected to the last in the order the view draws them.
react-msaview-cli export-svg --selection draws the same block from a --spec
or --props that holds a selection, and an export of a snapshot with
trimToSelection draws only the selected columns.
React: the selection and trimToSelection props on MSAViewer, with
onSelectionChange reporting each change the reader makes, or
model.setSelection(block) and model.setTrimToSelection(true). R:
msaview(selection = list(start = 2, end = 5, rows = c("human", "mouse"))) or
geom_msa_selection(2, 5, rows = c("human", "mouse")), with
input$<id>_selection in Shiny. Python: the selection trait, which the widget
also writes back, and trim_to_selection.
relativeTo
The name of a row to read every other row against. With one set, the viewer:
- draws a residue matching the reference row’s residue in its column as a dot on a grey cell, so only the differences keep their color
- repeats the reference row as a track pinned above the alignment, so it stays in view while the rows under it scroll; the row keeps its place in the tree
- numbers the position ruler and the track tooltips in the reference row’s own residues, and reads a number typed into the Go to row or column box as one of them
{
"type": "MsaView",
"data": { "msa": ">human\nMKAANSE\n>mouse\nMKA-NSE\n>chicken\nMKSANSE" },
"relativeTo": "human"
}
Open this snapshot in the app.
The pinned track’s id is reference-row, so
"turnedOffTracks": { "reference-row": true } keeps the dots and drops the
copy. In the shorthand, query sets relativeTo and also names the row whose
residues the highlights count.
React: the relativeTo prop on MSAViewer, or model.drawRelativeTo(name). R:
msaview(relative_to = "human") or + stat_msa_diff("human"). Python: the
relative_to trait.
clades
A clade of the tree with a mark over it. mark takes one of five values:
highlightfills the rows behind the clade with a translucent rectangle, running from the clade’s common ancestor to the right edge of the tree area and on across the alignment, which is ggtree’sgeom_hilight.bracketdraws a vertical bar beside the clade’s rows carrying the record’slabel, which is ggtree’sgeom_cladelaband, over arange,geom_strip.collapsecollapses the clade at load, the way the branch menu’s “Collapse clade” does.focusopens the viewer on the clade alone, the way “Show only this clade” does.rotateswaps the order of the clade’s children at load, the way “Rotate clade” does, which is ggtree’srotate. The rows follow the tips.

highlight and a bracket over the same mrca; the clade under it carries a
collapse and draws as a triangle labeled with its six tips. Tip labels take
their color from an encodings entry over the phenotype field."clades": [
{
"mrca": ["Gs/TW/TNC1/2015", "Ck/TW/a174/2015"],
"tips": 47,
"mark": "highlight",
"color": "#fff3c4",
"label": "2.3.4.4 H5Nx"
},
{
"mrca": ["Gs/TW/TNC1/2015", "Ck/TW/a174/2015"],
"tips": 47,
"mark": "bracket",
"color": "#b45309",
"label": "2.3.4.4 H5Nx"
},
{ "mrca": ["Dk/VN/1/2012", "Ck/VN/14/2012"], "tips": 6, "mark": "collapse" }
]
mrca names tips whose most recent common ancestor is the clade, and the mark
covers every tip under that ancestor. Two names are enough for a clade of any
size, and a name the tree does not have, or has twice, drops the record.
tips is the leaf count the producer measured. The viewer counts the leaves
under the ancestor it resolved, and a count that differs drops the clade, so a
re-rooted or re-estimated tree loses the mark instead of drawing it over a
different clade.
range takes the two ends of a run of tips in display order, in either order,
and covers every tip between them, monophyletic or not. Its tips is checked
against the length of the run:
{ "range": ["Dk/VN/1/2012", "Ck/VN/14/2012"], "tips": 6, "mark": "highlight" }
color is any CSS color, defaulting to a light yellow. A highlight’s color
carrying no alpha of its own draws at 60% opacity, so the branches and the
residues under it stay readable. A bracket draws its bar and its label in that
color at full strength, and takes the theme’s text color without one.
The bracket gutter is at the right of the tree area, between the tip labels and
the first row panel or the alignment, as wide as the bar plus the widest label
at the tree font, to a limit of 140px, past which a label is cut with an
ellipsis. A label reads across the rows where they are taller than the font, and
runs up the bar where they are not. A highlight record carrying a label
draws it the same way, with no bar.
collapse, focus and rotate seed the viewer’s own collapsed, showOnly
and rotated lists when the tree resolves, so hideGaps counts the rows that
remain exactly as when the user collapses a clade by hand. The three marks name
a node, so they need mrca: a range record carrying one of them drops.
Expanding a seeded clade or clearing the focus holds until the tree is rerooted,
and the record applies again the next time the link is opened.
Every mark resolves against the tree as loaded, so collapsing a clade’s ancestor or focusing on part of the tree keeps the mark on the rows that remain on screen.
React: the clades prop on MSAViewer, or model.setClades(list). R:
geom_msa_clade(c("Gs/TW/TNC1/2015", "Ck/TW/a174/2015"), tips = 47).
treeOrder and treeRoot
treeOrder sets the order each node’s children draw in, top to bottom, and the
rows of the alignment follow the tips:
branchLength, the default, puts the child with the shorter branch first.inputkeeps the order the tree file gives.ladderizeputs the child with fewer tips first, so the deep clades step down toward the bottom, which is ape’sladderizeasplot.phylodraws it.ladderizeReverseputs the child with more tips first, which is ggtree’s default.
A rotation from the branch menu or a rotate clade reverses one node’s children
after the order applies. “Undo rotations” in the tree settings clears them.
treeRoot reroots the tree before the viewer draws it. "midpoint" puts the
root halfway along the longest path between two tips, the usual root for the
unrooted trees FastTree, IQ-TREE and neighbor joining write. An outgroup puts it
halfway along the branch above the tips’ most recent common ancestor:
"treeRoot": { "outgroup": ["Dk/VN/1/2012", "Ck/VN/14/2012"] }
Where that ancestor is the root of the file’s tree, the outgroup straddles the root, and the viewer roots above the common ancestor of the other tips, which is the same branch of the unrooted tree. A tree whose outgroup resolves to neither side, or names a tip it does not have, keeps its own root.
A support value labels the branch above its node. When the viewer reroots, the nodes between the new root and the old one turn over, and each support value moves with its branch to the node now at the lower end of it. A root with two children has one branch left once the new root takes one of them, so the viewer drops it and joins its two branches into one.
“Reroot here” in the branch menu writes the outgroup as the first and last tip
of the node’s side of the split in the file’s tree, so a second reroot resolves
against the file and the link stays short. Rerooting renumbers the nodes, so it
clears collapsed, rotated and showOnly, and the collapse, focus and
rotate clades seed again on the new tree.
React: the treeOrder and treeRoot props on MSAViewer, or
model.setTreeOrder(order) and model.setTreeRoot(root). R:
coord_tree(order = "ladderize", root = "midpoint"), or root as a vector of
outgroup tip names. Python: tree_order and tree_root, the latter
"midpoint", one tip name or a list of them.
rowData
A table of fields per row, keyed by row name: a lineage, a host, a collection
date, a kinase group. The encodings below color the viewer’s marks by one of
these fields, the tree’s node-info dialog lists a row’s fields, and the tip
labels draw the field a rowLabel encoding names, else a genome field, else
the row name.
The model keeps the table as the JSON string data.treeMetadata, the field name
that travels in existing links, so a snapshot carries it there:
{
"type": "MsaView",
"data": {
"msa": ">duck\nMKAANSE\n>chicken\nMKA-NSE",
"treeMetadata": "{\"duck\":{\"clade\":\"2.3.4.4b\"},\"chicken\":{\"clade\":\"2.3.2.1c\"}}"
}
}
Open this snapshot in the app.
Everywhere else the table is an object: the rowData prop on MSAViewer,
model.setRowData(table), geom_msa_rowdata(df) in R, and the row_data trait
in Python. R takes a data frame whose label or row column names each row and
whose other columns are the fields, the shape a ggtree
tibble(label = , trait = ) has.
A field’s value can be a string, a number or a boolean. The viewer reads a
number or a boolean as its string, 2015 as "2015", the way it reads a GFF
attribute, and leaves out a null or a nested object.
A real metadata table needs the filehandle. Five thousand rows with eight fields
run to roughly 700 kB, far past the 50 kB inline limit a jbrowse session keeps,
so the snapshot drops the table and unshareableData reports the drop. Host the
JSON and set treeMetadataFilehandle to its URL, and the viewer fetches the
table at startup:
{
"type": "MsaView",
"msaFilehandle": { "uri": "https://example.org/h5.fa" },
"treeMetadataFilehandle": { "uri": "https://example.org/h5-lineages.json" }
}
features
Features on the rows as JSON, the form a GFF line takes once parsed: row,
start and end in residues of that row, 1-based and inclusive, with an
optional name, description, type, strand and color. The viewer draws
them in the annotation overlay beside the GFF’s, under the same legend, filter
dialog and feature channels.
{
"type": "MsaView",
"data": { "msa": ">human\nMKAANSEMKAANSE\n>mouse\nMKA-NSEMKA-NSE" },
"features": [
{ "row": "human", "start": 2, "end": 7, "name": "SH3", "source": "pfam" },
{ "row": "mouse", "start": 3, "end": 9, "name": "SH2", "source": "smart" }
],
"encodings": [{ "channel": "featureFill", "field": "source" }]
}
Open this snapshot in the app.
name is the key the legend, the accession palette and the filter dialog group
features by, and an unnamed feature takes row:start-end. color overrides the
palette and any scale, as a GFF color= attribute does. A strand of + or
- draws the span as an arrow whatever its type, and a type of exon,
CDS or a UTR draws it as a numbered segment. Every other field, such as
source above, is a column the featureFill and featureLabel channels read
the way they read a GFF attribute.
A host that computes its spans passes them here, and a file of them loads
through data.gff or gffFilehandle. React: the features prop on
MSAViewer, or model.setFeatures(features). R: a data frame given to
msaview(gff = ) or geom_msa_domains(), with a row (or seqname) column
and every other column a field. Python: the features trait, which takes a list
of dicts or a DataFrame.
encodings
What the viewer’s own marks read from a table. Each entry names a channel, the
field feeding it, and the color object: the scale that turns a field value
into a color, with its domain of values and the range of colors or the
scheme they map onto, and the legend that guides it. The spelling is
Vega-Lite’s, and jbrowse-components’ displays write the same records.

tipLabel and
branch over the phenotype field, and rowTint over the subclass field through
a domain that names one of its two values, so the alleles it leaves out take
no tint. Each field lists its own legend.{
"type": "MsaView",
"data": { "msa": ">duck\nMKAANSE\n>chicken\nMKA-NSE" },
"encodings": [
{ "channel": "tipLabel", "field": "clade", "scale": { "scheme": "set1" } },
{
"channel": "rowTint",
"field": "clade",
"scale": { "domain": ["2.3.4.4b"], "range": ["#e41a1c"] }
}
]
}
| Field | Meaning |
|---|---|
channel |
one of the seven below |
field |
the field the channel reads |
scale.type |
ordinal (the default), linear, log, threshold or identity |
scale.domain |
an ordinal scale’s values in legend order, each taking the range color at its index; a threshold scale’s cuts; the colors an identity scale’s legend lists |
scale.range |
a list of colors: one per value, a ramp’s stops, or one per threshold interval |
scale.scheme |
a palette name for an ordinal scale, a ramp name for the others, read where range is unset |
scale.domainMin |
a ramp’s low end; the field’s lowest value when unset |
scale.domainMax |
a ramp’s high end; the field’s highest value when unset |
scale.domainMid |
the value a ramp’s middle color marks, for a diverging ramp such as redblue |
scale.domainQuantile |
the nearest-rank quantile an unset end follows, from 0.5 to 1 (default 1, the extremes) |
scale.reverse |
true turns the ramp round |
legend.title |
the legend’s title; records with the same scale and title share one scale |
legend.labels |
the legend’s name for each ordinal or identity domain value or each threshold interval, in order |
legend.missingLabel |
the grey legend row for a record with no value, which then draws grey |
| Channel | What it sets | Reads a field of |
|---|---|---|
tipLabel |
the color of each tip label in the tree | rowData |
rowTint |
a wash over the row, across the tree gutter and the alignment | rowData |
branch |
the color of a tree edge whose tips all share one value | rowData |
nodePoint |
the fill of the bubble on each internal node of the tree | the tree, field support |
rowLabel |
the text of each tip label in the tree | rowData |
featureFill |
the fill of each span of the annotation overlay | the gff |
featureLabel |
the text drawn inside a span | the gff |
A scheme is one of ggplot (the default), set1, dark2, okabeito and
tableau, with okabeIto and tableau10 read as aliases. The scale hands its
colors to the field’s distinct values: the values domain lists first, in that
order, then the rest in natural order, numbers by value and digit runs by
magnitude, so 2 sorts before 10 and 2.3.2.1a before 2.3.4.4b. A value
keeps its color as rows are collapsed, filtered or re-ordered. Past the end of a
named palette every value takes an evenly spaced hue instead, which keeps a
forty-clade field readable.
A range colors as many values as it holds, so a domain and a range of one
length color the values they name, and a value they leave out keeps the plain
mark: an uncolored tip label draws in the theme’s text color, an uncolored row
takes no tint, and an uncolored span draws grey.
A tint draws at 25% opacity so the residues under it stay readable. A color
carrying its own alpha, such as rgba(228,26,28,0.5), draws at that alpha.
The branch channel gives an internal node the field’s value when every tip
below it shares that value, and that node’s edge and every edge inside the clade
draw in the scale’s color for it. An edge whose tips disagree draws in the
default color, and a collapsed clade’s triangle takes the color of the value its
tips agree on. This is ggtree’s groupClade followed by aes(color = group),
with the group read from the table.
Every scale an encoding reads carries a legend, titled by legend.title or else
the field name, drawn by the overlay on screen and reserved as a column in the
SVG export. Two channels declaring the same members over one field list it once.
A legend lists at most 20 rows, then a +N more line counting the rest.
A field whose every value is a number still takes ordinal colors, one per
distinct value, until the record names scale: {"type": "linear"}. Its legend
carries a note saying so.
Linear, log and threshold scales
A linear or log scale reads each value as a number and colors it from a ramp
between domainMin and domainMax. Its legend is a gradient bar with the two
ends printed under it. A log scale spaces the ramp by orders of magnitude and
reads only the positive values.
{
"channel": "tipLabel",
"field": "year",
"scale": {
"type": "linear",
"scheme": "viridis",
"domainMin": 2000,
"domainMax": 2024
}
}
The ramps are viridis (the default), magma, inferno, cividis, reds,
blues, redblue and purpleorange, the tables jbrowse-components bakes. A
range of two or more colors makes a ramp of its own, evenly spaced. A value
past a pinned end draws in the end color, and the legend prints that end as
≤2000 or ≥2024.
An end left unset follows the field’s values: the lowest and the highest, or
with domainQuantile below 1 the nearest-rank quantile at each end, so 0.99
sets aside the outermost 1% and one outlier date leaves the rest of the ramp in
use. A scale with an unset end is resolved per field. A scale pinned at both
ends is its declaration, so two strips over different fields with the same
pinned scale share one ramp and one gradient legend.
A threshold scale cuts the number line at the values domain lists, in
ascending order, and colors each interval from range, which is one longer than
domain. Without a range each interval takes an evenly spaced color of its
scheme. The legend lists every interval, as < 50, 50 – 70, 70 – 90 and
≥ 90, or under the names legend.labels gives them:
{
"channel": "featureFill",
"field": "plddt",
"scale": {
"type": "threshold",
"domain": [50, 70, 90],
"range": ["#ff7d45", "#ffdb13", "#65cbf3", "#0053d6"]
},
"legend": { "labels": ["Very low", "Low", "Confident", "Very high"] }
}
On a continuous or threshold scale a value that is no number, such as NA,
draws grey and lists under a grey not a number row. legend.missingLabel
renames that row, and records with no value at all then draw grey under it too.
The identity scale
An identity scale reads each value as the CSS color it names: #e41a1c,
steelblue, or 255,0,0, which reads as rgb(255,0,0). A producer that has
already chosen its colors writes them into the table and declares the scale. The
legend lists the colors domain names, in that order and under the names
legend.labels gives them, and only those some record holds. With no domain
the legend lists nothing.
{
"channel": "featureFill",
"field": "color",
"scale": { "type": "identity", "domain": ["#d7191c", "#2c7bb6"] },
"legend": { "title": "ClinVar", "labels": ["pathogenic", "benign"] }
}
A GFF color= attribute colors its own feature through the same rule before any
scale, and the feature table holds it as color, so the record above gives a
GFF’s own colors a legend. A range or a scheme on an identity scale is never
read, and scaleProblems reports it.
Scale problems
Some combinations of members contradict each other, and the viewer draws what it
can and reports them: a domainMax below its domainMin, threshold cuts out of
ascending order, a threshold range that is not one longer than its domain, a
domainQuantile outside 0.5 to 1, legend.labels of a different length from
what it names, a scheme no table holds, and a range or scheme on an
identity scale. model.scaleProblems lists each one with the record that
declares it (encodings[0], rowPanels[2].encoding.fill), the member (slot)
and a message. The scale’s legend carries the first as a note, and
react-msaview-cli export-svg --spec prints every one to stderr as
record.slot: message. The rules and their messages are jbrowse-components’
colorProblems. A bar or point panel’s value scale reports its ends’ problems
the same way, under rowPanels[i].encoding.x, and a bar track’s under
columnTracks[i].encoding.y.
Hiding a category
A click on a row of an ordinal or identity scale’s legend hides that value, and a second click shows it again. The overlay strikes a hidden row through, and the SVG export leaves it out of the legend and the figure.
- A hidden
rowDatavalue leaves the marks it colors unpainted: a strip draws no cell, a bar, point or text panel draws no bar, dot or text for a row itsencoding.colorreads the value in, a tip label and a branch draw in the default color, and a row takes no tint. The row stays in the tree and the alignment; arowTransformfilter drops rows. - A hidden feature value takes the features carrying it out of the overlay, the
featurespanels and thefeaturestracks, and out of their tooltips. - A hidden
supportvalue leaves its node’s bubble plain. - A hidden value of a column track, whose legend’s field is the track’s
name, leaves the bar, strip cell, character or arc holding it undrawn, and the bar’s or cell’s tooltip empty.
The hides persist as hiddenCategories, a list of {field, value}, and travel
in the snapshot and the shared URL. A hide applies wherever an ordinal or
identity scale reads its field, in any table, and waits unapplied while none
does. A legend shared by several fields hides the value in each of them.
{ "hiddenCategories": [{ "field": "clade", "value": "2.3.2.1c" }] }
The accession key, which colors spans by accession where no featureFill
encoding is set, hides a feature type through the filter dialog’s own state,
turnedOffFeatures, so a click in the key and a checkbox in the dialog are one
switch. A ramp or a threshold scale lists no row a click hides.
The feature channels
A feature channel reads any field of the feature table: accession, name,
featureType, any GFF attribute of column 9, such as Name or gene, or any
field of a features record.

description attribute: featureFill colors each span from a
set1 scale and featureLabel draws the same value inside it.{
"type": "MsaView",
"data": {
"msa": ">duck\nMKAANSE\n>chicken\nMKA-NSE",
"gff": "##gff-version 3\nduck\tncbi\tgene\t1\t5\t.\t+\t.\tName=HA;class=surface\nchicken\tncbi\tgene\t1\t4\t.\t+\t.\tName=NP;class=internal;color=255,0,0"
},
"encodings": [
{
"channel": "featureFill",
"field": "class",
"scale": { "scheme": "set1" }
},
{ "channel": "featureLabel", "field": "Name" }
]
}
The featureFill scale replaces the accession palette the overlay colors spans
by, so a span whose value the scale gives no color draws grey, and the domain
legend lists that scale’s values under the field’s name. A feature carrying a
GFF3 color= attribute keeps that color whatever the scale says, and 255,0,0
reads as rgb(255,0,0), the convention JBrowse and IGV honor. A featureLabel
draws inside its span wherever the text fits, and it is a data channel, so it
draws whether or not the residue letters do.
The tree channels
nodePoint fills the bubble on each internal node from the node’s support
value, ggtree’s geom_nodepoint(aes(color = support)). Its one field is
support, the label a Newick file writes after a node’s closing paren: 95 and
80 in ((A,B)95,(C,D)80);. The parser keeps that label as a string, so a
threshold scale reads bootstrap percentages into bands and an ordinal scale
reads named clades. A node with no label keeps the plain bubble, and the bubbles
draw while drawNodeBubbles is on, its default. The tree overview draws no node
points.
{
"channel": "nodePoint",
"field": "support",
"scale": {
"type": "threshold",
"domain": [70, 95],
"range": ["#d7191c", "#fdae61", "#1a9641"]
}
}
rowLabel names the rowData field each tip label draws, so a tree keyed by
accession can print strain names: {"channel": "rowLabel", "field": "strain"}.
A row with no value in that field draws its row name. With no rowLabel
encoding the labels read a genome field. The tree area fits the labels it
draws.
residueColor
The color object of the residue mark, {channel, field, scale}:
channelis what the color paints:fill(the default) colors the cell, andcolorcolors the letter and leaves the cell plain.fieldis what a cell reads:feature(the default) takes the color the annotation overlay gives the span covering the cell, andresiduetakes the residue’s color throughscale. Thecolorchannel reads the residue.scaleholdsscheme, a built-in scheme name (maeditorwhere unset), ordomainandrange, a color per residue letter. Adomainwins overscheme.
{
"type": "MsaView",
"data": { "msa": ">human\nMKAANSE\n>mouse\nMKA-NSE" },
"residueColor": {
"scale": {
"domain": ["K", "R", "D", "E"],
"range": ["#1f77b4", "#1f77b4", "#d62728", "#d62728"]
}
}
}
Open this snapshot in the app.
Under field: "feature" the domains fill the cells only while the overlay draws
a span, so an alignment with no annotations keeps its residue colors and a
loaded GFF fills the cells its spans cover. A span takes the color the overlay
draws it in: its GFF color=, a featureFill encoding, or the accession
palette. Under field: "residue" or the color channel, the scale keeps the
residue colors and each domain draws as a bar under its row.
The letters a domain lists take the range color at their own index, and
every other letter is uncolored, the rule a domain and range in encodings
follow. The viewer upper-cases every row before coloring it, as the built-in
schemes expect, so a letter matches in either case. A gap is uncolored unless
the domain lists - or .. The letters color the sequence logo too.
Three schemes color a cell from its column’s statistics, so one letter takes a
different color in each column: clustalx_protein_dynamic, blosum62_dynamic
and percent_identity_dynamic. A domain wins over these too.
Settings → Color writes the same object. Domains sets
field: "feature", a scheme sets scale.scheme, drops the letters and hands
the cells back to the residues, and Color the letters, not the cells sets
channel: "color".
A link written before residueColor carries the keys bgColor,
colorSchemeName, customColorScheme and domainFill, and the viewer reads
them into residueColor when it opens the link: bgColor: false is
channel: "color", domainFill: false is field: "residue", colorSchemeName
is scale.scheme, and a customColorScheme map is scale.domain and
scale.range.
React: residueColor={{ scale: { domain: ['K'], range: ['#1f77b4'] } }} on
MSAViewer, or model.setResidueColor(color). R:
scale_residue_color(c(K = "#1f77b4")). Python:
residue_color={"scale": {"domain": ["K"], "range": ["#1f77b4"]}}.
rowPanels
A panel beside the tree on the row scale, the counterpart of columnTracks on
the column scale. Each record names a kind. A strip reads a field of
rowData and fills each row’s cell through its color object, and eight strips
make the tip-aligned matrix ggtree draws with gheatmap. A features panel
draws the spans gff carries, one row per alignment row, which is gggenes. A
bar, point or text panel draws a number or a string from rowData beside
each row, which is ggtree’s geom_facet.

title, so the matrix carries a single key for its
residue colors.{
"type": "MsaView",
"data": {
"msa": ">duck\nMKAANSE\n>chicken\nMKA-NSE",
"treeMetadata": "{\"duck\":{\"HA\":\"H5\",\"NA\":\"N1\"},\"chicken\":{\"HA\":\"H5\",\"NA\":\"N8\"}}"
},
"rowPanels": [
{
"kind": "strip",
"encoding": { "fill": { "field": "HA", "scale": { "scheme": "set1" } } },
"width": 12
},
{
"kind": "strip",
"encoding": { "fill": { "field": "NA" } },
"header": "NA segment"
}
]
}
| Field | Meaning |
|---|---|
kind |
strip, features, bar, point or text |
encoding |
a strip’s {fill: {field, scale, legend}}, the color object of encodings |
width |
the column’s pixel width: a row height for a strip, 200 for features, 80 for bar, point, text |
header |
the name drawn above the column, defaulting to the field a strip, bar, point or text reads |
A strip’s fill reads a rowData field, and its legend.title names the
legend its values list under, defaulting to the field. A strip over a numeric
field reads it through a linear, log or threshold scale the way an
encoding does, so a column of collection years takes a ramp and a gradient
legend.
The panels take their width out of the alignment’s, so the alignment scrolls and fits within what is left. A strip scrolls with the tree and the alignment, and a row the table gives no value leaves its cell empty.
Each header draws in the band the tree’s scale bar and the minimap share, turned
on its side, and it exports with the figure. The band is as tall as the minimap,
so a longer header is clipped to it and the full name is the column’s tooltip. A
panel with an axis, a bar, a point or a features panel under
x: "position", draws the axis at the foot of the band and writes its header
across above it.
A panel’s scale carries a legend of its own, titled by the field, and every
panel and encoding declaring the same members over one field lists it once.
Eight columns over one set of colors read eight fields, so give them one
legend.title. The strips then share one scale over every value the eight
fields take, a value two segments carry draws one color in both, and the figure
carries one key for the matrix:
"rowPanels": [
{
"kind": "strip",
"encoding": {
"fill": {
"field": "PB2",
"scale": { "scheme": "set1" },
"legend": { "title": "segment lineage" }
}
}
},
{
"kind": "strip",
"encoding": {
"fill": {
"field": "PB1",
"scale": { "scheme": "set1" },
"legend": { "title": "segment lineage" }
}
}
}
]
A features panel taking the overlay’s colors lists them under the same key the
overlay draws, and with no alignment behind it the panel’s own entries are that
key.
React: the rowPanels prop on MSAViewer, or model.setRowPanels(list). R:
geom_msa_strip("HA", range = "set1", width = 12, title = "amino acid") and
geom_msa_features(fill = "Name", label = "Name", align = "genE"). Python: the
row_panels trait.
The features panel
A features record draws the same spans the alignment’s overlay draws, in a
column of its own: an arrow where the GFF gives a gene a strand, a box
otherwise, labeled where the text fits. Features that overlap within a row stack
into lanes, which divide the row’s height between them.

trpB, with no alignment at all: a tree, a GFF
and one features panel under x: "position". The align transform starts
trpB at one x down the panel, and encoding.fill reads the GFF’s role
attribute while encoding.text reads Name.| Field | Meaning |
|---|---|
x |
column draws in the alignment’s columns; position in each row’s own residue positions |
encoding |
{fill: {field, scale, legend}, text: {field}} over fields of the features, or fill: {value} |
transform |
[{type: "align", on: <Name value>}], only under x: "position" |
position |
identity stacks overlapping features; strandpile splits the row by strand |
x: "position" maps every row’s features onto one linear scale across the
extent they cover, so a genome with no alignment has an x. With no msa the
alignment panel is zero columns wide, and the tree and the panel fill the view.
{type: "align", on: "genE"} shifts each row so that the first feature whose
Name is genE starts at zero, which is gggenes’ make_alignment_dummies. A
row carrying no such feature keeps its own origin. An align under
x: "column" draws nothing different, since the columns are the alignment’s.
Under x: "position" the header band draws the panel’s axis, with the header
above it as the axis title. The ticks count positions from 0 at the start of
each row’s sequence, and step in kb or Mb once the step reaches a thousand. With
an align transform, 0 is the start of the aligned feature: a tick at -2 kb
marks two kilobases before genE starts in every row that carries one, and in a
row with no genE it marks two kilobases before the row’s own start.
encoding.fill reads any field of the feature table, the same fields a
featureFill encoding reads, or holds one color as {"value": "#bbbbbb"}. A
record with no fill takes the colors the overlay gives the same features, and
encoding.text falls back to the featureLabel encoding the same way. A
feature’s own GFF color= wins over either.

position: "strandpile", which separates the divergently
transcribed neighbours that read as one more arrow in a row under identity.position: "strandpile" is gggenomes’ position_strandpile. Each strand packs
on its own, and the deepest row on each side sets the grid every row lays out
on, so the line between the strands sits at one height down the panel. A row
using only one side leaves the other empty, and a feature with no strand piles
with the forward ones.
{
"type": "MsaView",
"data": {
"tree": "((genome1:0.1,genome2:0.1):0.2,genome3:0.3);",
"gff": "##gff-version 3\ngenome1\tncbi\tgene\t1\t500\t.\t+\t.\tName=genD\ngenome1\tncbi\tgene\t600\t1000\t.\t+\t.\tName=genE\ngenome2\tncbi\tgene\t200\t700\t.\t+\t.\tName=genE\ngenome3\tncbi\tgene\t1\t400\t.\t-\t.\tName=genD"
},
"rowPanels": [
{
"kind": "features",
"x": "position",
"width": 320,
"header": "neighborhood",
"encoding": {
"fill": { "field": "Name", "scale": { "scheme": "set1" } },
"text": { "field": "Name" }
},
"transform": [{ "type": "align", "on": "genE" }]
}
]
}
Bar, point and text panels
A bar panel draws one bar per row from the panel’s left edge to the value of a
numeric rowData field, and a point panel draws a dot at that value. The
value runs along the panel’s width through encoding.x.scale, and the header
band draws that scale’s axis with the header above it as its title. A text
panel prints a rowData field in the panel’s width, cut in the middle where it
runs longer.
"rowPanels": [
{
"kind": "bar",
"header": "genome (bp)",
"encoding": {
"x": { "field": "genomeSize", "scale": { "domainMin": 0 } },
"color": { "field": "host", "scale": { "scheme": "dark2" } }
}
},
{ "kind": "point", "encoding": { "x": { "field": "year" } }, "size": 5 },
{ "kind": "text", "encoding": { "text": { "field": "clade" } } }
]
| Field | Meaning |
|---|---|
encoding.x |
a bar or point’s {field, scale}, the numeric field and its value scale |
encoding.x.scale |
{type, domainMin, domainMax, domainQuantile}, with type linear or log |
encoding.text |
a text panel’s {field} |
encoding.color |
a color object over the same field or another, coloring each bar, dot or text |
size |
a point’s diameter in pixels, 6 by default and at most the row height |
Each end of the value scale is domainMin or domainMax where set, and
otherwise follows the field’s values, clipped at domainQuantile as a color
ramp’s ends are. A linear bar scale with an end unset takes 0 into its domain,
so the bars start at 0. A log scale reads only the positive values and draws
its bars from its low end. A row whose field is missing or no number draws no
mark, and its tooltip reads (none).
The axis ticks step along 1, 2 and 5 times a power of ten, the ladder the tree’s
scale bar uses, and print a thousand or more as k, M or G. A log axis
ticks each power of ten. encoding.color resolves through the same declarations
as the strips and the encodings, so a bar colored by host and a strip over
host with one scale list one legend. Under scale: {type: "identity"} each
bar, dot or text takes the color its field names. A bar or point with no
encoding.color draws grey, and a text with none draws in the theme’s text
color.
model.scaleProblems lists a value scale’s contradictions under
rowPanels[i].encoding.x: a domainMax below its domainMin, a log scale’s
domainMin at or below 0, a domainQuantile outside 0.5 to 1, and a type
other than linear or log.
rowTransform
What the row axis does with the rowData fields: filter keeps the rows that
pass every test, sort orders them, and facet stacks them in bands, each
labelled with its field’s value. Every panel reads the one row order, so the
tree, the labels, the row panels and the alignment move together.
{
"type": "MsaView",
"data": {
"msa": ">duck\nMKAANSE\n>chicken\nMKA-NSE\n>goose\nMKAANSE\n>swan\nMKAGNSE",
"treeMetadata": "{\"duck\":{\"host\":\"wild\",\"year\":2021},\"chicken\":{\"host\":\"poultry\",\"year\":2015},\"goose\":{\"host\":\"poultry\",\"year\":2022},\"swan\":{\"host\":\"wild\",\"year\":2009}}"
},
"rowTransform": {
"filter": [{ "field": "year", "range": [2010, null] }],
"sort": [{ "field": "year", "order": "descending" }],
"facet": { "field": "host", "sort": ["wild"] }
}
}
Open this snapshot in the app.
| Field | Meaning |
|---|---|
filter |
[{field, oneOf: [values]}] or [{field, range: [min, max]}], every test passing |
sort |
[{field, order}], order being ascending (the default) or descending |
facet |
{field, sort}, where sort lists the values whose bands come first, in that order |
A oneOf test compares the value as a string, so 2015 matches "2015". A
range is inclusive, and null leaves an end open. A row with no value for the
field fails every test. A filter keeping no row is not applied, and the header
warns that it keeps none.
A sort compares values in the natural order a scale’s domain uses: numbers by
value, and digit runs by magnitude, so 2.3.2.1a sorts before 2.3.4.4b. Each
further key orders the rows the keys before it leave tied, and rows tied on
every key keep the file’s order. Rows with no value sort last in either order.
A facet stacks the bands the values sort lists first, then the other values in
natural order, and the rows with no value last, under no label. Each band keeps
the order the sort gives its rows. A band’s label draws in the gutter the
bracket clade mark uses, beside a bar over the band’s rows, and exports with
the figure the same way.
With a tree, the tree sets the row order:
filterprunes the tree to the tips it keeps, as “Show only this clade” narrows it. An internal node whose tips all fail drops with them. Thecladesmarks resolve against the whole tree, so a highlight keeps the rows of its clade that remain.sortis not applied, and the header warns that the tree sets the order. This holds withdrawTreeoff, since collapses, the focus and thecladesmarks all follow the tree.facetlabels each band whose rows are one clade of the pruned tree: the most recent common ancestor of the band’s tips has no other tips under it. A band that is not a clade draws no label, and the header warns, naming it. The rows stay in the tree’s order.
A link carries rowTransform as written: field names and values. Rerooting the
tree keeps it, and a new rowData table reapplies it.
React: the rowTransform prop on MSAViewer, or
model.setRowTransform(transform). Python: the row_transform trait, a dict of
the same shape.
residueMappings
A residue mapping records which residue of which structure each residue of a row
corresponds to. Unlike the layers above, residueMappings draws nothing; the
model reads it to answer lookups. The host has to supply it, because matching a
row to a structure by sequence equality fails for a construct with an expression
tag, a truncation, an engineered residue, or a row that is a subsequence of the
entry. The highlight then lands on a real residue, just the wrong one. A
producer such as SIFTS, an AlphaFold model or a curator computes the
correspondence.
"residueMappings": [
{
"row": "HBA_HUMAN/1-142",
"accession": "P69905",
"structure": {
"id": "1A3N",
"kind": "experimental",
"asymId": "A",
"url": "https://files.rcsb.org/download/1A3N.cif"
},
"segments": [
{ "rowStart": 1, "rowEnd": 141, "structStart": 2, "structEnd": 142 }
],
"unobserved": [[60, 62]],
"rowLength": 142,
"generated": { "by": "sifts", "date": "2026-09-10" }
}
]
| Field | Meaning |
|---|---|
row |
The alignment row this maps |
accession |
The sequence database entry the mapping went through, for provenance |
structure |
id, plus optional kind, asymId (the chain), asymIdKind and url |
segments |
Contiguous runs where the two sides line up 1:1 |
unobserved |
Structure positions declared but not resolved, as [start, end] |
rowLength |
Ungapped length of the row it was computed against; always set it |
generated |
Who computed it, when, and from what |
asymIdKind says which id asymId is, label for the file’s label_asym_id
or auth for the author’s auth_asym_id. With none set a reader tries the
label id and then the author id, which is wrong for an entry where the two
collide, such as 7K00’s author chain X, which is label AB. A mapping that
names no chain applies to every chain.
Positions are 1-based and inclusive on both sides, as everywhere else in this
document. Structure positions are label_seq_id, the index into the entity’s
SEQRES. Author numbering carries insertion codes, which break integer
arithmetic, so the layer does not use it.
A mapping is a few contiguous runs, and the segments define what is unmapped, so the layer needs no status field that could contradict them. A position is in one of three states:
- covered by a segment and not in
unobserved: mapped and observed - covered and listed in
unobserved: mapped, not observed - anything else: unmapped
The middle state separates “the crystallographer could not see this residue” from “this protein has no such residue”.
Two model methods read it:
model.structureResidue(rowName, seqPos, structureId?) // -> {structure, position, observed} | undefined
model.rowResidue(structureId, position, asymId?) // -> {rowName, seqPos} | undefined
Both return undefined when no mapping covers the position, and also when
more than one does. A row commonly maps onto several structures, such as an
experimental entry and a couple of predicted models, and a homodimer maps two
rows onto two chains of one id. Returning the first mapping found would place
the answer on a wrong residue with no error. Name one structure or chain with
the optional argument, or read mappedStructures to see what is available.
Staleness
A host can load a saved mapping against a re-aligned, revised or different sequence, and every lookup would then return a wrong residue with no error. Before answering, the viewer checks each mapping and stops using it when any of these holds:
- The row it names is not in the alignment.
rowLengthis declared and does not match the row’s ungapped length. No other check catches a same-length substitution, so a producer should always set it.- A segment covers residues past the end of the row, which shows the same
mismatch when
rowLengthis missing.
When a segment is malformed, its two sides differing in length so it cannot be a 1:1 run, the viewer drops only that segment and keeps using the rest of the mapping.
model.residueMappingProblems lists each mapping or segment the viewer dropped,
with a scope (mapping or segment) and a reason, so a host can tell “there
is no structure for this row” from “this data no longer matches what is loaded”.
model.usableResidueMappings holds the mappings that passed.
packages/examples/src/examples/kinaseStructure.json is a real mapping,
generated by scripts/examples-gen/contacts.mjs from SIFTS: the SRC_HUMAN row
against chain A of 2SRC, one segment putting row residue 86 at structure residue
2, one unobserved range, and rowLength: 536. The
spike_structure tutorial
builds another from scratch, against a construct whose numbering is offset by 19
and whose furin loop has no coordinates at all.
seqPos is 1-based, like the rest of this document, and composes directly with
applyHighlight. The column helpers on the model (seqPosToVisibleCol) take
0-based positions, so a structure hover reaches a column as
model.seqPosToVisibleCol(rowName, seqPos - 1).
Generating a mapping
react-msaview-cli residue-mappings writes this layer from SIFTS for a PDB
chain, or from AlphaFold DB for a predicted model. It checks each row against
its UniProt sequence first, maps a /start-end row as that fragment, and sets
rowLength, unobserved and generated. The
CLI page lists its options.
react-msaview-cli residue-mappings --msa spike.afa --row SARS-CoV-2 \
--accession P0DTC2 --pdb 6VXX --chain A -o mappings.json