Skip to main content

TreeSidebarMixin

Auto-generated from the @jbrowse/mobx-state-tree model in the source — see the developer guide for concepts. Built into JBrowse core. View source.

Row set with a dendrogram sidebar, its arrangement the display's rows config object and its row colors the rowColor object, each written as a session edit to the track's config so undo, reset and a share link reach it and it survives unticking the track. Brings the sidebar toggles, the runClustering / clusterRegion and sortRowsBy declarative launch specs setupTreeSidebarAutoruns consumes, the row arrangement every shared consumer goes through, the rows derived from it (editableSources, clusterableSources) with the arrangement dialog's applyRowEdits, the root getter, and the tree-hover and canvas-ref volatiles the shared sidebar draws through. A display supplies discoveredRows, and guideTreeNewick where its adapter carries a tree, and overrides the hooks its rows need

The rows are derived in stages, each a computed of its own: the display's discoveredRows, then expandedRows (expandRows: a variant display's haplotypes), then editableSources, ordered by rowOrder, relabelled by rows.labels and each carrying its resolved rowColor, then clusterableSources, narrowed to the focus, then bandedSources, stacked in the bands rowBanding names.

A row's color is resolvedRowColors: its rowColor entry (a name pair, or the color dealtRowColors deals its attribute value), else its own color, else the row palette's color by name where rowPaletteDeals. The sidebar draws it as a bar beside the row's label, and a display paints its marks in it where rowColorPaintsMarks. Its key is rowColorScales, and a click on an entry focuses that entry's rows (focusLegendEntry).

Every arrangement write reaches the session at once rather than after the track's 400 ms save, so a clustering run is one undo step and undoable the moment its tree appears. "Reset row order" returns each member, and rowColor where it sets a row a color, to what the config.json declares, or what a track the session owns was added with, and never touches rows.field.

Properties

MemberDescription
runClustering
runClustering: types.maybe(types.boolean)		Transient declarative launch spec, the same idea as LinearGenomeView's init: a session or config sets this true and the real clustering RPC runs once automatically, with no dialog, as soon as the display reports itself ready. setupRunClusteringAutorun clears it afterwards, so a saved session never re-triggers.
clusterRegion
clusterRegion: types.maybe(types.string)		Where that run reads from, as a locstring (whitespace-separated for several). Clustering is region-scoped, so naming the locus lets a session cluster on the signal and then show it against its context. Cleared with runClustering, since it is that flag's argument.
sortRowsBy
sortRowsBy: types.maybe(types.frozen<RowSortSpec>())		Transient declarative launch spec, the same idea as runClustering: set {refName, pos} to order the rows once by the value each carries at that genomic column — the session-expressible form of the right-click "Sort rows by ... here". setupRowSortAutorun applies it once the region containing it has loaded and then clears it, so the resulting order persists but a saved session never re-sorts.

Volatiles

MemberDescription
hoveredTreeNode
HoveredTreeNode | undefined
treeCanvas
HTMLCanvasElement | null
mouseoverCanvas
HTMLCanvasElement | null

Getters

MemberDescription
showTree
boolean		Whether the dendrogram sidebar is drawn.
showBranchLength
boolean		Whether tree nodes are positioned by branch length (dendrogram) or evenly by topology (cladogram).
showRowLabels
boolean		Whether each row's name is drawn over the left of the plot.
treeAreaWidth
number		Width in px of the sidebar the dendrogram draws in. On the config rather than the display snapshot for the same reason height is: the config node outlives the display instance, so a dragged width survives unticking and reticking the track.
rowDomain
string[]		The row order, rows.domain: the rows it names lead, in its order, and the rest follow as unlistedRowsSort says.
rowLabels
Readonly<Record<string, string>>		The labels drawn in place of row names, rows.labels, by name.
rowTreeProvenance
ClusterProvenance | undefined		What rowTree was computed from, the locus and the settings; undefined for a tree that arrived as data.
rowFocus
readonly string[] | undefined		The row names a focus narrows the display to, rows.kept — a clade picked off the tree or a key row's rows — or undefined while every row shows.
rowColorSetting
RowColorSetting		The rowColor object: the row attribute whose values take colors, name where it names none, and the values given a color of their own.
baseRowColor
RowColorSetting		The rowColor object this display's base declares, which a reset returns to and "is this the reader's" compares against.
baseRowDomain
readonly string[]		The rows.domain this display's base declares: the base arrangement a row palette deals over, so no reorder recolors a row.
discoveredRows
S[]		Overridable hook, which every display overrides: the rows as the data reports them, before any arrangement. A getter, and a stable-identity one wherever the rows come off region payloads, so a refetch of the same rows re-derives nothing.
guideTreeNewick
string | undefined		Overridable hook: the guide tree the display's adapter supplies, as newick, which rowTree draws while some rotation of it lists rows.domain. It never enters rows.tree, since the adapter re-supplies it on every load. None by default.
rowAlias
RowAlias | undefined		Overridable hook: the name a row also answers to, for a display whose rows stand for something named by another name (a variant display's haplotype rows, each answering to its sample). An order, a label, a color and a focus written against the alias reach every row answering to it. None by default.
unlistedRowsSort
UnlistedRowsSort		Overridable hook: where the rows rowOrder does not list go, in the order they arrived by default.
rowBanding
RowBanding | undefined		Overridable hook: the attribute the rows stack in bands by and the bands listed first, or undefined, the default, for no bands.
svgSidebar
SvgSidebarProps | undefined		Overridable hook: what the SVG export draws in the sidebar left of the track, or undefined, the default, for none. SvgTreeSidebar draws it and svgSidebarWidth sizes the gutter from it.
rowsHeaderHeight
number		Overridable hook: the px of bands, an axis inset or anything else the display stacks above its rows, 0 by default.
rowFocusLineHeight
number		The line the "Showing N rows" chip takes above the first row while rows.kept narrows the rows, 0 while every row shows.
rowsTopOffset
number		Where the rows start in the display's box: under the display's own rowsHeaderHeight and the focus chip's line. Every row painter, hit test, label, tree and export places the rows from here.
guideTree
HierarchyNode<NewickNode> | undefined		guideTreeNewick parsed and rotated towards rows.domain; undefined while the display supplies none.
guideTreeHonoursDomain
boolean		Whether the rotated guide tree lists rows.domain's names in rows.domain's order, which holds exactly when some rotation of it does.
rowTree
string | undefined		The tree the rows are arranged by, as newick: rows.tree, else the guide tree while guideTreeHonoursDomain. A reorder no rotation produces hides the guide tree, and a reset brings it back.
rowOrder
readonly string[]		Overridable hook: the names the rows are placed by, rows.domain by default; MAF leads with a drawn tree's leaves.
expandedRows
S[]		discoveredRows through expandRows: the rows at the granularity drawn, before any arrangement.
sharesPanel
boolean		Overridable hook: whether the rows share one panel, so nothing but color tells them apart. False by default.
rowColorPaintsMarks
boolean		Overridable hook: whether a row's color paints its data marks, which holds while nothing else colors them. True by default.
rowNoun
string		Overridable hook: what one row is called, which titles the row color key where it lists the rows by name in a shared panel. "Row" by default, which only a display of its own that shares a panel would show; a wiggle overlay's rows are subtracks.
internalRowFields
readonly string[]		Overridable hook: the row fields that are a display's own plumbing, which the arrangement dialog never lists as a column.
rowColorFields
readonly string[]		Overridable hook: the row attributes a reader can color the rows by, offered beside None and Each row. By default every attribute a row carries but its name, label and colors.
rowBandingNotices
string[]		A line for the corner notice when rows have arrived and none carries the field rowBanding bands by, which then bands nothing. Each display spreads it into its notices.
rowPaletteDeals
boolean		Whether the palette deals each row a color by name: only where the rows share one panel and their color paints the marks.
rowColorDealRows
readonly S[]		The rows the palette deals over: expandedRows in the base arrangement, so no reorder, focus or relabel recolors a row.
rowStylingIsCustom
boolean		Whether rowColor gives its field's values colors the config does not, so "Reset row order" is offered for a recolor too: whether rowColorResetTarget has anything to write. What the rows are colored by is no arrangement, so picking it is never custom.
rowColorChoice
string		What the rows are colored by, as the arrangement dialog and a menu offer it: '' for none dealt, name for a palette color each, or an attribute.
rowColorAttribute
string		The attribute the rows are colored by, or '' by name.
dealtRowColors
ReadonlyMap<string, string>		The color each value of the config's rowColor field takes, listed pairs first and then in the order dealt.
rowColorAttributesOffered
readonly string[]		The attributes a reader can color the rows by: rowColorFields, and the current one where the rows lack it, so it still shows as chosen.
resolvedRowColors
ReadonlyMap<string, string>		Each row's color, by name: its rowColor entry, else its own color, else the palette's where rowPaletteDeals. The one answer every display paints a row's color from.
rowArrangementIsCustom
boolean		Whether the arrangement differs from what the config declares — what "Reset row order" is offered on.
editableSources
S[]		The rows in the reader's arrangement, each with its resolved rowColor, and with no focus or band: the list the arrangement dialog edits, so a submit writes back only what the reader chose. expandedRows itself while nothing is arranged or colored.
rowColorKeyInputs
RowColorKeyInputs		What the row color key and its focus read of the colors.
rowColorScales
CategoricalScale[]		The row color key, which every display spreads into its colorScales: one scale titled by the rowColor field, or none where it has no entries. Its entries (rowColorKeyEntries) show where the labels cannot name the colors: by an attribute, or by name in a shared panel. By name on stacked rows the labels are the key.
clusterableSources
S[]		Overridable hook: editableSources narrowed to the focus, the rows a clustering run clusters, and deliberately not the display's decorated sources, whose palette and band a run has no business writing back. MAF applies a focus as given on a track that discovers its species.
parsedTree
HierarchyNode<NewickNode> | undefined		rowTree parsed. A run rotated its tree in the same write as the order it produced; a tree that arrived as data rotates towards rows.domain here, and the guide tree is guideTree's parse.
root
HierarchyNode<NewickNode> | undefined		The parsed tree narrowed to the focus.
bandedRows
{ rows: S[]; bands: RowBand[]; }		bandedSources and rowBands, from one pass over the rows.
bandedSources
S[]		clusterableSources stacked in bands by rowBanding, each band's rows in their arranged order: the rows each display paints its palette over. clusterableSources itself while nothing bands.
rowBands
readonly RowBand[]		Each band's value, label and the rows it spans in bandedSources; none while nothing bands.
sources
S[]		Overridable hook: the rows drawn, top to bottom, bandedSources by default. MAF drops its hidden reference row.
treeRoot
HierarchyNode<NewickNode> | undefined		Overridable hook: the tree hierarchy positions, root by default. computeClusterHierarchy declines to position a tree whose leaves are no longer the rows drawn, so a display that hides a row prunes it from the tree here too, or the whole dendrogram goes with the row.
drawsTree
boolean		Overridable hook: whether the dendrogram draws at all, true by default; off wherever the rows it would lay against are not drawn. This is the single gate: the on-screen sidebar, the SVG export, spatialIndex (subtree hover) and the tooltip dead zone the sidebar reserves all read hierarchy, so none keeps drawing or reserving space on its own.
rowsContentHeight
number		The px the rows stack to, sources × effectiveRowHeight, which the dendrogram's leaves spread over: the content the rows scroll through, never the viewport they scroll inside.
hierarchy
ClusterHierarchyNode | undefined		The dendrogram positioned against the rows drawn, or undefined while there is no tree or drawsTree is off. computeClusterHierarchy checks the tree's leaves against the drawn row names, the backstop against anything reordering sources downstream of the arrangement: such a reorder drops the dendrogram rather than drawing it against rows it does not name.
spatialIndex
TreeSpatialIndex | undefined		The hit index the sidebar's subtree hover reads, built from hierarchy.
clusterPartition
string[][] | undefined		The names of the rows a clustering run clusters, by band, so each band clusters apart and the run writes one forest; undefined while fewer than two bands stack.
treelessBandCount
number		How many bands the tree draws no dendrogram for, because it holds no clade whose leaves are that band's rows in order; 0 with no tree or no bands.
treeHasBranchLengths
boolean		Whether the tree carries merge heights, so a dendrogram layout differs from the cladogram; gates the "Tree branch lengths" toggle.

Methods

MemberDescription
expandRows
(rows: S[]) => S[]		Overridable hook: the discovered rows as the rows drawn, the rows themselves by default; a variant display's phased mode expands each sample to its haplotypes.
svgSidebarWidth
(text?: ExportTextStyle | undefined) => number		Px the SVG export reserves left of the track for svgSidebar, measured in the export's text.
rowBand
(row: S) => string		Overridable hook: the band a row stacks in while rowBanding is set, by default its value of the banding attribute, '' for none.
dealtRowColorsFor
(setting: Partial<RowColorSetting>) => ReadonlyMap<string, string>
The color each value takes under setting (dealtValueColors), which the arrangement dialog shows before it writes the setting.
rowColorFor
(choice: string) => RowColorSetting		The rowColor object choice starts from (startingRowColor): the current object's where it shows that choice, else the config's.
rowOrderWillDropTree
(next: readonly { name: string; }[]) => boolean		Whether the arrangement dialog's submit of next drops the tree: an order that moves no row is not written, so it drops nothing, and the guide tree drops only for an order no rotation of it lists.

Actions

MemberDescription
setShowTree
(arg: boolean) => void
setShowBranchLength
(arg: boolean) => void
setShowRowLabels
(arg: boolean) => void
setTreeAreaWidth
(width: number) => void
setRunClustering
(arg?: boolean | undefined) => void
setClusterRegion
(arg?: string | undefined) => void
setSortRowsBy
(arg?: RowSortSpec | undefined) => void		Trigger (or clear) a one-shot declarative row sort; consumed and reset by setupRowSortAutorun.
setHoveredTreeNode
(node?: HoveredTreeNode | undefined) => void
setTreeCanvasRef
(ref: HTMLCanvasElement | null) => void
setMouseoverCanvasRef
(ref: HTMLCanvasElement | null) => void
setRowOrder
(rows: readonly { name: string; }[], run?: ClusterRun | undefined) => void
Arrange the rows in rows' order, ahead of any name the current order carries that rows does not. A clustering run passes its result, and the tree and its provenance land with the order; any other reorder that moves a row drops the tree, which no longer describes it.
setRowLabels
(labels: Readonly<Record<string, string>>) => void		The labels drawn in place of row names, whole: a row the map does not name shows the name it arrived with.
setRowFocus
(names?: readonly string[] | undefined) => void		Narrow the display to names, or show every row again.
applyRowEdits
(rows: readonly S[], rowColor?: Partial<RowColorSetting> | undefined) => void
The arrangement dialog's submit: the rows in their new order, each carrying the label the reader left on it, and the rowColor object the dialog shows, written where it differs from the config's. The labels go to rows by the rule labelEdits states, and the order to rows.domain unless it moves no row, so a submit that changes nothing writes nothing.
resetRowArrangement
() => void		Return every arrangement member — order, labels, tree, provenance and focus — to what the config declares, leaving rows.field, and the rowColor colors to rowColorResetTarget: the config's for the choice, which stays.
setRowColorChoice
(choice: string) => void		Color the rows by choice, as a menu picks it: '' for None, name for Each row, or an attribute, starting from rowColorFor. A pick of the current choice writes nothing.
focusLegendEntry
(scaleId: string, value: string) => void		LegendHost's hook: a click on a row color key entry narrows the rows to those it lists. Every other scale's entries name colors, not rows, and stay inert.