Skip to main content

LinearMultiSampleVariantMatrixDisplay

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 the matrix display. 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: 'LinearMultiSampleVariantMatrixDisplay',
    },
  ],
}

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 rowColor one of those attributes to color the matrix rows on load (same metadata mechanism as the regular LinearMultiSampleVariantDisplay):

{
  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: 'LinearMultiSampleVariantMatrixDisplay',
      height: 400,
      rowColor: 'population',
    },
  ],
}

Taller matrix filtering rare variants (MAF < 5 %). Row order, per-row color and group labels come from the adapter's samplesTsvLocation above — the display's own layout holds the arrangement the user then 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: 'LinearMultiSampleVariantMatrixDisplay',
      height: 400,
      minorAlleleFrequencyFilter: 0.05,
    },
  ],
}

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

Config slots

These slots go on a display entry: "displays": [{ "type": "LinearMultiSampleVariantMatrixDisplay", ... }], 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 = 250		Starting height in pixels for the whole display, including the lineZoneHeight band above the rows; drag-resizable, and the rows divide what is left over while row height is on auto-fit
lineZoneHeight
number = 20		Raises the shared slot's 0 default: this display lays columns out by feature index, so it needs the zone for the lines tying each column back to its genomic position. Drag-resizable, like height.
advanced
Inherited from SharedVariantDisplay18 slots
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.
callback args: feature
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.
rowColor
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
Facet		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; or { field, domain }, the listed values banding first and the rest sorted. Unset, the rows keep their existing order.

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.
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
treeAreaWidth
number = 80		width in px of the tree sidebar, which a drag on its edge also writes
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