MsaView.md

Note: this document is automatically generated from @jbrowse/mobx-state-tree objects in our source code.

Links

• Source code
• Embedding guide — how to use this model in React, HTML, and R
• User guide — a tour of the viewer

Example usage

import { MSAModelF } from 'react-msaview'
import { types } from '@jbrowse/mobx-state-tree'

const RootModel = types.model({ view: types.optional(MSAModelF(), {}) })
const root = RootModel.create({})
root.view.setData({ msa: '>seq1\nACGT\n>seq2\nACGT' })

Overview

The main MSAView state model. Holds the loaded alignment, tree, and optional overlay annotations, plus all display state (color scheme, zoom, scroll, collapsed clades). It composes in members from DialogQueueSessionMixin, Tree, and MSAModel (see Inherited members below). Data is loaded reactively from the msaFilehandle / treeFilehandle / gffFilehandle properties, or set directly with setData. Most state is persisted into the shareable URL.

Inherited members

Available on this model via composition. Follow each link for full signatures and docs.

Available via DialogQueueSessionMixin

Getters: DialogComponent, DialogProps

Actions: removeActiveDialog, queueDialog

Available via Tree

Properties: drawLabels, labelsAlignRight, treeAreaWidth, treeWidth, showBranchLen, drawTree, drawNodeBubbles, autoTreeAreaWidth

Actions: setTreeAreaWidth, setTreeWidth, setLabelsAlignRight, setDrawTree, setAutoTreeAreaWidth, setShowBranchLen, setDrawNodeBubbles, setDrawLabels

Available via MSAModel

Properties: bgColor, colorSchemeName, showColumnStats, msaFormat

Actions: setColorSchemeName, setBgColor, setShowColumnStats, setMSAFormat

MsaView - Properties

property: allowedGappyness

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
allowedGappyness: stripDefault(types.number, defaultAllowedGappyness)

property: collapsed

array of tree parent nodes that are 'collapsed' (all children are hidden)

// type signature
IOptionalIType<IArrayType<ISimpleType<string>>, [undefined]>
// code
collapsed: stripDefault(types.array(types.string), [])

property: columnTracks

tracks supplied as data: per-column values drawn as bars, or a per-column string drawn as a text track. See docs/layers.md

// type signature
IOptionalIType<IArrayType<IType<ColumnTrackSpec, ColumnTrackSpec, ColumnTrackSpec>>, [undefined]>
// code
columnTracks: stripDefault(
          types.array(types.frozen<ColumnTrackSpec>()),
          [],
        )

property: colWidth

width of columns, px

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
colWidth: stripDefault(types.number, defaultColWidth)

property: currentAlignment

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
currentAlignment: stripDefault(types.number, defaultCurrentAlignment)

property: data

data from the loaded tree/msa/treeMetadata, generally loaded by autorun

// type signature
IOptionalIType<IModelType<{ tree: IMaybe<ISimpleType<string>>; msa: IMaybe<ISimpleType<string>>; treeMetadata: IMaybe<ISimpleType<string>>; gff: IMaybe<...>; }, { ...; }, _NotCustomized, { ...; }>, [...]>
// code
data: types.optional(DataModelF(), {
          tree: '',
          msa: '',
          treeMetadata: '',
        })

property: drawMsaLetters

// type signature
IOptionalIType<ISimpleType<boolean>, [undefined]>
// code
drawMsaLetters: stripDefault(types.boolean, defaultDrawMsaLetters)

property: gffFilehandle

filehandle object for a GFF file of overlay annotations

// type signature
IMaybe<any>
// code
gffFilehandle: types.maybe(FileLocation)

property: height

height of the div containing the view, px

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
height: stripDefault(types.number, defaultHeight)

property: hideGaps

// type signature
IOptionalIType<ISimpleType<boolean>, [undefined]>
// code
hideGaps: stripDefault(types.boolean, defaultHideGaps)

property: highlightColumns

declarative seed for the highlighted-columns overlay (visible column indices). Unlike the volatile highlightedColumns (driven by transient genome-hover sync), this persists in the snapshot/URL so a shared link can open with specific columns highlighted. Applied once in afterCreate.

// type signature
IType<number[], number[], number[]>
// code
highlightColumns: types.frozen<number[] | undefined>()

property: highlights

labeled highlights in 1-based inclusive coordinates: a column span {start, end}, a residue span {row, start, end} of a named row, or a row set {rows}, each with an optional label and color. Persists in the snapshot and the URL.

// type signature
IOptionalIType<IArrayType<IType<Highlight, Highlight, Highlight>>, [undefined]>
// code
highlights: stripDefault(types.array(types.frozen<Highlight>()), [])

property: id

id of view, randomly generated if not provided

// type signature
any
// code
id: ElementId

property: msaFilehandle

filehandle object for the MSA (which could contain a tree e.g. with stockholm files)

// type signature
IMaybe<any>
// code
msaFilehandle: types.maybe(FileLocation)

property: relativeTo

// type signature
IMaybe<ISimpleType<string>>
// code
relativeTo: types.maybe(types.string)

property: residueMappings

row-to-structure residue correspondence, computed outside the viewer (e.g. from SIFTS). Matching by sequence equality places a tagged construct, a truncation or a subsequence row on the wrong residue. See docs/layers.md

// type signature
IOptionalIType<IArrayType<IType<ResidueMapping, ResidueMapping, ResidueMapping>>, [undefined]>
// code
residueMappings: stripDefault(
          types.array(types.frozen<ResidueMapping>()),
          [],
        )

property: rowHeight

height of each row, px

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
rowHeight: stripDefault(types.number, defaultRowHeight)

property: scrollX

scroll position, X-offset, px

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
scrollX: stripDefault(types.number, defaultScrollX)

property: scrollY

scroll position, Y-offset, px

// type signature
IOptionalIType<ISimpleType<number>, [undefined]>
// code
scrollY: stripDefault(types.number, defaultScrollY)

property: scrollZoom

zoom in/out on plain mouse-wheel without holding ctrl

// type signature
IOptionalIType<ISimpleType<boolean>, [undefined]>
// code
scrollZoom: stripDefault(types.boolean, defaultScrollZoom)

property: scrollZoomAxis

which cell dimensions a wheel zoom scales, while scrollZoom is on

// type signature
IOptionalIType<ISimpleType<"both" | "horizontal" | "vertical">, [undefined]>
// code
scrollZoomAxis: stripDefault(
          types.enumeration('ScrollZoomAxis', [...scrollZoomAxes]),
          defaultScrollZoomAxis,
        )

property: showDomainLegend

whether the domain legend is expanded. The legend floats over the top-right of the alignment and covers residues, so a session or figure can open with it collapsed.

// type signature
IOptionalIType<ISimpleType<boolean>, [undefined]>
// code
showDomainLegend: stripDefault(types.boolean, defaultShowDomainLegend)

property: showDomains

// type signature
IOptionalIType<ISimpleType<boolean>, [undefined]>
// code
showDomains: stripDefault(types.boolean, defaultShowDomains)

property: showOnly

focus on particular subtree

// type signature
IMaybe<ISimpleType<string>>
// code
showOnly: types.maybe(types.string)

property: subFeatureRows

// type signature
IOptionalIType<ISimpleType<boolean>, [undefined]>
// code
subFeatureRows: stripDefault(types.boolean, defaultSubFeatureRows)

property: trackHeights

the height of every track one divider resizes, keyed by heightKey: the kind for the computed tracks, own:<id> for a data track. A key is absent until the user drags that divider, and defaultTrackHeights answers for it until then, so an untouched viewer adds nothing to the shared URL.

// type signature
IOptionalIType<IMapType<ISimpleType<number>>, [undefined]>
// code
trackHeights: stripDefault(types.map(types.number), {})

property: treeFilehandle

filehandle object for the tree

// type signature
IMaybe<any>
// code
treeFilehandle: types.maybe(FileLocation)

property: treeMetadataFilehandle

filehandle object for tree metadata

// type signature
IMaybe<any>
// code
treeMetadataFilehandle: types.maybe(FileLocation)

property: turnedOffFeatures

the user's explicit hide choices per annotation accession, keyed by accession with the value meaning "off", like turnedOffTracks. An untouched accession is absent and drawn, so the shared URL grows only with the user's filters

// type signature
IOptionalIType<IMapType<ISimpleType<boolean>>, [undefined]>
// code
turnedOffFeatures: stripDefault(types.map(types.boolean), {})

property: turnedOffTracks

the user's explicit show/hide choice per track id, keyed by id with the value meaning "off". A track the user has never touched is absent and falls back to its own default (see defaultOffTracks), so a hidden-by-default track adds nothing to the shared URL.

// type signature
IOptionalIType<IMapType<ISimpleType<boolean>>, [undefined]>
// code
turnedOffTracks: stripDefault(types.map(types.boolean), {})

property: type

hardcoded view type

// type signature
ILiteralType<"MsaView">
// code
type: types.literal('MsaView')

MsaView - Volatiles

volatile: annotations

overlay annotations drawn on the alignment. InterProScan JSON, GFF and user uploads all convert to this flat list

// type signature
Annotation[]
// code
annotations: [] as Annotation[]

volatile: blockSize

size of blocks of content to be drawn, px

// type signature
number
// code
blockSize: 500

volatile: error

// type signature
unknown
// code
error: undefined as unknown

volatile: headerHeight

// type signature
number
// code
headerHeight: 0

volatile: hideHeader

leaves the toolbar out, for a host drawing its own controls. Kept out of the snapshot so a link opened in the full app shows the toolbar.

// type signature
false
// code
hideHeader: false

volatile: highlightedColumns

array of column indices to highlight

// type signature
number[]
// code
highlightedColumns: undefined as number[] | undefined

volatile: highResScaleFactor

canvas scale factor, from the device pixel ratio

// type signature
number
// code
highResScaleFactor: typeof window === 'undefined' ? 1 : window.devicePixelRatio

volatile: hostCarriesData

set by a host that restores the loaded documents itself, such as a jbrowse session or a page that refetches them. unshareableData then reports nothing

// type signature
false
// code
hostCarriesData: false

volatile: hoveredTreeNode

the currently hovered tree node ID and its descendant leaf names

// type signature
{ nodeId: string; descendantNames: string[]; }
// code
hoveredTreeNode: undefined as
        | { nodeId: string; descendantNames: string[] }
        | undefined

volatile: loadingMSA

// type signature
false
// code
loadingMSA: false

volatile: loadingTree

// type signature
false
// code
loadingTree: false

volatile: marginLeft

// type signature
number
// code
marginLeft: 20

volatile: minimapHeight

// type signature
number
// code
minimapHeight: 56

volatile: mouseClickCol

the currently mouse-click column

// type signature
number
// code
mouseClickCol: undefined as number | undefined

volatile: mouseClickRow

the currently mouse-click row

// type signature
number
// code
mouseClickRow: undefined as number | undefined

volatile: mouseCol

the currently mouse-hovered column

// type signature
number
// code
mouseCol: undefined as number | undefined

volatile: mouseRow

the currently mouse-hovered row

// type signature
number
// code
mouseRow: undefined as number | undefined

volatile: resetCount

bumped by reset(). The error boundary above the view uses it as its key, since the boundary keeps its caught error until remounted

// type signature
number
// code
resetCount: 0

volatile: resizeHandleWidth

resize handle width between tree and msa area, px

// type signature
number
// code
resizeHandleWidth: 5

volatile: status

// type signature
{ msg: string; onCancel?: () => void; }
// code
status: undefined as { msg: string; onCancel?: () => void } | undefined

volatile: transientHighlights

transient highlights keyed by owner, so a structure viewer's hover and a genome view's hover each clear only their own. Not persisted.

// type signature
Record<string, Highlight[]>
// code
transientHighlights: {} as Record<string, Highlight[]>

volatile: volatileWidth

// type signature
number
// code
volatileWidth: undefined as number | undefined

volatile: warnings

non-fatal load problems: an optional layer that failed to load, an overlay that failed to parse. error replaces the view and is for the alignment itself

// type signature
string[]
// code
warnings: [] as string[]

MsaView - Getters

getter: actuallyShowDomains

// type
boolean

getter: adapterTrackModels

// type
BasicTrack[]

getter: alignmentNames

// type
any

getter: allBranchesLength0

// type
boolean

getter: alphabetMaxBits

The information content of a fully conserved column, in bits, which depends on the alphabet. Both the entropy ceiling conservation normalizes against and the y-axis ceiling of the sequence logo track.

// type
number

getter: basePairTrackModels

the consensus secondary structure as a track, when there is one. A separate getter keeps the object stable across zoom, so its canvas does not redraw

// type
BasicTrack[]

getter: blanks

// type
any[]

getter: blocks2d

// type
(readonly [any, any])[]

getter: blocksX

// type
any[]

getter: blocksY

// type
any[]

getter: categoricalDomainTypes

categorical feature types (InterPro domains and the like) that each get their own color and a legend entry

// type
any[]

getter: clickedCell

the cell a click pinned. Public API: MSAViewer's onCellClick reports it.

// type
any

getter: colClustalX

Pre-computed ClustalX colors per column. Returns a map of letter -> color for each column. ref http://www.jalview.org/help/html/colourSchemes/clustal.html

// type
;(Record < string, string > [])

getter: colConsensus

Pre-computed consensus letter and percent identity color per column. Used by percent_identity_dynamic color scheme.

// type
{
  letter: string
  color: string
}
;[]

getter: colorScheme

// type
Record<string, string>

getter: colStats

// type
ColumnCounts

getter: columns

// type
Map<unknown, unknown>

getter: columns2d

// type
any

getter: columnTrackContent

a data track's values or string, projected from its row's residues onto alignment columns when it names a row

// type
Map<string, { values?: number[]; data?: string; arcs?: Arc[]; }>

getter: columnTrackModels

// type
BasicTrack[]

getter: computedTrackModels

the tracks computed from the alignment; they depend on their heights and the alphabet, not on zoom

// type
BasicTrack[]

getter: conservation

Conservation score per column using Shannon entropy (biojs-msa style). Conservation = (1 - H/Hmax) * (1 - gapFraction) Returns values 0-1 where 1 = fully conserved, 0 = no conservation.

// type
number[]

getter: dataInitialized

// type
boolean

getter: domainBands

every filtered-on annotation resolved to the visible column span it is drawn across, keyed by row name. Each row is ordered longest-first so a nested short domain draws on top, and each band carries the lane the sub-row layout puts it in. Resolved once here instead of per canvas block per redraw; the letter renderer also reads the band colors to pick legible letter colors.

// type
Map<string, DomainBand[]>

getter: domainBandsByStart

the same bands ordered by start column, for left-to-right sweeps (the letter renderer walks columns and needs the band covering each one)

// type
Map<any, any>

getter: domainUnderline

whether the overlay marks each domain with a bar under its row instead of filling the row behind the letters. Letter-color mode hands the background to the color scheme, so a filled box would paint over it and leave the setting with nothing to show. Sub-row layout already stacks the boxes clear of the letters, and with the letters too small to draw the filled box is the only thing left to read.

// type
boolean

getter: fontSize

// type
number

getter: header

// type
any

getter: hideGapsEffective

hideGaps takes effect when there are collapsed rows or allowedGappyness < 100

// type
boolean

getter: hierarchy

generates a new tree that is clustered with x,y positions

// type
HierarchyNode<NodeWithIdsAndLength>

getter: highlightedColumnRuns

contiguous runs of highlightedColumns, so a run of highlighted columns draws as one bordered band. Memoized because the overlay canvas redraws on every mouse move.

// type
{
  start: number
  end: number
}
;[]

getter: hostRestoresData

whether the host restores the loaded documents outside the snapshot. When true, unshareableData is empty.

A simple host sets hostCarriesData. A host where this depends on how the view was opened overrides the getter in its own composed model's .views block; jbrowse-plugin-msaview's indexed-location views refetch from a URL the session holds, while its data-store views do not. unshareableData reads it off self, so an override takes effect.

// type
boolean

getter: hoveredCell

the cell under the pointer. Public API: MSAViewer's onCellHover reports it.

// type
any

getter: hoveredInsertion

Returns insertion info if mouse is hovering over an insertion indicator

// type
{
  rowName: any
  col: number
  letters: any
}

getter: hoveredRowIndices

row indices highlighted by the current tree hover (a hovered internal node highlights every tip below it). Shared by the tree and MSA overlay canvases, via the memoized name->index map.

// type
unknown[]

getter: insertionPositions

Returns a map of row name to array of insertions with display position and letters

// type
Map<string, { pos: number; letters: string; }[]>

getter: isLoading

// type
boolean

getter: labelWidthMap

// type
Map<any, number>

getter: labelWidthScale

factor turning a labelWidthMap entry into its width at the current font size

// type
number

getter: leaves

// type
any[]

getter: mappedStructures

the structures with usable mappings. A row can map onto several, such as an experimental entry and a predicted model.

// type
any

getter: maxBranchLength

x-position of the farthest tip in a phylogram, px: treeWidth, or 0 for a tree with no branch lengths (drawn as a cladogram)

// type
number

getter: maxDepthToLeaf

max topological depth to a tip, used to scale cladogram x-positions

// type
number

getter: maxScrollX

// type
number

getter: maxScrollY

most-negative allowed scrollY, which keeps the last row in view

// type
number

getter: mouseOverColumnStats

columnStatsAt for the hovered column, undefined when nothing is hovered

// type
ColumnStats

getter: mouseOverDomains

domain annotations under the mouse, hit-tested against the exact visible column span each box is drawn at (so it matches the overlay across gaps)

// type
Annotation[]

getter: mouseOverRowName

// type
any

getter: MSA

// type
MSAParserType

getter: msaAreaHeight

the vertical space for alignment rows: the widget height less the header, the tracks, and the minimap when columns overflow. Shared by blocksY, maxScrollY, the vertical scrollbar and fitVertically.

// type
number

getter: msaAreaWidth

widget width minus the tree area gives the space for the MSA

// type
number

getter: msaCanvasWidth

width of the alignment canvas: the msa area less the vertical scrollbar. showHorizontalScrollbar must not read it, since that feeds msaAreaHeight -> showVerticalScrollbar and would form a cycle

// type
number

getter: noTree

// type
boolean

getter: numColumns

// type
number

getter: numRows

number of rows on screen: the leaf count, which includes tree leaves with no matching MSA row (drawn blank), unlike rows.length.

// type
any

getter: propertyConservation

Per-column conservation of physicochemical property class (amino acids only). Surfaces conservative-substitution sites that identity-based conservation misses. Empty for nucleotide alignments.

// type
number[]

getter: pxPerBranchLength

pixels per unit of branch length in the phylogram layout, 0 in cladogram mode. The tree's scale bar uses it.

// type
number

getter: realAllowedGappyness

// type
number

getter: referenceRowIndex

row index of the reference row (relativeTo), undefined when unset

// type
unknown

getter: residueMappingProblems

why each ignored residue mapping is ignored, so a host can tell a missing structure from a mapping made against a different alignment.

// type
ResidueMappingProblem[]

getter: resolvedHighlights

highlights projected onto what is on screen: residue spans go through the named row's gap structure, column spans through the hidden-column list, and a span that lands entirely on hidden columns is dropped. Row names that match no row are ignored.

// type
ResolvedHighlight[]

getter: root

// type
HierarchyNode<any>

getter: rootToTipLength

branch-length extent of the displayed tree, root to farthest tip, in the tree's own units

// type
number

getter: rowMap

every sequence in the alignment, keyed by row name, including rows a collapsed clade hides. rows holds only the rows on screen; lookups by row name use this

// type
Map<unknown, unknown>

getter: rowNames

Returns the list of row (sequence) names in display order. Part of the public API used by downstream consumers (e.g. jbrowse plugins).

// type
string[]

getter: rowNamesSet

// type
Map<unknown, unknown>

getter: rows

// type
any

getter: secondaryStructureArcs

the base pairs of the consensus secondary structure, as arcs, in visible column space (hidden columns are removed before parsing)

// type
Arc[]

getter: secondaryStructureConsensus

// type
string

getter: segmentDomainTypes

ordinal segment types (exons etc.), ordered by sequence position so exon-1..exon-14 run left-to-right; colored by alternating shade and labeled by number, with no legend row

// type
any

getter: segmentLabels

accession -> number drawn on each segment band: the trailing number of the feature name ("exon-3" -> "3"), else its 1-based position

// type
Map<unknown, unknown>

getter: seqConsensus

// type
string

getter: sequenceType

Detects sequence type based on letters present in the alignment. Returns 'dna', 'rna', or 'amino'.

// type
;'dna' | 'rna' | 'amino'

getter: showBranchLenEffective

effective showBranchLen accounting for allBranchesLength0

// type
boolean

getter: showHorizontalScrollbar

// type
boolean

getter: showMsaLetters

// type
boolean

getter: showTreeText

// type
boolean

getter: showVerticalScrollbar

// type
boolean

getter: totalHeight

// type
number

getter: totalTrackAreaHeight

total height of track area (px)

// type
any

getter: totalWidth

// type
number

getter: tree

// type
NodeWithIds

getter: treeAreaWidthMinusMargin

// type
number

getter: treeMetadata

extra per-row attributes, keyed by row name. labelWidthMap reads this on every layout, so a malformed user-supplied file returns {} instead of throwing out of rendering.

// type
Record<string, Record<string, string>>

getter: turnedOnTracks

// type
any

getter: unshareableData

loaded documents left out of the snapshot, largest first. A file opened from disk or pasted in becomes inline text, and DataModel drops an inline document past maxInlineSnapshotBytes.

The header lists these, and the standalone app stops rewriting the address bar while the list is non-empty, so a copied link does not open an empty viewer unannounced. A document fetched from a URL never appears here, since the snapshot keeps its filehandle.

Empty when hostRestoresData is true.

// type
UnshareableData[]

getter: usableResidueMappings

the mappings that fit the loaded alignment. A row-level problem drops the whole mapping; a malformed segment drops only that segment.

// type
ResidueMapping[]

getter: verticalScrollbarWidth

// type
0 | 20

getter: viewport

the columns on screen. Public API: MSAViewer's onViewportChange reports it.

// type
Viewport

getter: visibleDomainTypes

the domain types currently drawn on the alignment (filtered-on), shared by the on-screen legend and the SVG export legend: the categorical types ordered by sequence position. Ordinal segments (exons) are numbered on the band instead

// type
any

getter: wheelZoomAxis

axis a wheel zoom scales, for ctrl+wheel as much as for scroll-zoom. With scroll-zoom off the toolbar shows no axis, so ctrl+wheel takes both.

// type
;'both' | 'horizontal' | 'vertical'

getter: width

// type
number

MsaView - Methods

method: cellAt

the cell at a visible column and row index, in the coordinates a host writes highlights in

// type signature
cellAt: (visibleCol: number, rowIndex?: number) => Cell

method: columnStatsAt

per-column summary statistics: consensus residue and its identity fraction, both conservation scores, gap fraction, and the sorted non-gap residue distribution. undefined past the end of the alignment or for an all-gap column.

// type signature
columnStatsAt: (col: number) => ColumnStats

method: getRowData

// type signature
getRowData: (name: string) => { data: { name?: string; accession?: string; dbxref?: string; }; treeMetadata: Record<string, string>; }

method: globalColToVisibleCol

Convert a global column index to a visible column index. Returns undefined if the column is hidden (in blanks). This is the inverse of visibleColToGlobalCol.

// type signature
globalColToVisibleCol: (globalCol: number) => number

method: rowResidue

The row residue for a structure residue; the inverse of structureResidue, returning undefined in the same cases. asymId picks a chain when several mappings share an entry id, as in a homodimer.

// type signature
rowResidue: (structureId: string, position: number, asymId?: string) => RowResidue

method: seqPosIndex

index of the global column holding each ungapped sequence position of a row. The domain overlay resolves thousands of these per redraw. Built lazily per row and cached on the parse.

// type signature
seqPosIndex: (rowName: string) => Int32Array<ArrayBufferLike>

method: seqPosToGlobalCol

Convert a sequence position (ungapped) to a global column index. Returns undefined for a row name the alignment does not have.

// type signature
seqPosToGlobalCol: (rowName: string, seqPos: number) => any

method: seqPosToVisibleCol

Convert a sequence position (ungapped) directly to a visible column index. This combines seqPosToGlobalCol and globalColToVisibleCol.

// type signature
seqPosToVisibleCol: (rowName: string, seqPos: number) => any

method: structureResidue

The structure residue for a row residue. Returns undefined when no segment covers seqPos, or when the row maps onto several structures and structureId does not pick one (see mappedStructures).

Positions are 1-based, like residueMappings and highlights; the column helpers above are 0-based.

// type signature
structureResidue: (rowName: string, seqPos: number, structureId?: string) => StructureResidue

method: trackHeight

the height a track draws at: what the user dragged its divider to, then the height its snapshot asked for, then its kind's default. Only a text track falls through to rowHeight, and ?? short-circuits before reading it, so vertical zoom does not rebuild the other tracks

// type signature
trackHeight: (kind: TrackKind, heightKey?: string, given?: number) => number

method: visibleColToGlobalCol

Convert a visible column index (what a mouse handler reports) to a column of the full alignment. A host indexing its own per-column data needs this when columns are hidden.

// type signature
visibleColToGlobalCol: (visibleCol: number) => number

method: visibleColToRowLetter

Return a row-specific letter at a visible column, or undefined if gap.

// type signature
visibleColToRowLetter: (rowName: string, visibleCol: number) => any

method: visibleColToSeqPos

Convert a visible column to a row-specific sequence position (0-based). Returns undefined if the position is a gap in the sequence.

Public API, like the sibling converters (visibleColToGlobalCol, seqPosToVisibleCol, globalColToVisibleCol, seqPosToGlobalCol) hosts use to translate between columns and residue positions. Keep them stable.

// type signature
visibleColToSeqPos: (rowName: string, visibleCol: number) => number

method: visibleColToSeqPosOneBased

Convert a visible column to a row-specific sequence position (1-based). Returns undefined if the position is a gap in the sequence.

// type signature
visibleColToSeqPosOneBased: (rowName: string, visibleCol: number) => any

method: visibleSpan

the visible columns a span covers, in highlight coordinates: start and end are 1-based residues of row, or columns of the file without it. A fractional position, as a zoom gesture reports one, widens to the whole residue or column it falls in. A span entirely on hidden columns, or naming a row the alignment lacks, gives undefined.

// type signature
visibleSpan: ({ row, start: rawStart, end: rawEnd }: Region) => { startCol: any; endCol: any; }

MsaView - Actions

action: addWarning

record a non-fatal load problem: a layer that failed to load, a file that failed to parse

// type signature
addWarning: (warning: string) => void

action: applyHighlight

show highlights for owner, replacing that owner's previous ones and leaving other owners' in place

// type signature
applyHighlight: (owner: string, highlights: Highlight[]) => void

action: calculateNeighborJoiningTreeFromMSA

Calculate a neighbor joining tree from the current MSA using BLOSUM62 distances. Throws above maxNeighborJoiningRows: the join loop is cubic and runs on the main thread, and 800 rows freeze the tab for ten seconds with no cancel.

// type signature
calculateNeighborJoiningTreeFromMSA: () => void

action: clearHighlight

remove owner's highlights, leaving other owners' in place

// type signature
clearHighlight: (owner: string) => void

action: clearWarnings

// type signature
clearWarnings: () => void

action: doScrollX

// type signature
doScrollX: (deltaX: number) => void

action: doScrollY

// type signature
doScrollY: (deltaY: number) => void

action: drawRelativeTo

draw the alignment with positions numbered relative to the given row's sequence (its node id), instead of in raw MSA-column coordinates

// type signature
drawRelativeTo: (id: string) => void

action: exportSVG

// type signature
exportSVG: (opts: ExportSvgOptions) => Promise<void>

action: fit

// type signature
fit: () => void

action: fitHorizontally

// type signature
fitHorizontally: () => void

action: fitVertically

// type signature
fitVertically: () => void

action: replaceTree

swap in a different tree over the same alignment. Clears collapsed and showOnly, since path-derived node ids (node-0-0-1) from the old tree would match unrelated nodes in the new one.

// type signature
replaceTree: (newick: string) => void

action: reset

Return to the import form: reset every property not in preservedOnReset to its default, then clear the file-derived volatiles applySnapshot does not touch.

// type signature
reset: () => void

action: resetZoom

restore the default column width and row height

// type signature
resetZoom: () => void

action: setAllowedGappyness

// type signature
setAllowedGappyness: (arg: number) => void

action: setAnnotations

Set the overlay annotations (an empty list clears them). InterProScan, GFF, user uploads and NCBI CDD all arrive here as Annotation[].

Leaves showDomains alone, because a restored snapshot reloads its GFF and must keep a hidden overlay hidden.

// type signature
setAnnotations: (annotations: Annotation[]) => void

action: setColumnTracks

// type signature
setColumnTracks: (tracks: ColumnTrackSpec[]) => void

action: setColWidth

set col width (px)

// type signature
setColWidth: (n: number) => void

action: setCurrentAlignment

switch to another alignment of a multi-alignment file (Stockholm). Clears the collapsed node ids, the subtree in focus, the reference row and the scroll position, which all refer to the previous alignment

// type signature
setCurrentAlignment: (n: number) => void

action: setData

set the alignment/tree/metadata/domain data directly from strings, bypassing the filehandle loaders

// type signature
setData: (data: { msa?: string; tree?: string; treeMetadata?: string; gff?: string; }) => void

action: setDomains

set the overlay from raw InterProScan results keyed by row name. Kept for downstream plugins that hold the EBI wire format; new code should adapt to Annotation[] and call setAnnotations.

// type signature
setDomains: (data?: Record<string, InterProScanResults>) => void

action: setDrawMsaLetters

// type signature
setDrawMsaLetters: (arg: boolean) => void

action: setError

set error state

// type signature
setError: (error?: unknown) => void

action: setFilter

show or hide an annotation type. Only hidden types are recorded; see turnedOffFeatures

// type signature
setFilter: (accession: string, shown: boolean) => void

action: setGFF

store the GFF text in the snapshot like the alignment and tree. The parsed annotations are volatile and a blob filehandle is cleared once read, so the text is the only persisted copy. An autorun parses it into annotations.

// type signature
setGFF: (result: string) => void

action: setGFFFilehandle

// type signature
setGFFFilehandle: (gffFilehandle?: FileLocationType) => void

action: setHeaderHeight

// type signature
setHeaderHeight: (arg: number) => void

action: setHeight

set the height of the view in px

// type signature
setHeight: (height: number) => void

action: setHideGaps

hide columns that are entirely (or mostly, see allowedGappyness) gaps

// type signature
setHideGaps: (arg: boolean) => void

action: setHideHeader

// type signature
setHideHeader: (arg: boolean) => void

action: setHighlightedColumns

set highlighted columns

Public API: jbrowse-plugin-msaview calls this from its afterCreateAutoruns, and MSAViewer passes its highlightColumns prop through it.

// type signature
setHighlightedColumns: (columns?: number[]) => void

action: setHighlights

// type signature
setHighlights: (highlights: Highlight[]) => void

action: setHighResScaleFactor

update the canvas scale factor when the device pixel ratio changes (moving between monitors, browser zoom)

// type signature
setHighResScaleFactor: (arg: number) => void

action: setHostCarriesData

declare that this host restores the loaded documents itself, which hides the "Not in the link" warning. See hostCarriesData

// type signature
setHostCarriesData: (arg: boolean) => void

action: setHoveredTreeNode

set hovered tree node and its descendants

// type signature
setHoveredTreeNode: (nodeId?: string) => void

action: setLoadingMSA

// type signature
setLoadingMSA: (arg: boolean) => void

action: setLoadingTree

// type signature
setLoadingTree: (arg: boolean) => void

action: setMouseClickPos

set mouse click position (row, column) in the MSA

// type signature
setMouseClickPos: (col?: number, row?: number) => void

action: setMousePos

set mouse position (row, column) in the MSA

Public API: a host calls this (and reads mouseCol) to sync hover with its own view, such as a genome view or 3D structure. Keep the name and signature stable.

// type signature
setMousePos: (col?: number, row?: number) => void

action: setMSA

// type signature
setMSA: (result: string) => void

action: setMSAFilehandle

// type signature
setMSAFilehandle: (msaFilehandle?: FileLocationType) => void

action: setResidueMappings

replace the alignment<->structure correspondence (see docs/layers.md)

// type signature
setResidueMappings: (mappings: ResidueMapping[]) => void

action: setRowHeight

set row height (px)

// type signature
setRowHeight: (n: number) => void

action: setScrollX

// type signature
setScrollX: (n: number) => void

action: setScrollY

set scroll Y-offset (px), clamped to keep the alignment in view

// type signature
setScrollY: (n: number) => void

action: setScrollZoom

// type signature
setScrollZoom: (arg: boolean) => void

action: setScrollZoomAxis

// type signature
setScrollZoomAxis: (arg: "both" | "horizontal" | "vertical") => void

action: setShowDomainLegend

expand or collapse the domain legend that floats over the alignment

// type signature
setShowDomainLegend: (arg: boolean) => void

action: setShowDomains

toggle the annotation overlay on the alignment

// type signature
setShowDomains: (arg: boolean) => void

action: setShowOnly

show only the subtree rooted at the given node id (pass undefined to show the whole tree again)

// type signature
setShowOnly: (node?: string) => void

action: setStatus

// type signature
setStatus: (status?: { msg: string; onCancel?: () => void; }) => void

action: setSubFeatureRows

// type signature
setSubFeatureRows: (arg: boolean) => void

action: setTrackHeight

resize every track sharing a heightKey; see trackHeights

// type signature
setTrackHeight: (heightKey: string, height: number) => void

action: setTree

// type signature
setTree: (result: string) => void

action: setTreeFilehandle

// type signature
setTreeFilehandle: (treeFilehandle?: FileLocationType) => void

action: setTreeMetadata

// type signature
setTreeMetadata: (result: string) => void

action: setTreeMetadataFilehandle

// type signature
setTreeMetadataFilehandle: (treeMetadataFilehandle?: FileLocationType) => void

action: setWidth

// type signature
setWidth: (arg: number) => void

action: toggleCollapsed

collapse or un-collapse the subtree rooted at the given tree node id

// type signature
toggleCollapsed: (node: string) => void

action: toggleTrack

// type signature
toggleTrack: (id: string) => void

action: zoomIn

// type signature
zoomIn: () => void

action: zoomInHorizontal

// type signature
zoomInHorizontal: () => void

action: zoomInVertical

// type signature
zoomInVertical: () => void

action: zoomOut

// type signature
zoomOut: () => void

action: zoomOutHorizontal

// type signature
zoomOutHorizontal: () => void

action: zoomOutVertical

// type signature
zoomOutVertical: () => void

action: zoomToPos

Smoothly zoom by a continuous scaleFactor. The column under the cursor (offsetX/offsetY, px relative to the MSA area) stays anchored horizontally. Vertically the anchor is biased toward y=0 when the alignment nearly fits the viewport, fading to cursor-anchoring as the alignment grows taller than the viewport. Drives wheel/trackpad-pinch zoom. axis holds one cell dimension fixed; the held axis still re-anchors its scroll offset, since the other one can change how much of the alignment fits.

// type signature
zoomToPos: (scaleFactor: number, offsetX: number, offsetY: number, axis?: "both" | "horizontal" | "vertical") => void

action: zoomToRegion

zoom and scroll so a span fills the alignment's width, in highlight coordinates (see visibleSpan). Does nothing before the viewer knows its width, or for a span that resolves to no visible column.

// type signature
zoomToRegion: (region: Region) => void