# LinearMultiSampleVariantDisplay

Auto-generated config schema for the current JBrowse release — see the [config guide](https://jbrowse.org/jb2/docs/config_guide) for concepts. Provided by the `variants` plugin. [View source](https://github.com/GMOD/jbrowse-components/blob/main/plugins/variants/src/LinearMultiSampleVariantDisplay/configSchema.ts).

## 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](https://jbrowse.org/jb2/docs/config_guides/tracks#configuring-displays):

```js
{
  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:

```js
{
  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:

```js
{
  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._

## Related links

- **Adapter:** [BedpeAdapter](../bedpeadapter)
- **Adapter:** [SplitVcfTabixAdapter](../splitvcftabixadapter)
- **Adapter:** [StarFusionAdapter](../starfusionadapter)
- **Adapter:** [VcfAdapter](../vcfadapter)
- **Adapter:** [VcfTabixAdapter](../vcftabixadapter)
- **State model:** [runtime API](../../models/linearmultisamplevariantdisplay)
- **Base config:** [SharedVariantDisplay](../sharedvariantdisplay)

## Config slots

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

<!-- prettier-ignore -->
| Slot | Description |
| --- | --- |
| <span id="slot-height">**height**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>200</code> | Starting height in pixels for the genotype rows; drag-resizable, and the rows divide it while row height is on auto-fit |
| <span id="slot-showinsertionglyphs">**showInsertionGlyphs**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | 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.<br><br>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.<br><br>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. |
| <span id="slot-showvariantlane">**showVariantLane**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>false</code> | 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.<br><br>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.<br><br>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.<br><br>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.<br><br>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. |
| <span id="slot-variantlaneheight">**variantLaneHeight**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>40</code> | 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.<br>_advanced_ |
| <span id="slot-variantlanelabels">**variantLaneLabels**</span><br>[`stringEnum`](https://jbrowse.org/jb2/docs/config_guides/slot_types#stringenum) (auto, nameAndDescription, name, description, none) = <code>'auto'</code> | 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.<br><br>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. |
| <span class="slot-group">Inherited from [SharedVariantDisplay](../sharedvariantdisplay)</span> | <span class="slot-group-count">20 slots</span> |
| <span id="slot-facetfield">**facet.field**</span><br>[`string`](https://jbrowse.org/jb2/docs/config_guides/slot_types#string) = <code>''</code> | 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.<br><br>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. |
| <span id="slot-facetdomain">**facet.domain**</span><br>`stringArray` = <code>[]</code> | 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. |
| <span id="slot-linezoneheight">**lineZoneHeight**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>0</code> | 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.<br>_advanced_ |
| <span id="slot-showtooltips">**showTooltips**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | 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.<br><br>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. |
| <span id="slot-renderingmode">**renderingMode**</span><br>[`stringEnum`](https://jbrowse.org/jb2/docs/config_guides/slot_types#stringenum) (alleleCount, phased) = <code>'alleleCount'</code> | 'alleleCount' draws one row per sample colored by allele dosage; 'phased' draws one row per haplotype |
| <span id="slot-featurecolor">**featureColor**</span><br>[`string`](https://jbrowse.org/jb2/docs/config_guides/slot_types#string) = <code>''</code> | 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. |
| <span id="slot-shadebydosage">**shadeByDosage**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | 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. |
| <span id="slot-minorallelefrequencyfilter">**minorAlleleFrequencyFilter**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>0</code> | Hide variants whose minor allele frequency is below this threshold<br>_advanced_ |
| <span id="slot-maxmissingnessfilter">**maxMissingnessFilter**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>1</code> | Hide variants whose fraction of no-call (missing) genotypes is above this threshold; 1 keeps every variant<br>_advanced_ |
| <span id="slot-showlegend">**showLegend**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | 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. |
| <span id="slot-colorby">**colorBy**</span><br>[`string`](https://jbrowse.org/jb2/docs/config_guides/slot_types#string) = <code>''</code> | 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. |
| <span id="slot-facet">**facet**</span><br><code>variantFacetSchema</code> | 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. |
| <span id="slot-referencedrawingmode">**referenceDrawingMode**</span><br>[`stringEnum`](https://jbrowse.org/jb2/docs/config_guides/slot_types#stringenum) (draw, skip) = <code>'skip'</code> | 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. |
| <span id="slot-jexlfilters">**jexlFilters**</span><br>`stringArray` = <code>[]</code> | 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 |
| <span id="slot-rowheight">**rowHeight**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>0</code> | 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 |
| <span id="slot-showtree">**showTree**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | Show the sample clustering tree in the sidebar |
| <span id="slot-showbranchlength">**showBranchLength**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | position tree nodes by branch length (dendrogram) rather than evenly by topology (cladogram) |
| <span id="slot-showrowlabels">**showRowLabels**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>true</code> | Show the per-sample row labels in the sidebar |
| <span id="slot-domain">**domain**</span><br>`stringArray` = <code>[]</code> | 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 |
| <span id="slot-showrowseparators">**showRowSeparators**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>false</code> | 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 |
| <span class="slot-group">Inherited from [BaseLinearDisplay](../baselineardisplay)</span> | <span class="slot-group-count">3 slots</span> |
| <span id="slot-mouseover">**mouseover**</span><br>[`string`](https://jbrowse.org/jb2/docs/config_guides/slot_types#string) = <span class="cell-more"><button type="button" class="cell-more-trigger"><code>'jexl:get(feature,'_mouseOver')&#124;&#124;get(feature,'name')&#124;&#124;get(featu…</code></button><dialog class="cell-dialog"><form method="dialog"><button class="cell-dialog-close" aria-label="Close">✕</button></form><pre><code>'jexl:get(feature,'_mouseOver')&#124;&#124;get(feature,'name')&#124;&#124;get(feature,'function')&#124;&#124;get(feature,'id')'</code></pre></dialog></span> | text to display when the cursor hovers over a feature<br>_callback args:_ `feature` |
| <span id="slot-fetchsizelimit">**fetchSizeLimit**</span><br>[`number`](https://jbrowse.org/jb2/docs/config_guides/slot_types#number) = <code>1_000_000</code> | maximum data to attempt to download for a given track, used if adapter doesn't specify one<br>_advanced_ |
| <span id="slot-forceload">**forceLoad**</span><br>[`boolean`](https://jbrowse.org/jb2/docs/config_guides/slot_types#boolean) = <code>false</code> | 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.<br>_advanced_ |

