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 InterProScan domain 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

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

Available via MSAModel

Properties: bgColor, colorSchemeName, msaFormat

Actions: setColorSchemeName, setBgColor, setMSAFormat

MsaView - Properties

property: allowedGappyness

// type signature
number
// code
allowedGappyness: defaultAllowedGappyness

property: collapsed

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

// type signature
IArrayType<ISimpleType<string>>
// code
collapsed: types.array(types.string)

property: colWidth

width of columns, px

// type signature
number
// code
colWidth: defaultColWidth

property: currentAlignment

// type signature
number
// code
currentAlignment: 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
true
// code
drawMsaLetters: defaultDrawMsaLetters

property: featureFilters

// type signature
IMapType<ISimpleType<boolean>>
// code
featureFilters: types.map(types.boolean)

property: gffFilehandle

filehandle object for InterProScan GFF file

// type signature
IMaybe<ISnapshotProcessor<ITypeUnion<any, { locationType: "UriLocation"; uri: string; internetAccountId: string | undefined; internetAccountPreAuthorization: ModelSnapshotType<{ internetAccountType: ISimpleType<string>; authInfo: IType<...>; }> | undefined; } | ModelSnapshotType<...> | ModelSnapshotType<...> | Model...
// code
gffFilehandle: types.maybe(FileLocation)

property: height

height of the div containing the view, px

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

property: hideGaps

// type signature
true
// code
hideGaps: 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[] | undefined, number[] | undefined, number[] | undefined>
// code
highlightColumns: types.frozen<number[] | undefined>()

property: id

id of view, randomly generated if not provided

// type signature
IOptionalIType<ISimpleType<string>, [undefined]>
// code
id: ElementId

property: msaFilehandle

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

// type signature
IMaybe<ISnapshotProcessor<ITypeUnion<any, { locationType: "UriLocation"; uri: string; internetAccountId: string | undefined; internetAccountPreAuthorization: ModelSnapshotType<{ internetAccountType: ISimpleType<string>; authInfo: IType<...>; }> | undefined; } | ModelSnapshotType<...> | ModelSnapshotType<...> | Model...
// code
msaFilehandle: types.maybe(FileLocation)

property: relativeTo

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

property: rowHeight

height of each row, px

// type signature
number
// code
rowHeight: defaultRowHeight

property: scrollX

scroll position, X-offset, px

// type signature
number
// code
scrollX: defaultScrollX

property: scrollY

scroll position, Y-offset, px

// type signature
number
// code
scrollY: defaultScrollY

property: scrollZoom

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

// type signature
false
// code
scrollZoom: defaultScrollZoom

property: showDomains

// type signature
false
// code
showDomains: defaultShowDomains

property: showOnly

focus on particular subtree

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

property: subFeatureRows

// type signature
false
// code
subFeatureRows: defaultSubFeatureRows

property: treeFilehandle

filehandle object for the tree

// type signature
IMaybe<ISnapshotProcessor<ITypeUnion<any, { locationType: "UriLocation"; uri: string; internetAccountId: string | undefined; internetAccountPreAuthorization: ModelSnapshotType<{ internetAccountType: ISimpleType<string>; authInfo: IType<...>; }> | undefined; } | ModelSnapshotType<...> | ModelSnapshotType<...> | Model...
// code
treeFilehandle: types.maybe(FileLocation)

property: treeMetadataFilehandle

filehandle object for tree metadata

// type signature
IMaybe<ISnapshotProcessor<ITypeUnion<any, { locationType: "UriLocation"; uri: string; internetAccountId: string | undefined; internetAccountPreAuthorization: ModelSnapshotType<{ internetAccountType: ISimpleType<string>; authInfo: IType<...>; }> | undefined; } | ModelSnapshotType<...> | ModelSnapshotType<...> | Model...
// code
treeMetadataFilehandle: types.maybe(FileLocation)

property: turnedOffTracks

turned off tracks

// type signature
IMapType<ISimpleType<boolean>>
// code
turnedOffTracks: types.map(types.boolean)

property: type

hardcoded view type

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

MsaView - Volatiles

volatile: blockSize

size of blocks of content to be drawn, px

// type signature
number
// code
blockSize: 500

volatile: conservationTrackHeight

// type signature
number
// code
conservationTrackHeight: 40

volatile: error

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

volatile: headerHeight

// type signature
number
// code
headerHeight: 0

volatile: highlightedColumns

array of column indices to highlight

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

volatile: highResScaleFactor

high resolution scale factor, helps make canvas look better on hi-dpi screens. derived from the device pixel ratio so canvases are crisp on retina/4k displays and not needlessly oversized on standard ones

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

volatile: hoveredTreeNode

the currently hovered tree node ID and its descendant leaf names

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

volatile: interProAnnotations

// type signature
Record<string, InterProScanResults> | undefined
// code
interProAnnotations: undefined as
        | undefined
        | Record<string, InterProScanResults>

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 | undefined
// code
mouseClickCol: undefined as number | undefined

volatile: mouseClickRow

the currently mouse-click row

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

volatile: mouseCol

the currently mouse-hovered column

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

volatile: mouseRow

the currently mouse-hovered row

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

volatile: resizeHandleWidth

resize handle width between tree and msa area, px

// type signature
number
// code
resizeHandleWidth: 5

volatile: status

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

volatile: volatileWidth

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

MsaView - Getters

getter: actuallyShowDomains

// type
boolean

getter: adapterTrackModels

// type
BasicTrack[]

getter: alignmentNames

// type
string[]

getter: allBranchesLength0

// type
boolean

getter: blanks

// type
number[]

getter: blanksSet

// type
Set<number>

getter: blocks2d

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

getter: blocksX

// type
number[]

getter: blocksY

// type
number[]

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 | undefined
}
;[]

getter: colorScheme

// type
Record<string, string>

getter: colStats

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

getter: colStatsSums

// type
number[]

getter: columns

// type
Map<string, string>

getter: columns2d

// type
string[]

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: fontSize

// type
number

getter: header

// type
{ info: string; version: string | undefined; } | Record<string, unknown> | { General: Record<string, string[]>; Accessions: { [k: string]: string; }; Dbxref: { [k: string]: string; }; }

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: hoveredInsertion

Returns insertion info if mouse is hovering over an insertion indicator

// type
{ rowName: string; col: number; letters: string; } | undefined

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<string, number>

getter: leaves

// type
HierarchyNode < NodeWithIdsAndLength > []

getter: maxBranchLength

max branch length across the tree, used to scale phylogram x-positions

// 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, keeping the last row in view rather than letting the whole alignment scroll off the top. visible MSA height is computed inline here because msaAreaHeight is defined later in the chain.

// type
number

getter: mouseOverRowName

// type
string | undefined

getter: MSA

// type
MSAParserType | null

getter: msaAreaHeight

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

// type
number

getter: msaAreaWidth

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

// type
number

getter: noTree

// type
boolean

getter: numColumns

// type
number

getter: numRows

// type
number

getter: realAllowedGappyness

// type
number

getter: root

// type
HierarchyNode<NodeWithIds>

getter: rowMap

// type
Map<string, string>

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<string, number>

getter: rows

// type
[string, string][]

getter: secondaryStructureConsensus

// type
string | undefined

getter: seqConsensus

// type
string | undefined

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
number

getter: totalWidth

// type
number

getter: tracks

// type
BasicTrack[]

getter: tree

// type
NodeWithIds

getter: treeAreaWidthMinusMargin

// type
number

getter: treeMetadata

// type
any

getter: turnedOnTracks

// type
BasicTrack[]

getter: verticalScrollbarWidth

// type
0 | 20

getter: width

// type
number

MsaView - Methods

method: extraViewMenuItems

unused here, but can be used by derived classes to add extra items

// type signature
extraViewMenuItems: () => never[]

method: getRowData

// type signature
getRowData: (name: string) => { data: { name?: string | undefined; accession?: string | undefined; dbxref?: string | undefined; } | undefined; treeMetadata: any; }

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 | undefined

method: seqPosToGlobalCol

Convert a sequence position (ungapped) to a global column index.

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

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) => number | undefined

method: visibleColToRowLetter

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

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

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.

CROSS-REPO CONTRACT: this and the sibling coordinate converters (seqPosToVisibleCol, globalColToVisibleCol, seqPosToGlobalCol) are used by jbrowse-plugin-protein3d to translate between alignment columns and structure/sequence residue positions across gaps. Keep them stable.

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

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) => number | undefined

MsaView - Actions

action: calculateNeighborJoiningTreeFromMSA

Calculate a neighbor joining tree from the current MSA using BLOSUM62 distances

// type signature
calculateNeighborJoiningTreeFromMSA: () => 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 | undefined) => void

action: exportSVG

// type signature
exportSVG: (opts: { theme: Theme; includeMinimap?: boolean | undefined; includeTracks?: boolean | undefined; exportType: "entire" | "viewport"; }) => Promise<void>

action: fit

// type signature
fit: () => void

action: fitHorizontally

// type signature
fitHorizontally: () => void

action: fitVertically

// type signature
fitVertically: () => void

action: reset

// 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: setColWidth

set col width (px)

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

action: setConservationTrackHeight

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

action: setCurrentAlignment

// 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 | undefined; tree?: string | undefined; treeMetadata?: string | undefined; gff?: string | undefined; }) => void

action: setDomains

Set domain annotations and reveal the overlay in a single step (or clear both when passed undefined). Shared by every domain source: InterProScan, GFF, user-provided uploads, and NCBI CDD.

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

action: setDrawMsaLetters

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

action: setError

set error state

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

action: setGFFFilehandle

// type signature
setGFFFilehandle: (gffFilehandle?: FileLocation | undefined) => 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: setHighlightedColumns

set highlighted columns

CROSS-REPO CONTRACT: called by jbrowse-plugin-msaview (afterCreateAutoruns.ts) to highlight alignment columns. It has no in-repo caller, so do not flag it as dead code — it is public API.

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

action: setHighResScaleFactor

high-res scale factor, tracks the device pixel ratio so canvases stay crisp when the window moves between monitors or the browser zooms

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

action: setHoveredTreeNode

set hovered tree node and its descendants

// type signature
setHoveredTreeNode: (nodeId?: string | undefined) => 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 | undefined, row?: number | undefined) => void

action: setMousePos

set mouse position (row, column) in the MSA

CROSS-REPO CONTRACT: jbrowse-plugin-protein3d calls this (and reads the mouseCol volatile) to sync MSA<->3D-structure hover. Keep the name and signature stable; see that repo's ProteinToMsaHoverSync.tsx.

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

action: setMSA

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

action: setMSAFilehandle

// type signature
setMSAFilehandle: (msaFilehandle?: FileLocation | undefined) => 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)

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

action: setScrollZoom

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

action: setShowDomains

toggle the InterProScan protein-domain 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 | undefined) => void

action: setStatus

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

action: setSubFeatureRows

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

action: setTree

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

action: setTreeFilehandle

// type signature
setTreeFilehandle: (treeFilehandle?: FileLocation | undefined) => void

action: setTreeMetadata

// type signature
setTreeMetadata: (result: string) => 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 the top: when the alignment nearly fits the viewport, snap to y=0 rather than pinning a random row under the cursor, with the bias fading out as the alignment grows taller than the viewport (where cursor-anchoring is useful). Drives wheel/trackpad-pinch zoom.

// type signature
zoomToPos: (scaleFactor: number, offsetX: number, offsetY: number) => void