Skip to main content

LinearMultiSampleVariantDisplay

Auto-generated config schema for the current JBrowse release — see the config guide for concepts. Provided by the variants plugin. View source.

Example usage

Minimal VariantTrack config selecting this display type. The displays array form is required here (rather than the object shorthand) because this is a non-default display type — see configuring displays:

{
  type: 'VariantTrack',
  trackId: 'cohort',
  name: 'Cohort variants',
  assemblyNames: ['hg38'],
  adapter: {
    type: 'VcfTabixAdapter',
    uri: 'https://example.com/cohort.vcf.gz',
  },
  displays: [
    {
      type: 'LinearMultiSampleVariantDisplay',
    },
  ],
}

Preloading sample metadata: point the adapter's samplesTsvLocation at a TSV whose first column is the sample name and whose other columns are per-sample attributes (e.g. population), then colorBy one of those attributes to color the sidebar rows on load. referenceDrawingMode: 'skip' (the default) paints the background solid grey and draws only ALT alleles on top, which makes overlapping structural variants easier to see; 'draw' paints the reference alleles too. This is the 1000 Genomes "colored by population" demo config:

{
  type: 'VariantTrack',
  trackId: 'cohort',
  name: 'Cohort variants',
  assemblyNames: ['hg38'],
  adapter: {
    type: 'VcfTabixAdapter',
    uri: 'https://example.com/cohort.vcf.gz',
    samplesTsvLocation: { uri: 'https://example.com/samples.tsv' },
  },
  displays: [
    {
      type: 'LinearMultiSampleVariantDisplay',
      height: 800,
      colorBy: 'population',
      referenceDrawingMode: 'skip',
    },
  ],
}

Phased haplotype rows, two per sample. Sample colors and group labels come from the adapter's samplesTsvLocation above — the display's own layout holds the row arrangement the user drags into place, so it is session state rather than a config slot:

{
  type: 'VariantTrack',
  trackId: 'cohort',
  name: 'Cohort variants',
  assemblyNames: ['hg38'],
  adapter: {
    type: 'VcfTabixAdapter',
    uri: 'https://example.com/cohort.vcf.gz',
  },
  displays: [
    {
      type: 'LinearMultiSampleVariantDisplay',
      height: 400,
      renderingMode: 'phased',
    },
  ],
}

See the Config slots section below for all available configuration fields.

Config slots

These slots go on a display entry: "displays": [{ "type": "LinearMultiSampleVariantDisplay", ... }], or in the track's displayDefaults when this is its default display. Slot types (fileLocation, frozen, ...) are explained in the config slot types reference. Slots a base configuration contributes are listed here too, so this table is the whole surface.

SlotDescription
height
number = 200		Starting height in pixels for the genotype rows; drag-resizable, and the rows divide it while row height is on auto-fit
showInsertionGlyphs
boolean = true		Widen each alt-carrying cell of an insertion to a marker sized by the inserted bp, the same one plugins/alignments and plugins/maf draw, with the bp count when the row is tall enough.

A cell is drawn across the reference the record covers, with a 2px floor. That is right for a SNP and right for a deletion, but an insertion consumes almost no reference, so a 65 kb insertion and a SNP both land on that floor and the structural tier of a pangenome callset becomes unreadable. Only cells whose genotype carries the allele widen, and each keeps its genotype color, so the marker adds length without displacing what the color already says.

This display only: it draws every cell at its genomic position, so a width there is a claim about length. LinearMultiSampleVariantMatrixDisplay lays its columns out by feature index at a uniform width, so it has no such width to correct.
showVariantLane
boolean = false		Draw a LinearVariantDisplay-style lane above the genotype rows: one mark per record at its genomic span, colored by whatever "Color by → Cells" is set to. It answers "which variant am I looking at" without a second track, the relationship the coverage band has to a pileup — shared/variantTopBands.ts holds the band stack.

It is that display's band, drawn by the same code: overlapping records stack onto rows rather than overdrawing one another, and the band compacts to fit the height it is given — dropping descriptions, then thinning IDs, then packing bodies alone. Hovering a mark reports the record (its ID, alleles, length and description), clicking opens its details, and right-clicking opens the same menu a genotype cell does, including the split view for a breakend.

One thing it does NOT do that the cells below it do: widen an insertion to its inserted length. A box is its reference span there, so the length of a large <INS> is carried by showInsertionGlyphs on the rows.

Off by default: on, it takes variantLaneHeight px away from the rows, so defaulting it on would resize every existing display and every committed figure.

This display only, for now: it draws every cell at its genomic position, so the lane above lines up with the cells below it column for column. LinearMultiSampleVariantMatrixDisplay lays its columns out by feature index and ties them to the genome with connector lines instead; the band geometry is already shared with it (topBands), but nothing paints the lane there yet.
variantLaneHeight
number = 40		Height of the variant lane, spent only while showVariantLane is on. On the config rather than a prop for the same reason height and lineZoneHeight are: a drag-resize outlives the display instance, so unticking and reticking the track keeps the lane the user sized.
advanced
variantLaneLabels
stringEnum (auto, nameAndDescription, name, description, none) = 'auto'		Letter the lane's marks with each record's VCF ID and/or its description, in plugin-canvas's label font at its measured widths and in its two colors — the same text a LinearVariantDisplay puts under the same record, under the same enum it spells the choice with.

What the band has room for is decided by the same fit ladder that display uses in fit mode, so asking for both kinds is a preference and not a promise: descriptions go first, then IDs are thinned to the records with room for them, then dropped entirely so the boxes can keep their height. Zooming in therefore letters more, and a taller band letters more, both continuously.
Inherited from SharedVariantDisplay20 slots
facet.field
string = ''		Name of a sample-metadata attribute (a column in the adapter's samplesTsvLocation, e.g. 'population') whose values each take their own band of rows, so a group-restricted genotype pattern reads as one band rather than being scattered across the matrix. Bands order by domain, then the way every in-track grouping orders, digits by magnitude. Empty means the rows keep their existing order. Writing facet: 'population' directly on the display lands here.

The band is applied when the rows are read, over whatever order the reader has arranged, so a drag that moves a sample into another band snaps back while this is set. It yields while a cluster tree describes the rows — the dendrogram positions leaf i on row i, so a band under it would draw it against the wrong rows. Clear the tree, or reset the row order, to band a clustered track.
facet.domain
stringArray = []		Optional band order: the values listed come first, in this order, and the rest follow sorted. Left off, the bands are every value the metadata holds, sorted. A listed value the metadata lacks takes no band.
lineZoneHeight
number = 0		Height of the zone above the rows holding the lines that tie each matrix column to its genomic position. 0 (the default here) means no zone at all — only the matrix display, which lays columns out by feature index rather than at their genomic positions, raises it.
advanced
showTooltips
boolean = true		Show the hover tooltip naming the genotype, the sample and the record under the pointer. On by default; turning it off leaves every other hover affordance — the crosshairs, the highlighted cell, the cross-display session.hovered channel — alone, so the pointer still says where it is while the panel stops covering the rows beside it.

A config slot rather than a display property, so a track config can ship with it off and a figure capture keeps it off across a reload. Both multi-sample displays honor it: they draw the same tooltip off the same hoveredFeature slot.
renderingMode
stringEnum (alleleCount, phased) = 'alleleCount'		'alleleCount' draws one row per sample colored by allele dosage; 'phased' draws one row per haplotype
featureColor
string = ''		Optional per-feature color for the genotype cells: a jexl expression (or plain CSS color) evaluated once per variant in the worker, painting every alt-carrying cell with that color while ref/no-call cells keep their normal coloring so "who carries it" still reads. Empty means the default genotype-based coloring (allele dosage / phasing). The "Color by..." menu offers presets like consequence impact (jexl:impactColor(feature)), but any feature jexl works, same as the standard color slot.
shadeByDosage
boolean = true		Compose the cell hue with the genotype's alt dosage — the fraction of its called alleles that are non-reference — so a homozygote paints the hue itself and a heterozygote a lighter version of it. On by default, and on in every color mode: turn it off to paint each alt-carrying cell its flat hue, which reads the class or impact tier at full strength at the cost of the zygosity.
minorAlleleFrequencyFilter
number = 0		Hide variants whose minor allele frequency is below this threshold
advanced
maxMissingnessFilter
number = 1		Hide variants whose fraction of no-call (missing) genotypes is above this threshold; 1 keeps every variant
advanced
showLegend
boolean = true		Whether to draw the floating legend over the display. It is clipped to the display's own bounds, so while it is on it sets a floor under the lane height: turn it off to size a short lane to its rows rather than to its key, as for a one-record SV call genotyped across a handful of carriers.
colorBy
string = ''		The tint is resolved when the rows are read, and while it is set it wins over any color a row already carried — a color column in the samplesTsv, one the arrangement dialog wrote, one an older session persisted. A channel bound to a variable beats a per-row constant; clear this to hand each row back its own color.
facet
variantFacetSchema		The row facet: a sample-metadata attribute, or an object naming it and its band order, whose values each take their own contiguous band of sample rows.
referenceDrawingMode
stringEnum (draw, skip) = 'skip'		Whether to paint reference alleles: 'skip' (the default) fills the row background solid grey and paints only ALT alleles, which makes overlapping variants easier to pick out; 'draw' paints reference alleles like any other genotype.
jexlFilters
stringArray = []		default set of jexl filters to apply to a track. note: these do not use the jexl prefix because they have a deferred evaluation system
rowHeight
number = 0		per-row height in px, scrolling the rows that do not fit; 0 (the default) fits the rows to the display height instead, dividing it between them
showTree
boolean = true		Show the sample clustering tree in the sidebar
showBranchLength
boolean = true		position tree nodes by branch length (dendrogram) rather than evenly by topology (cladogram)
showRowLabels
boolean = true		Show the per-sample row labels in the sidebar
domain
stringArray = []		Row order: the samples listed come first, in this order, and the rest keep the file's order; a facet groups within it. A clustering run rotates its dendrogram towards this order instead of discarding it, so the listed samples come as early as the tree allows
showRowSeparators
boolean = false		draw a hairline between adjacent rows; off by default, because a painting whose neighbouring rows differ in color already separates itself and the line only earns its pixel where they do not — a run of same-colored rows reads as one block without it, with no way to recover the row count by eye. Drawn only once rows are at least 4px tall: below that the line is as thick as the row it borders, turning a dense painting into a grid of hairlines with a little color between them
Inherited from BaseLinearDisplay3 slots
mouseover
string = 
'jexl:get(feature,'_mouseOver')||get(feature,'name')||get(feature,'function')||get(feature,'id')'
text to display when the cursor hovers over a feature
callback args: feature
fetchSizeLimit
number = 1_000_000		maximum data to attempt to download for a given track, used if adapter doesn't specify one
advanced
forceLoad
boolean = false		Declarative equivalent of the "Force load" button on the "too much data" banner: when true the display always renders, however large the region or dense the features. Off by default (the gate guards against huge downloads). Set it on a view no one can interact with — an embedded / notebook view, or a screenshot — where the region is known and you want it drawn without a click.
advanced