DotplotDisplay
Auto-generated @jbrowse/mobx-state-tree API for the current JBrowse release —
see pluggable elements for concepts. Provided by the
dotplot-view plugin.
View source.
The configuration slots for this model are documented on its config schema page.
Members a composed model contributes are listed here too, so these tables are the whole surface.
Properties
| Member | Description | Defined by |
|---|---|---|
typetype: types.literal('DotplotDisplay') | DotplotDisplay | |
configurationconfiguration: ConfigurationReference(configSchema) | DotplotDisplay | |
idid: ElementId | BaseDisplay |
Volatiles
| Member | Description | Defined by |
|---|---|---|
rpcDatarpcData: undefined as DotplotRpcData | undefined | RPC-computed feature data | DotplotDisplay |
instanceDatainstanceData: undefined as DotplotInstanceData | undefined | GPU-instance positions produced from rpcData, self-describing via embedded bpPerPx, with no colors in them. Rebuilt only when the data or the zoom changes; the palette is joined on top by the geometry getter. | DotplotDisplay |
fetchWarningsfetchWarnings: [] as ComparativeWarning[] | What the last completed fetch had to say about itself, written with the data it describes (see setRpcData). | DotplotDisplay |
hoveredSegmentIdxhoveredSegmentIdx: -1 | Index into instanceData's per-SEGMENT arrays of the line the pointer is nearest, or -1.The segment rather than the feature, even though the tooltip and the highlight are both about the feature: the feature index derives from this one ( hoveredFeatureIdx below), and the CIGAR operator under the cursor derives from nothing else — a CIGAR-detailed alignment is a staircase of segments and the pointer is on one step of it. Same choice LinearSyntenyDisplay.hoveredInstanceIdx makes, where getFeature does the translating.It addresses instanceData, so it is dropped by BOTH writers of that — a zoom rebuilds the geometry without refetching. | DotplotDisplay |
errorerror: undefined as unknown | BaseDisplay | |
statusMessagestatusMessage: undefined as string | undefined | BaseDisplay | |
statusProgressstatusProgress: undefined as number | undefined | determinate progress fraction [0,1] for the current status, or undefined when the in-flight phase is indeterminate. Set alongside statusMessage by setStatusMessage; a display that never shows a bar simply leaves it undefined. | BaseDisplay |
fetchingfetching: false | True while an RPC fetch is in-flight. Combined with ready it distinguishes a first load (no data yet — full overlay) from a refetch (stale content still on screen — corner indicator). | SyntenyFetchStateMixin |
loadedFetchKeyloadedFetchKey: undefined as string | undefined | Fetch-input signature the currently held data was fetched for (each display builds its own currentFetchKey). Compared against the live inputs in dataCurrent to catch data gone stale after a region/zoom change — including during the pre-refetch debounce gap, where fetching is still false and would otherwise report done on content drawn against the old viewport. | SyntenyFetchStateMixin |
assembliesSwappedassembliesSwapped: false | Set once at view load by a refName-comparison check, independent of the per-render fetch, so it never re-fires or misfires on zoom. Surfaces through each display's warnings. | SyntenyFetchStateMixin |
reloadCounterreloadCounter: 0 | Bumped by reload(). Read unconditionally by installComparativeFetchAutorun, so it is always in the autorun's dependency set — which is the whole point: after an error the fetch inputs are unchanged, so nothing else would ever refire the autorun and the error banner's Retry would be a button that does nothing. | SyntenyFetchStateMixin |
fetchCanceledfetchCanceled: false | True from the moment the user clicks Cancel on the loading overlay (cancelFetchByUser) until reload() clears it. Durable and blocking: installComparativeFetchAutorun gates on it, so nothing restarts the load in the meantime — not a zoom, not a region change, and no timer.That is the deliberate half. These displays sit on single RPCs that can run for minutes against a remote index, so a cancel any pan quietly undoes is not a cancel, and a retry that re-arms itself hammers the server that just failed. The way back is the overlay's Retry button and nothing else — LoadingOverlay draws it off this flag. | SyntenyFetchStateMixin |
stopActiveFetchstopActiveFetch: () => {} | Stops the in-flight RPC. installComparativeFetchAutorun hands over its stop-token rotation's cancel at install (setStopActiveFetch): the rotation lives in that skeleton's closure, one per install and beside the fetch that uses it, and this mixin holds no fetch machinery of its own (ADR-054).A cancel that cannot reach it is not a cancel. Nothing else rotates the token, so the run the user stopped watching stays isCurrent() and COMMITS its result when it lands — the plot appears, the overlay disappears, and the cancel is undone by the fetch it cancelled. Stopping the token is also the only thing that tells the worker to drop the reads still in flight, which is half of why a user clicks it.A no-op until the skeleton installs, so a display with no fetch autorun can still be asked. | SyntenyFetchStateMixin |
Getters
| Member | Description | Defined by |
|---|---|---|
viewDotplotViewModel | The plot this display draws into. One getter rather than a getContainingView cast per reader, the same way LinearSyntenyDisplay.view answers it.This names the view type even though the view names this display back ( dotplotDisplays). That mutual reference resolves only because both model types are declared as interface … extends Instance<…> rather than type … = Instance<…> — see ADR-055. | DotplotDisplay |
displayKeynumber | Stable slot on the view-shared backend. Hashed from the node id, not taken from the track's index, so hiding or reordering a sibling can't hand this display another's buffer. | DotplotDisplay |
readyboolean | A fetch has completed (data is present, even if it mapped zero features). Not a feature-count test — an empty-but-finished fetch is ready, otherwise an empty plot spins the loading overlay forever. | DotplotDisplay |
computedColorsUint32Array<ArrayBufferLike> | undefined | Main-thread-computed per-segment colors — the gpuProps half of the rpcProps/gpuProps split. A colorBy change recomputes this alone, without re-walking a single CIGAR. Opacity is NOT read here. It rides the shader's alpha uniform (and drawDotplotInstances' param) off DotplotView.dotplotRenderState, so the slider is a redraw, not a recolor — the same split synteny makes. Baking it in made every drag frame recompute this array, re-pack every instance and re-upload the buffer. | DotplotDisplay |
paintedChromosomeOrderreadonly string[] | undefined | The chromosome order the chromosome-painting modes color by: the refNames of whichever axis' assembly colorBy names, in the assembly's own order. Undefined for every other mode, and while the assembly is still loading — the color function falls back to its hash there.It has to come from the assembly rather than from the features, because a color must not change with which chromosomes happen to be in view. The dotplot twin of LinearSyntenyDisplay.paintedChromosomeOrder, off the two axes instead of two stacked levels: 'query' is the horizontal axis (the feature's own refName lane) and 'target' the vertical (the mate's). 'reference' is a stacked-view mode with no dotplot meaning, and the shared color function falls it back to query — with no order, since naming an axis for it would be inventing an answer. | DotplotDisplay |
colorBySyntenyColorBy | The mode this track renders with: its own override if the user set one, else the plot-wide mode. | DotplotDisplay |
trackColorstring | This track's slot in the plot's palette, used by colorBy: 'track'. Assigned by the view, not locally: pinning a color on one track shifts which automatic slots its siblings can take. | DotplotDisplay |
trackIdstring | DotplotDisplay | |
| geometry | Instance positions joined with the computed colors: what the backends upload and what SVG export draws. The view's upload autorun reads this, so a palette change re-uploads without rebuilding geometry. | DotplotDisplay |
hoveredFeatureIdxnumber | Index into rpcData's per-FEATURE arrays of the alignment the pointer is over, or -1. Derived rather than stored, so it cannot disagree with hoveredSegmentIdx about which alignment that is.Not instanceFeatureIdx[i] ?? i: an out-of-range segment index reads undefined there, and falling back to the raw index would answer with a different feature rather than with nothing. Same reasoning as LinearSyntenyDisplay.getFeature. | DotplotDisplay |
tooltipLinesstring[] | undefined | The hovered feature's tooltip, as lines, or undefined when nothing is hovered. The dotplot twin of LinearSyntenyDisplay.tooltipLines; both feed ComparativeTooltip, which renders lines as text nodes — see getDotplotTooltipLines. | DotplotDisplay |
hoveredFeatureHighlightDotplotHoverHighlight | undefined | The hovered feature redrawn over the canvas: an SVG path of its segments in plot px, plus its own packed color as CSS. This is the whole of the hover shading, and it deliberately isn't in either renderer. Synteny boosts alpha and darkens rgb per fragment from a hoveredFeatureId uniform, which costs an instance lane, a uniform, a hand-written Canvas2D twin of the same arithmetic, and a broken color run in drawDotplotInstances' batcher. Restroking one feature — a handful of segments — over the shared canvas needs none of that, and is backend-agnostic by construction: it draws the same over the GPU canvas and the Canvas2D fallback because it never asks which one painted. renderSvg deliberately does not draw it — an off-screen export has no pointer, and a transient hover has no business in a figure.The cue is opacity + width, not hue: the plot's own alpha slider routinely sits at 0.2, so restroking opaque and a few px wider is exactly synteny's "the hovered one goes solid". Nothing here picks a highlight color, because every hue is already in use — category10 paints the chromosome modes, and red/blue/black are the strand and default schemes.Recomputes on pan (through plotTransform's viewBpH/viewBpV), which is what keeps the highlight on its feature, and only while something is hovered. plotTransform rather than dotplotRenderState, which carries alpha and lineWidth too — an opacity drag would rebuild this path once a frame for a value it does not read. | DotplotDisplay |
fetchFlagsComparativeFetchFlags | DotplotDisplay | |
loadingboolean | First load: no data has arrived yet. Drives the centered overlay. | DotplotDisplay |
refetchingboolean | Refetch in-flight: a new fetch is running but a stale plot is still on screen (zoom, diagonalize reorder, pan past the buffer). Drives a subtle corner indicator instead of the full overlay so the visible plot isn't masked on every viewport change. | DotplotDisplay |
fetchRegionsRegion[] | The h-axis fetch window: the visible content blocks expanded by the shared pan buffer and snapped outward to a buffer-sized grid, so a pan within the buffer neither refetches nor exposes an unfetched strip, and zoomed out it collapses to the whole displayed region. The v axis is deliberately not scoped: the fetch is one-dimensional (h regions in, every mate out), so a vertical pan needs no data the h window didn't already bring, and must never trigger a refetch. Unlike synteny, nothing culls this window again in the worker — executeDotplotFeaturesAndPositions maps every feature it is handed — so the window's only job is to be a superset of what's on screen. | DotplotDisplay |
currentFetchKeystring | The fetch-input signature (see fetchKey.ts) for the view's current state. Reactive: recomputes when either axis's zoom or displayed-region order/orientation changes, or when a pan carries the h axis into a new snapped fetch window. As a computed it only notifies when the string itself changes, which is what lets the fetch autorun track it and stay quiet through sub-buffer pans. | DotplotDisplay |
lodTierLodTier | The detail tier this plot's fetch asks the adapter for. Resolved here on the main thread, not adapter-side from bpPerPx, so it is part of currentFetchKey — see resolveLodTier. Both axes feed it: CIGAR detail is worth drawing when a block is wide on either one, so dropping to the no-CIGAR tier is only safe once both are past the threshold. | DotplotDisplay |
dataCurrentboolean | True when the rendered rpcData was fetched for the view's current inputs. Goes false the instant a zoom or diagonalize reorder changes the axes — before the debounced refetch begins and while stale geometry is still on screen — so the settled done-gate can't fire on it. The dotplot analog of LGV's viewportWithinLoadedData. | DotplotDisplay |
displayPhaseDisplayStatusPhase | The display's own mutually-exclusive state, the way every LGV display publishes one — so AppReadyMarker counts this display's fetch, and the app stops reporting itself ready over a plot that is still working. Ranked by comparativeDisplayPhase, off the shared canvas's surfaceReadiness and this display's own fetch state.DisplayStatusPhase, not DisplayPhase: the view owns the rendering backend, so this display can never be the one to report a backend failure. | DotplotDisplay |
warningsComparativeWarning[] | Per-render fetch warnings, plus the load-time reversed-assembly hint. | DotplotDisplay |
svgReadyboolean | Off-screen SVG export gate: "Export SVG" waits on this before drawing (see the SVG export guide). Runs the same shared computeSvgReady policy every other display does and awaits it via the shared awaitSvgReady — no inlined when(). A failed track fails the export rather than drawing itself into the plot; every display paints that one rect, so SVGDotplotView fans them out through awaitSvgRenders and names all of them at once. No regionTooLarge state: the fetch is gated by LOD, not region size. Stale-safe via dataCurrent: an export fired right after a zoom/diagonalize reorder waits for geometry rebuilt from the fresh fetch instead of exporting the stale plot. | DotplotDisplay |
parentTrackAbstractTrackModel | BaseDisplay | |
RenderingComponentFC<…> | BaseDisplay | |
| DisplayBlurb | BaseDisplay | |
adapterConfigRecord<string, unknown> | BaseDisplay | |
isMinimizedboolean | Returns true if the parent track is minimized. Used to skip expensive operations like autoruns when track is not visible. | BaseDisplay |
hoveredFeatureunknown | Overridable hook (default undefined): what the pointer is currently over, for readers outside the display. LinearGenomeViewContainer publishes it to session.hovered, the view-wide "what is the user pointing at" channel a plugin can subscribe to.Declared here because a cross-display consumer can only read a name the base declares — the same reason SyntenyFetchStateMixin.fetchInert is a hook rather than a getter each display invents. The container used to read featureUnderMouse, which only the wiggle, alignments and Manhattan families spelled that way — canvas said hoveredFeature, variants hoveredGenotype — so the channel carried a hover from a third of the display types and nothing said which. It also asked only displays[0] of each track.unknown because the payload genuinely differs — a read, a wiggle bin, a SNP, a genotype cell — and session.hovered is typed to match ("can be anything; code that wants to deal with this should examine it"). Narrow it in the override. | BaseDisplay |
featureNounstring | Overridable hook (default 'feature'): the SINGULAR word for one of the things this display draws, as a menu row or a chip says it — "Hide this read", "Showing 3 variants".Declared here for the same reason as hoveredFeature above: it is read across the display boundary, by chrome that has no idea which display it is drawing for (SoloSelectionChip, alignments' group-label overlay), and a name only the base declares is a name every such consumer can rely on. Two displays declared it independently and one of those declarations WAS this default.A control keeps the generic word; content takes this one. "Variant height" reads as a different setting from "Feature height" when it is the same one, so the shared menus stay on "feature" however the display answers here, and the noun varies where it names what the user is looking at — "Showing 3 variants", "Hide this read". A display drawing something the generic word already fits is right to leave this alone. Distinct from the per-hit noun a context menu takes off the clicked item's own type ("mRNA", "gene"); that names one annotation, this names what the track holds. The hit noun falls back to this. | BaseDisplay |
featureWidgetType{ type: string; id: string; } | Overridable hook: which widget openFeatureWidget opens for one of this display's features. The default is the generic one, which is what a display drawing plain features wants and what the canvas base spelled out by hand.An override is a display whose features have a vocabulary of their own — a read, a variant, a synteny block — and the id is deliberately part of it: two displays naming one id share the drawer panel, which is the behaviour when the two are showing the same kind of thing. | BaseDisplay |
fetchInertboolean | Overridable hook, default false: the states where this display's fetch autorun deliberately never runs, so it holds no data and none is coming. Anything waiting on data has to treat those as terminal rather than wait forever — which is why the answer lives in one place and is read by the autorun's own gate, the loading overlay, the SVG export's extraTerminal, and displaysSettled below.displaysSettled is the reason this is a mixin hook rather than a display-local getter: it is the one reader outside the display, and without the hook it demanded dataCurrent from a display whose loadedFetchKey can never be set — wedging the view's settled gate, and with it the data-display-drawn screenshot capture waits on.Default false is the strict answer, so a display that grows an inert state and forgets to say so keeps waiting for data (diagnosable) rather than reporting done without it (silently wrong). Dotplot leaves it: its prepare bails only before the view is initialized, which the view's own canvasDrawn/canRender gate already covers. | SyntenyFetchStateMixin |
Methods
| Member | Description | Defined by |
|---|---|---|
| renderSvg | DotplotDisplay | |
| renderingProps | props passed to the renderer's React "Rendering" component. these are client-side only and never sent to the worker. includes displayModel and callbacks | BaseDisplay |
() => MenuItem[] | BaseDisplay |
Actions
| Member | Description | Defined by |
|---|---|---|
| setRpcData | Commits a fetch result and the warnings it raised, tagged with the key it was fetched for. One action, not three: the warnings describe this result, so writing them separately let a failed refetch leave the last result's warnings standing over data they no longer describe, and each extra action is another round of the view's warning/upload observers per RPC completion. Same reason LinearSyntenyDisplay.setRpcData takes its feature and instance data together.The loading flags are deliberately NOT touched here: this runs as installComparativeFetchAutorun's commit, whose finally clears fetching and the status line under the same staleness guard. Clearing them here too meant one of the two comparative displays wrote fetching directly instead of through setFetching, for no effect the skeleton wasn't about to have anyway.setError is not overridden either: the two callers that set one (the fetch skeleton's catch, afterAttach's) already log it, so the override this display used to carry printed every fetch failure twice — and had to special-case undefined because the skeleton clears the error through the same setter before every fetch. | DotplotDisplay |
setInstanceData(data: DotplotInstanceData | undefined) => void | DotplotDisplay | |
setHoveredSegmentIdx(idx: number) => void | Written by the view's setHoveredFeature, which points the whole plot's hover at one hit — never per display from a component, so the N writes land in one MobX batch. | DotplotDisplay |
setStatusMessage(status?: RpcStatus | undefined) => void | BaseDisplay | |
setError(error?: unknown) => void | BaseDisplay | |
clearHoveredFeature() => void | Overridable hook (default no-op): drop whatever hoveredFeature reports. The writing twin of that getter, and what installClearHoverOnViewportChange calls.A display that STORES its hover owes an override; one that derives it from the live pointer (MAF, Hi-C, LD) owes nothing, and the default costs it nothing. Declared here so the clear can be installed for every display rather than remembered per display — forgetting it is the failure ARCHITECTURE.md's stored-hover section is about, and it used to be six closures at six call sites, which is six chances to omit one. | BaseDisplay |
reload() => void | base display reload does nothing, see specialized displays for details | BaseDisplay |
setFetching(arg: boolean) => void | SyntenyFetchStateMixin | |
setAssembliesSwapped(arg: boolean) => void | SyntenyFetchStateMixin | |
setStopActiveFetch(stop: () => void) => void | Install-time wiring, called once by installComparativeFetchAutorun — see stopActiveFetch for why the stop arrives from there rather than being built here. | SyntenyFetchStateMixin |
cancelFetchByUser() => void | The loading overlay's Cancel. Stops the in-flight RPC and lands in the durable fetchCanceled state, so the fetch autorun's gate holds until reload() reopens it.Same name as FetchMixin's, which is what lets one overlay set serve all three fetch families (DisplayLoadingOverlayModel names it). What has no twin here is the internal half of that split, cancelFetch — stop, clear the flag, bump a generation to retrigger — because it exists there for clearAllRpcData, and this family has nothing that resets a display behind the user's back. reload() is the only thing that reopens the gate, which is exactly the constraint: retry is a button, never an automatic re-arm.Clears fetching itself, because nothing else will: the in-flight run's finally writes it only while isCurrent(), and the stop above just closed that guard. | SyntenyFetchStateMixin |