@jbrowse/core (util)
Auto-generated from exported functions tagged #api in the source. See
imports and re-exports for how to
import these from a plugin.
adapterRefName
Mints the brand where a file's name for an out-of-request location is first read.
import { adapterRefName } from '@jbrowse/core/util'
function adapterRefName(refName: string): AdapterRefNameAdapterRefName
A refName in a data file's own spelling that names a location the request
did not ask for: a mate, a supplementary alignment, a synteny target
(agent-docs/reference/REFNAME_NAMESPACES.md). A plain string at runtime.
Deliberately not a string subtype, so it cannot meet a canonical name
unconverted: comparing it with a string is TS2367, and handing it to a
string parameter, a Map<string, _> or a Record<string, _> is TS2345 or
TS2538. canonicalAdapterRefName converts it, adapterRefNameText spells it.
import type { AdapterRefName } from '@jbrowse/core/util'
interface AdapterRefName {
readonly __refNameNamespace: 'adapter'
}adapterRefNameText
The file's spelling as text, for display or for handing back to the adapter that spelled it. Not for comparing with view state.
import { adapterRefNameText } from '@jbrowse/core/util'
function adapterRefNameText(refName: AdapterRefName): stringBand
One band of a display's vertical stack — a coverage histogram, an arc strip,
a conservation row. The contract is the pair: active is
whether the band exists right now (the display pre-ANDs its settings half,
showX, with its data half, "some lane has ink"), and height is the stated
height when it does. Consumers read pixels through reservedPx or
stackBands, never by re-combining the pair, so the reserver and the
painter use the same pixel values.
import type { Band } from '@jbrowse/core/util/bandLayout'
interface Band {
active: boolean
height: number
bounds?: BandBounds
}bandAt
The band under content-space y, or undefined below the stack or over a
band that reserves nothing. The pointer's half of the fold: a band's hover
reads the same tops and heights its painter drew at.
import { bandAt } from '@jbrowse/core/util/bandLayout'
function bandAt<K extends string>(stack: BandStack<K>, y: number): K | undefinedbandDragBounds
The legal range for a drag of band key in a stack folded from
boundStackedBands.
import { bandDragBounds } from '@jbrowse/core/util/bandLayout'
function bandDragBounds<K extends string>(
stack: BandStack<K>,
key: K,
plot: BandPlot,
): { max: number }BandPlot
The plot a stack of bands is taken from: the px the bands and the plot
share, and the px the plot keeps under any stack — MIN_BAND_HEIGHT
while it draws, so its rows stay visible and the lowest band's handle stays
on the display, and 0 while it draws nothing.
import type { BandPlot } from '@jbrowse/core/util/bandLayout'
interface BandPlot {
height: number
floor: number
}baseDisplayConfig
The base's entry for this display, hydrated, which a reset returns to and "is this the reader's" compares against: the config.json's, or the one a track the session owns was added with; empty in a session that keeps no base.
import { baseDisplayConfig } from '@jbrowse/core/util/baseDisplayConfig'
function baseDisplayConfig(self: object): Record<string, unknown>boundBandHeight
Bound a band height to its legal range — a config value, a menu choice, or a slider position, i.e. anywhere the number is being stated rather than dragged.
The floor keeps the band operable at its smallest: for a drag-resized
band that means keeping the handle grabbable, for a menu-sized one it is the
height below which its content stops reading. The ceiling stops a band
from swallowing the plot it sits over — every display floors its plot area at
0, so an unbounded band takes the rows to zero height rather than to a
scrollbar, and takes the band's own handle off-screen with them. Bands that
share a plot take their ceilings from the stack (boundStackedBands in
bandLayout), since one band's ceiling depends on the others.
The bounds differ per band and the rule does not, so this takes the bounds and each band does not re-derive the rule.
import { boundBandHeight } from '@jbrowse/core/util/bandHeight'
function boundBandHeight(n: number, opts?: BandBounds): numberboundStackedBands
A stack's stated heights — a config value, a session snapshot, a drag made on a taller track — bound against the plot the bands share, top-down: each active band takes at most the room the active bands above it left, from 0 px up, so the stack never takes the plot below its floor. An inactive band reserves nothing, so it is bound to the whole room and comes back at a legal height. Bind here, then fold with stackBands.
import { boundStackedBands } from '@jbrowse/core/util/bandLayout'
function boundStackedBands<K extends string>(
order: readonly K[],
bands: Record<K, Band>,
plot: BandPlot,
): Record<K, Band>canonicalAdapterRefName
The assembly's canonical name for an adapter-spelled refName, through
getCanonicalRefName2; the file's spelling when there is no assembly.
import { canonicalAdapterRefName } from '@jbrowse/core/util'
function canonicalAdapterRefName(
assembly: { getCanonicalRefName2: (refName: string) => string } | undefined,
refName: AdapterRefName,
): stringcanonicalizeViewRefName
Resolve user-authored refName text against the assembly of the view
containing node, resolving aliases and casing together. Falls back to the
input when the assembly is absent or its aliases have not loaded.
Uses the view's assembly, not the track's, because displayed regions, loaded regions and blocks all use the refNames the view laid out.
Call it wherever a refName a person wrote is about to be compared against regions, features or blocks, which use the assembly's canonical name. A refName a display copied off a region is already canonical. One from a session spec, a config slot or a URL is whatever the author typed.
Without it, matching depends on the assembly: chr12 matches on an assembly
canonicalized chr12 and matches nothing on one canonicalized 12. The
same spec key works on one config and does nothing on the next, with no
error.
Resolves through getCanonicalRefName2, which falls back to the input
instead of throwing when a spec is read before the alias file has loaded.
The getters that read user specs run from the first render.
Takes a refName, not a spec that might hold one. The resolver calls
refName.toLowerCase(), so any other value throws once the aliases have
loaded, and a caller reading an untyped frozen slot must first check that
the value is a refName.
import { canonicalizeViewRefName } from '@jbrowse/core/util'
function canonicalizeViewRefName(
node: IAnyStateTreeNode,
refName: string,
): stringclampBandHeight
Clamp one resize of a drag-resizable band: boundBandHeight, plus the one rule a resize needs that a stated height does not.
The floor becomes min(bounds.min, current), never the bare bound: a band
whose config declares it smaller than the floor must stay where it is. Taking
the bare floor instead made the first drag on such a band jump it up to the
floor before honoring the delta. A band at or above the floor is unaffected,
one below it can still be dragged but never smaller than it already is, and
one dragged back past the floor regains it.
The ceiling is not relaxed the same way — a band already over its ceiling is the state the user is trying to escape, so a resize brings it back inside.
A drag passes ResizeHandle the band's height as value and this setter as
onChange: the handle aims at the height at the press plus the pointer's
travel, so the seam waits at a clamp until the pointer comes back to it.
import { clampBandHeight } from '@jbrowse/core/util/bandHeight'
function clampBandHeight(
current: number,
target: number,
bounds?: BandBounds,
): numberdragBandHeight
One resize of band key in a stack folded from boundStackedBands:
clampBandHeight from the band's folded height, so a band a config
declared under its floor stays where it is, whether or not it draws, up to
the room the other bands leave the plot above its floor. min is the
band's drag floor, MIN_BAND_HEIGHT by default.
import { dragBandHeight } from '@jbrowse/core/util/bandLayout'
function dragBandHeight<K extends string>(
stack: BandStack<K>,
key: K,
plot: BandPlot,
target: number,
min?: number,
): numberelectronRenderer
The renderer half of electron, reached through the Node require an
Electron window runs with. Throws outside Electron.
import { electronRenderer } from '@jbrowse/core/util/electron'
function electronRenderer(): ElectronRendererfillStackedBands
A stack that fills height exactly, for a plot that draws nothing under its
bands: every band reserving px takes a share of height in proportion to
the px it reserves (scaleBandHeights, whole px, from 0), and every
other band fills 0. Answers each band's filled height by key.
import { fillStackedBands } from '@jbrowse/core/util/bandLayout'
function fillStackedBands<K extends string>(
order: readonly K[],
bands: Record<K, Band>,
height: number,
): (key: K) => numbergetAssemblyHost
The host's assembly manager, for a module that resolves names and nothing else.
Unlike the accessors in sessionServices.ts this one gives the caller no
smaller type graph — an AssemblyManager is an MST model a PluginManager
built, so naming it costs what naming a session costs. It is here to say
which service is wanted, and because that cost is the finding: the assembly
manager is the one thing on AbstractSessionModel a third-party host cannot
simply implement.
import { getAssemblyHost } from '@jbrowse/core/util'
function getAssemblyHost(node: IAnyStateTreeNode): AssemblyHostgetContainingDisplay
Returns the display model that contains the given node. Throws if the node has no containing display.
import { getContainingDisplay } from '@jbrowse/core/util'
function getContainingDisplay(node: IAnyStateTreeNode): AbstractDisplayModelgetContainingTrack
Returns the track model that contains the given node. Throws if the node has no containing track.
import { getContainingTrack } from '@jbrowse/core/util'
function getContainingTrack(node: IAnyStateTreeNode): AbstractTrackModelgetContainingView
Returns the view model that contains the given node. Throws if the node has no containing view.
import { getContainingView } from '@jbrowse/core/util'
function getContainingView(node: IAnyStateTreeNode): AbstractViewModelgetDialogHost
Where a display puts a dialog it cannot mount itself.
import { getDialogHost } from '@jbrowse/core/util'
function getDialogHost(node: IAnyStateTreeNode): DialogHostgetEnv
Returns the MST environment for a node, which holds the pluginManager.
import { getEnv } from '@jbrowse/core/util'
function getEnv(obj: IAnyStateTreeNode): { pluginManager: PluginManager }getNotificationSink
Where a display puts a message it cannot draw itself. An error is also kept
on the outermost view holding node, as view.problems.
import { getNotificationSink } from '@jbrowse/core/util'
function getNotificationSink(node: IAnyStateTreeNode): NotificationSinkgetPaletteHost
The colors to draw with, and the args that rebuild them in a worker.
import { getPaletteHost } from '@jbrowse/core/util'
function getPaletteHost(node: IAnyStateTreeNode): PaletteHostgetRenderingServices
Everything a display needs of its host in order to draw a region: the assemblies, the RPC entry point and the colors.
import { getRenderingServices } from '@jbrowse/core/util'
function getRenderingServices(node: IAnyStateTreeNode): RenderingServicesgetRpcHost
The host's RPC entry point, for a module that issues RPCs and nothing else.
import { getRpcHost } from '@jbrowse/core/util'
function getRpcHost(node: IAnyStateTreeNode): RpcHostgetSession
Returns the JBrowse session model for any node in the state tree. Throws if the node has no session ancestor.
import { getSession } from '@jbrowse/core/util'
function getSession(node: IAnyStateTreeNode): AbstractSessionModelgetSessionServices
The services a session offers that need no application-specific type to name. Prefer one of the narrower accessors below, which say which of them the calling module actually uses.
import { getSessionServices } from '@jbrowse/core/util'
function getSessionServices(node: IAnyStateTreeNode): SessionServicesinvokeElectronMain
Calls an Electron main-process handler, checked against ElectronMainChannels.
import { invokeElectronMain } from '@jbrowse/core/util/electron'
function invokeElectronMain<K extends keyof ElectronMainChannels>(
channel: K,
...args: ElectronMainChannels[K]['args']
): Promise<ElectronMainChannels[K]['return']>launchOrReplaceView
addOrReplaceView for view types whose state model may be lazily loaded;
the synchronous addOrReplaceView requires it loaded already.
import { launchOrReplaceView } from '@jbrowse/core/util'
function launchOrReplaceView(args: {
session: AbstractViewContainer
typeName: string
initialState?: Record<string, unknown>
replacing?: AbstractViewModel
}): Promise<AbstractViewModel>persistTrackConfigNow
Write the containing track's config to the session now, not after its 400 ms wait, so an edit is one undo step the moment it lands: every writer of a row arrangement, a lane choice or an axis setting calls it (ADR-157). Does nothing for a node outside a track.
import { persistTrackConfigNow } from '@jbrowse/core/util'
function persistTrackConfigNow(node: IAnyStateTreeNode): voidreservedPx
The pixels a band takes from the plot below it: 0 when off, the stated height when on. This is the single spelling of "off spends 0 px".
import { reservedPx } from '@jbrowse/core/util/bandLayout'
function reservedPx(band: Band): numberrunLazyAfterAttach
Run a display's afterAttach body from a module loaded on demand, so the
autorun installers stay out of the display's eager bundle.
One policy for the gap the await opens: a node torn down before the module
lands installs nothing, and a module that fails to load is reported where the
user can see it rather than onto the display's own error slot — that slot is
what reload() clears, and nothing would re-run the install behind it.
Three displays hand-rolled this IIFE and each drew the lines differently.
import { runLazyAfterAttach } from '@jbrowse/core/util/lazyAfterAttach'
function runLazyAfterAttach<Self extends IStateTreeNode>(
self: Self,
load: () => Promise<(self: Self) => void>,
): voidscaleBandHeights
Heights after growing or shrinking a stack of bands by distance px in all:
the one rule every whole-stack resize uses. Each band takes its share of the
height it has above floor, so the tall bands give and take the most, and
none goes below floor, or below its current height if it already sits under it
(the clampBandHeight rule). Whole pixels, rounded by largest
remainder, so the stack moves by exactly the rounded distance.
import { scaleBandHeights } from '@jbrowse/core/util/bandHeight'
function scaleBandHeights(
heights: number[],
distance: number,
floor?: number,
): number[]stackBands
Fold an ordered set of bands into tops and a bottom. The order is the argument, so a display states its band order exactly once. Reserve, paint and pick all call this function, so the reserved and painted positions cannot disagree.
Only the fold is shared; the rest stays in each display. Per-lane iteration runs this once per lane, sticky-vs-scrolling is a property of how the result is projected to the screen, and a band drawn outside its reservation (an overlay) has a separate draw rect beside the stack.
import { stackBands } from '@jbrowse/core/util/bandLayout'
function stackBands<K extends string>(
order: readonly K[],
bands: Record<K, Band>,
): BandStack<K>