core
Auto-generated from exported functions tagged #api in the source. See
imports and re-exports for how to
import these from a plugin.
AggregateOp
One summary over a group: count needs no field; sum, mean, min and
max read one, skipping values that are not numbers. The output field is
as, else count or <op>_<field>.
AggregateStep
One feature per distinct groupby value set (one for the whole region
with none), spanning its members' extent, carrying the group's fields and
every ops entry.
BinStep
Snap every feature to the genome-aligned bin of step bp its field
(start by default) falls in, writing the bin's edges over the fields
as names — start and end by default, so an aggregate grouped by
those counts per bin and the bar spans the bin.
buildColorRampLut
An RGBA lookup table over sampleColorRamp, laid out as the Nx1
texture both GPU backends upload and the Canvas2D twins index — entry i is
the color at t = i / (N - 1). N comes off the shader that samples it, so
the table and rampColor's texel mapping cannot disagree.
mid is where the stop list's own midpoint lands in the table, so a
diverging ramp whose middle colour belongs at a value off the centre of the
domain is baked into the bytes. Every reader — the shader, the Canvas2D
fillStyle table, the legend bar — then samples one evenly spaced table and
cannot disagree about the warp.
// type signature
(stops: readonly ColorRampStop[], mid?: number) => Uint8Array<ArrayBuffer>categoricalField
// type signature
(field: string, { domain, range, }?: { domain?: readonly string[] | undefined; range?: readonly string[] | undefined; }) => CategoricalFieldCategoricalField
One categorical field as every channel reads it — a facet's sections, a
color's range entries, a key's rows. key files a value, compare
orders keys (the domain first, the rest by compareGroupKeys, ''
after them), label names a key in a legend, sectionLabel on a chip, and
color paints it. A key's color depends only on the key and the
declaration, so every region agrees on it.
CategoricalRef
A field bound to a categorical scale: each distinct value takes one entry
of the channel's range — a colour for color, a glyph name for
glyph. Every value derives its entry from itself (an integer takes the
slot it names, anything else hashes in), so every region agrees on a value
it shares with another at the cost of an occasional collision. A domain
spends the range deliberately: the listed values take it in order, and a
value the domain leaves out never takes a listed value's entry. The domain
orders and spends; it never adds a value the data lacks.
ChannelReader
A channel read per feature: the compiled form of a FieldRef, and what a display's own worker method hands the encoder for a channel no field name can say — a join against a second adapter, a lookup table, a rule over two fields.
COLOR_SCHEMES
The named ramps a continuous colour scale's scheme takes, each one a stop
table in colorRamp.ts that every ramp baker reads, so no display can name
a scheme nothing bakes.
// type signature
readonly ["viridis"]ColorEncoding
How a mark's color channel resolves. A CSS colour or a jexl: expression
returning one paints per feature with no scale; the object forms bind a
field to a scale, which a legend can describe, and share the config's
member names.
colorEvaluator
A CSS colour or jexl: colour expression as a per-feature packed ABGR —
the unscaled arm of ColorEncoding, on its own for a display that
carries a plain color slot.
// type signature
(color: string, jexl: JexlInstance | undefined) => (feature: Feature) => numbercolorRampStops
The stops a continuous colour scale samples: range's CSS colours where it
lists any, else the named scheme, viridis while that is unset, turned
round under reverse.
// type signature
({ range, scheme, reverse, }: { range?: readonly string[] | undefined; scheme?: "viridis" | undefined; reverse?: boolean | undefined; }) => readonly ColorRampStop[]ColorScaleTable
The scale a colour channel was resolved through, as the legend reads it — the same table the colours in the payload came from, so the key cannot disagree with the painting.
ColorSchemeName
ContinuousRef
A numeric field read through a linear or log scale into a ramp. Each end of
the domain is pinned by domainMin or domainMax, or is the region's own
extreme where unset, so pinning both keeps colours consistent across a
whole view. The ramp is range's CSS colours, evenly spaced, where it
lists any, else the named scheme; reverse turns it round.
CoverageStep
Replace the features with runs of constant depth: how many of them overlap
each stretch of the region, in a field as (coverage by default), with
the stretches nothing overlaps left out.
EncodeContext
What surrounds an encode: the jexl instance a jexl: channel compiles
against — a caller whose channels are all readers or field names passes
none — and a progress reporter.
Encoded
EncodedChannels with the lanes in L present — what
encodeFeatures answers a caller that named them.
EncodedChannels
One encoding's channels over one region's features, dense and
index-aligned: instance i of every array is the same feature, and
featureIndex[i] says which one of the input list it was. A lane is
present when the caller asked for it (LaneName); Encoded
is this type with a known lane set required.
encodedChannelTransferables
The buffers an EncodedChannels owns, for rpcResult's transfer
list.
// type signature
(c: EncodedChannels) => ArrayBufferLike[]EncodedFeaturesResult
What CoreEncodeFeatures answers for one region: layers[i] is the
request's layers[i] over the region's features, so a display's mark
list indexes straight into it.
encodeFeatures
Evaluate one encoding over a feature list into dense channel arrays for
the lanes named, the scale table each scaled channel came from, the y
extremes and — when index is among the lanes — a hit index.
A feature whose x, x2 or (declared and asked-for) y is not finite is
skipped and counted in skipped, so every array stays index-aligned with
the Flatbush. Pure: the RPC around it owns the adapter, the filters and the
transferables.
// type signature
<L extends LaneName>(features: readonly Feature[], encoding: MarkEncodingInput, lanes: readonly L[], ctx?: EncodeContext) => Encoded<L>FacetedLayer
One layer of a faceted request: its features in section order, and the stacked row of each, index for index.
facetLayers
A faceted request's layers: the features split on field's key, each
layer's own steps run over each section alone, and the sections stacked —
a section's rows start where the one above it ends, and it is as tall as
the tallest layer packed it. Every layer's features come back in section
order beside their stacked rows, so a faceted display is the unfaceted one
drawn once per section, and a feature is handed on as its steps left it.
// type signature
(features: readonly Feature[], field: string, layers: readonly {…}[], jexl?: JexlInstance | undefined) => { ...; }FacetSection
One faceted section as the worker stacked it: its key, the row it starts on and how many rows it holds.
FacetSpec
A row facet: split the features on field's value, run every layer's own
steps over each section alone, and stack the sections, each starting on the
row after the one above it ends.
fieldReader
What a channel reads off a feature: a field by name, a dotted path into a
structured field where no field carries the whole name (INFO.SVTYPE on a
VCF record), or a jexl: expression over feature. A jexl expression that
does not compile throws here, once, rather than on every feature.
// type signature
(ref: string, jexl: JexlInstance | undefined) => (feature: Feature) => unknownFieldRef
Where a channel's value comes from: a feature field name, read natively
(feature.get(name)), or a jexl: expression over feature — the opt-in
escape, measured at 1.5x to 2.0x native per feature (MARK_ENCODING.md
"The jexl channel, measured").
FilterStep
Keep the features a jexl: expression over feature admits.
FlattenStep
Fan each feature out into one feature per element of an array-valued field
— subfeatures, so a gene answers its transcripts and a transcript its
exons. Each answer reads the element's own fields first and the feature it
came from for everything else, so an exon still knows its gene's name and
strand. A feature whose field holds no array drops out unless keepEmpty
says otherwise.
FormulaStep
Write a jexl: expression's value over feature into the field as of
every feature.
GLYPH_CODES
The point shape's glyph code for each name an encoding can say.
// type signature
Record<GlyphName, number>GlyphEncoding
A GlyphName, a jexl: expression over feature returning one, or
a field bound to a categorical scale whose range lists the glyph names
handed out — the three glyphs, in order, when absent.
GlyphScaleTable
The scale a glyph channel was resolved through: which glyph each value of the field took.
hitIndexOf
The hit index over count instances: each a box from x to x2 at its
y, or at 0 for a mark with no value.
// type signature
(x: Uint32Array<ArrayBufferLike>, x2: Uint32Array<ArrayBufferLike>, y: Float32Array<ArrayBufferLike> | undefined, count?: number) => FlatbushisPlainFieldRef
Whether a field ref is a bare name: what feature.get answers on its own,
with no path to walk and no expression to evaluate. A loop over a plain name
keeps the direct call, and only a config that writes a path pays for one.
// type signature
(ref: string) => ref is neverLaneName
The lanes a caller asks the encoder to fill, beyond x, x2 and
featureIndex, which every payload carries: a shape's channels, and
index for the Flatbush a hover reads. A lane not asked for is neither
allocated nor transferred, and a caller that never hovers declines the
index, which is most of the encoder's cost after the walk.
LayerRequest
One layer of a CoreEncodeFeatures request: the encoding to evaluate and
the lanes the display's shape reads.
MarkEncoding
The declared mapping from a feature's fields to a mark's channels. Every
positional channel is a field: x defaults to start and x2 to end, a
mark that plots no value leaves y off, and the scale y is read through
belongs to the display rather than to the encoding. glyph is read by the
point shape alone, row — an integer field, 0 where missing — by every
shape, which stands a feature in the band it names.
MarkEncodingInput
What encodeFeatures takes: a MarkEncoding, any channel of which
may be a ChannelReader in place of its declared form, and row the
values themselves, one per input feature, where the caller computed them —
a facet's stacked rows. The declared form is what crosses the wire; a
reader or a value list is built in the worker.
NO_VALUE_LABEL
The row a feature with nothing in a categorical field lands on, so a key says why a mark is grey rather than listing a blank value.
// type signature
"(no value)"numericDomain
A domain written as strings — the shared domain slot is a stringArray —
read back as the numbers it names. A member that is not a number reads NaN,
which every comparison against it declines.
// type signature
(domain: readonly (string | number)[]) => number[]PileupStep
Assign every feature the lowest row on which it overlaps nothing already
there — greedy first fit in start order, the packing a pileup is — and
write it to the field as (row). fields names the interval read
(start, end); padding is bp of clearance kept between two features
sharing a row. The answer is the input in start order, so a span
encoding row stacks it. Under a facet it packs each section on its own.
rampDomain
The domain a continuous colour scale spans: each end min or max pins,
else the extent's, ascending, since a span has no direction and reverse
is the ramp's. An open end stops at a pinned one rather than crossing it,
and an extent holding no value ([Infinity, -Infinity]) spans [0, 1].
// type signature
(min: number | undefined, max: number | undefined, extent: readonly [number, number]) => [number, number]rampOverExtent
A ramp table over extent, the union a display took across the regions it
loaded: each open end of the domain moved to the union's, the pinned ends
kept, and the table baked again where a domainMid places its middle stop
by that domain. Each region baked its own, so keeping the first region's
put the middle colour at a value none of them declared.
One table per stop list and middle position, so a display asking again over an extent that has not moved gets the bytes it already uploaded: a backend re-uploads a ramp on identity.
// type signature
(table: {…}, extent: [...]) => { ...; }relight
Move a color's OKLCH lightness by lightnessShift and scale its chroma,
holding its hue.
For extending a categorical palette past its length. Cycling a nine-color list over a 24-chromosome karyotype repeats the color outright; cycling it with a lightness shift per lap gives the hue back as a variant still told apart from the original — tab20's construction, which pairs a light and a dark of each hue.
SHIFT rather than a fixed lightness, and SCALE rather than a fixed chroma, because a categorical palette is uneven on purpose: category10's brown and its red are 5 degrees apart in hue and are told apart by chroma alone, so re-lighting both to one (lightness, chroma) makes them the same color. Keeping each color's own relative chroma keeps brown reading as brown.
In OKLCH rather than through lighten/darken, which work in sRGB, where
the same coefficient moves a yellow and a blue by visibly different amounts:
a lap has to read as one tone across the whole palette or it reads as noise.
// type signature
(color: string, lightnessShift: number, chromaScale?: number) => stringrunTransforms
Run the transform steps over a feature list, in order, in the worker. The list a step answers is what the next one reads, and the last one is what the encoder walks.
// type signature
(features: readonly Feature[], steps: readonly TransformStep[], jexl?: JexlInstance | undefined) => readonly Feature[]sampleColorRamp
The color at t in [0, 1] across a list of EVENLY SPACED stops, linearly
interpolated per channel. t is clamped, so the ends are the end stops
rather than an extrapolation past them, and a one-stop ramp is that stop
everywhere.
// type signature
(stops: readonly ColorRampStop[], t: number) => ColorRampStopScaleTable
Any channel's scale table; the kind names the channel.
SessionPaletteProvider
Make JBrowse follow the host's light/dark state — the whole of it, in one mount:
<SessionPaletteProvider session={session} mode={myAppIsDark ? 'dark' : 'light'}>
{tracks}
</SessionPaletteProvider>mode is optional. Left out, JBrowse follows the page's declared
color-scheme — so a host whose dark-mode toggle sets it, as most do, mounts
this with a session and nothing else — and the OS preference where the page
declares none.
A component rather than a documented pair of calls because the pair has a
half that can be left out with nothing to show for it. PaletteProvider is
the name a host reaches for, and it colors the React side alone; the session
write is what reaches the RPC worker, which bakes feature labels into the
rendered image. So a host that mounts only the provider gets light-mode
labels on a dark page, from a canvas whose every other pixel is right, and
nothing errors. See useSessionPalette for the mechanism.
The session is the only thing that resolves a palette here, so a host
supplying colors of its own mounts PaletteProvider directly instead.
// type signature
({ session, mode, children, }: { session: ThemeModeSession; mode?: "dark" | "light" | undefined; children: ReactNode; }) => ElementstopsFromRampLut
n evenly spaced legend stops read straight out of a
buildColorRampLut byte table — the same 256×1 RGBA array
uploadColorRampLut hands the GPU and the Canvas2D fillStyle LUTs index —
as the stops of a RampScale. It holds one claim by construction: the
swatch at bar fraction t is byte-identical to the ramp entry at t on
both backends. Alpha rides opacity (the juicebox fade), never baked into
the color string.
// type signature
(lut: Uint8Array<ArrayBufferLike>, n: number) => RampStop[]STRAND_FIELD
// type signature
"strand"thresholdCuts
A threshold scale's cut points as thresholdIndex walks them: the numbers the domain names, ascending. Cuts written high to low, as p-value thresholds often are, left the middle interval unreachable, the walk stopping at the first cut a value is under.
// type signature
(domain: readonly (string | number)[]) => number[]thresholdIndex
The bin a value falls in: how many of the ascending cut points it is at or
past, so a palette with one more entry than the domain paints it as
palette[thresholdIndex(value, domain)]. A value that is not a finite
number is in no bin and answers -1.
// type signature
(value: unknown, domain: readonly number[]) => numberthresholdLabels
What a threshold scale's bins are called in a key, one label per palette
entry: < a below the first cut, a – b between two, ≥ b past the last.
// type signature
(domain: readonly number[]) => string[]thresholdPalette
The colour of each interval, in order: the declared palette, and the default categorical palette where it runs out.
// type signature
(bins: number, palette?: readonly string[]) => string[]ThresholdRef
A numeric field cut into intervals: domain is the ascending cut points
and range holds one colour more, so a value paints the entry for the
number of cut points it is at or past. A value that is not a number
belongs to no interval.
TransformStep
One step over the features before a layer is encoded, named by type the
way GenomeSpy spells a transform; every step runs in order and the next
reads what the last answered.
VIRIDIS_STOPS
The 256 viridis stops, fully opaque. Feed them to buildColorRampLut for the texture/fillStyle form, or to sampleColorRamp for legend stops.
// type signature
readonly ColorRampStop[]ZoomRange
The bp/px interval, [minBpPerPx, maxBpPerPx), over which an adapter with
zoom levels answers a fetch from the same level it answered opts.bpPerPx
from. A display holding the answer refetches when the view leaves it.
Related links
- Guide: Dependencies and re-exports