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. showReferenceAlleles: false paints the background solid grey and draws only ALT alleles on top, which makes overlapping structural variants easier to see. 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',
      showReferenceAlleles: false,
    },
  ],
}

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 SharedVariantDisplay16 slots
showReferenceAlleles
boolean = false		Starting value for drawing reference alleles. When false, the row background is filled solid grey and only ALT alleles are painted on top (makes overlapping variants easier to see); when true, reference alleles are drawn normally. Seeds referenceDrawingMode the first time a config is loaded.
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
showRowSeparators
boolean = false		Draw a hairline between adjacent sample rows. Off by default, and only drawn once rows are at least 4px tall — below that the line is as thick as the row it borders.
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 hoveredGenotype 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.
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
maybeBoolean = true promotable		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, which is what a one-record SV call genotyped across a handful of carriers wants.
colorBy
string = ''		Name of a sample-metadata attribute (a column in the adapter's samplesTsvLocation, e.g. 'population') to color the sidebar rows by; empty means no grouping
groupBy
string = ''		Name of a sample-metadata attribute (a column in the adapter's samplesTsvLocation, e.g. 'population') to order the sample rows by, so each group's rows are contiguous and a group-restricted genotype pattern reads as one band; empty means the rows keep their existing order
referenceDrawingMode
stringEnum (draw, skip) = 'skip'		A 'draw'/'skip' toggle for reference alleles, settable independent of showReferenceAlleles (the admin-config-only starting default). No fallback derivation at read time — preProcessSnapshot below seeds this from showReferenceAlleles once, the first time a config lacking it is hydrated, so from then on this slot alone is the single source of truth.
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
Inherited from BaseLinearDisplay5 slots
maxFeatureScreenDensity
number = 1		maximum features per pixel before showing a "too many features" message
advanced
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
jexlFilters
stringArray = []		config jexlFilters are deferred evaluated so they are prepended with jexl at runtime rather than being stored with jexl in the config
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