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]
    }
  ]
}

Open this view in the app.

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.

Preproinsulin across nine vertebrates, with all three kinds over the Human row: Kyte-Doolittle hydropathy as bars, the chain each residue belongs to as characters, and the three disulfide bonds of UniProt P01308 as arcs. B7-A7 and B19-A20 reach across the C peptide that processing cuts out.
{
  "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.

p53 across fifteen vertebrates, read as a diff against Human. The two wide bands are UniProt domains given as residue ranges of the Human row, the six narrow ones are the IARC hotspot residues, and the blue wash is a 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:

  • highlight fills 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’s geom_hilight.
  • bracket draws a vertical bar beside the clade’s rows carrying the record’s label, which is ggtree’s geom_cladelab and, over a range, geom_strip.
  • collapse collapses the clade at load, the way the branch menu’s “Collapse clade” does.
  • focus opens the viewer on the clade alone, the way “Show only this clade” does.
  • rotate swaps the order of the clade’s children at load, the way “Rotate clade” does, which is ggtree’s rotate. The rows follow the tips.
46 TEM beta-lactamase alleles. The seven-tip clade at the top carries a 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.
  • input keeps the order the tree file gives.
  • ladderize puts the child with fewer tips first, so the deep clades step down toward the bottom, which is ape’s ladderize as plot.phylo draws it.
  • ladderizeReverse puts 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.

The same 46 alleles with three channels over the row table: 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 rowData value 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 its encoding.color reads 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; a rowTransform filter drops rows.
  • A hidden feature value takes the features carrying it out of the overlay, the features panels and the features tracks, and out of their tooltips.
  • A hidden support value 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.

Ten Src-family kinases with their InterPro Pfam matches, both feature channels reading the GFF’s 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}:

  • channel is what the color paints: fill (the default) colors the cell, and color colors the letter and leaves the cell plain.
  • field is what a cell reads: feature (the default) takes the color the annotation overlay gives the span covering the cell, and residue takes the residue’s color through scale. The color channel reads the residue.
  • scale holds scheme, a built-in scheme name (maeditor where unset), or domain and range, a color per residue letter. A domain wins over scheme.
{
  "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.

Nine strips between the tree and the alignment: the phenotype of each allele, then the residue it carries at each of eight Ambler positions. The eight position strips share one 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.

Twelve bacterial genomes around 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.

The same panel under 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:

  • filter prunes the tree to the tips it keeps, as “Show only this clade” narrows it. An internal node whose tips all fail drops with them. The clades marks resolve against the whole tree, so a highlight keeps the rows of its clade that remain.
  • sort is not applied, and the header warns that the tree sets the order. This holds with drawTree off, since collapses, the focus and the clades marks all follow the tree.
  • facet labels 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.
  • rowLength is 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 rowLength is 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