Skip to main content

LinearBasicDisplay

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

Example usage

A complete FeatureTrack config (e.g. genes from a GFF3) to paste into tracks. displayMode sets the feature height preset (normal, compact, or superCompact), or collapsed for a single-row overview:

{
  type: 'FeatureTrack',
  trackId: 'genes',
  name: 'Genes',
  assemblyNames: ['hg38'],
  adapter: {
    type: 'Gff3TabixAdapter',
    uri: 'https://example.com/genes.gff3.gz',
  },
  displays: [
    {
      type: 'LinearBasicDisplay',
      displayId: 'genes-LinearBasicDisplay',
      height: 200,
      displayMode: 'compact',
    },
  ],
}

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

configuration for the basic linear feature display (genes, BED, GFF, etc.)

Color slots are display-level: set them inside a track's displays array. color is the main feature fill; use a plain CSS color, or a jexl: expression to color per-feature. (connectorColor and utrColor set the intron lines and UTR fill. The legacy color1/color2/color3 names still work and map onto these.)

{
  "type": "FeatureTrack",
  "trackId": "my_genes",
  "name": "Genes",
  "assemblyNames": ["hg19"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "genes.gff.gz" },
  "displays": [
    {
      "type": "LinearBasicDisplay",
      "color": "blue",
      "utrColor": "lightblue"
    }
  ]
}

Color by an attribute with a jexl expression:

{
  "type": "LinearBasicDisplay",
  "color": "jexl:feature.type=='gene'?'blue':'gray'"
}

Config slots

These slots go on a display entry: "displays": [{ "type": "LinearBasicDisplay", ... }], 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
fetchSizeLimit
number = 5_000_000		Feature (GFF/BED) tracks are light text, and the tabix byte estimate is block-granular (a small region still pulls whole BGZF blocks), so a single gene can trip a tighter gate. A few Mb of feature text downloads fast; the feature-density gate remains the backstop for genuinely over-dense views. An adapter declaring its own fetchSizeLimit outranks this — the generated table in agent-docs/reference/REGION_TOO_LARGE.md § Shared primitives is which ones do, rather than a number restated here that goes stale when theirs moves (CRAM's did).
advanced
showOnlyGenes
boolean = false		Draw only gene-like top-level features, dropping everything else the file carries — the config form of the track menu's "Show only genes". Useful on an NCBI/Ensembl annotation whose non-gene records (regions, match features, biological regions) would otherwise crowd the genes out. ANDed with jexlFilters when both are set.
legend
frozen = []		Explicit color key drawn over the track: an array of { label, color }. A jexl: color expression is a lookup table only its author can read — the drawn feature carries the color but nothing carries what the color MEANS — so the config declares the vocabulary beside the expression that paints it. color is any CSS color and should be the same string the expression returns.

Empty (the default) draws nothing. Dismissable on screen, like every other floating key.
{
  type: 'LinearBasicDisplay',
  color:
    "jexl:{SINE:'#e41a1c',LINE:'#377eb8'}[feature.repClass] || 'gray'",
  legend: [
    { label: 'SINE', color: '#e41a1c' },
    { label: 'LINE', color: '#377eb8' },
  ],
}
Inherited from LinearCanvasBaseDisplay25 slots
maxHeight
number = 1200		Outer clamp in pixels on the content height the "autogrow track height" mode sizes to. Applies to no other mode — fixed and fit keep their configured height and scroll taller content. The autogrow ceiling proper is growMaxHeight, which is lower by default, so this only binds when set below it
advanced
showLegend
maybeBoolean = true promotable		show the display's color key when it has one (the legend slot, or a variant track's consequence-impact / SV-type presets). Unset (the default) follows the session-wide default for this display type, falling back to on; an explicit true/false customizes the track
showLabels
maybeStringEnum (auto, nameAndDescription, name, description, none) = 'auto' promotable		Which label text is drawn beside each feature: "auto" adapts to zoom, dropping descriptions at maxDescriptionFeatureDensity and names at maxLabelFeatureDensity; "nameAndDescription", "name", "description", and "none" pin a choice at every zoom. Unset (the default) follows the session-wide default for this display type, falling back to auto. Replaces the former showLabels on/off enum + showDescriptions boolean pair
maxLabelFeatureDensity
number = 0.2		In "auto" showLabels mode, hide labels when visible feature density (features/pixel) exceeds this value
advanced
maxDescriptionFeatureDensity
number = 0.1		In "auto" showLabels mode, hide descriptions when visible feature density (features/pixel) exceeds this value. Lower than maxLabelFeatureDensity so descriptions drop before names
advanced
color
maybeColor		the main fill color of each feature (a CSS color, or a jexl expression for per-feature coloring). Unset, a feature's own BED itemRgb paints it if it has one, else goldenrod
callback args: feature
connectorColor
maybeColor		color of the connecting/intron lines between feature segments (defaults to the theme text color)
callback args: feature
utrColor
maybeColor		fill color for UTRs on gene/transcript glyphs. Unset, a feature's own BED itemRgb paints them too (matching UCSC's whole-item coloring), else a contrasting blue
callback args: feature
outlineColor
color = ''		outline color for features (empty string = no outline)
featureHeight
number = 10		height in pixels of the main body of each feature
callback args: feature
displayMode
maybeStringEnum (normal, compact, superCompact, collapsed) = 'normal' promotable		Feature height preset. Unset (the default) follows the session-wide default for this display type, falling back to normal; normal/compact/superCompact customize the track explicitly (including customizing normal back over a compact session default); collapsed packs every feature onto a single row with all labels hidden
geneGlyphMode
stringEnum (auto, all, longestCoding) = 'auto'		Gene glyph display mode: "auto" switches based on zoom level, "all" shows all transcripts, "longestCoding" shows one transcript per gene — the one canonicalTranscriptTags names, else the longest coding
subfeatureLabels
maybeStringEnum (none, below, overlay) = 'none' promotable		subfeature label display mode. Unset (the default) follows the session-wide default for this display type, falling back to none; none/below/overlay customize the track explicitly
displayDirectionalChevrons
maybeBoolean = true promotable		Display directional chevrons on intron lines to indicate strand direction. Unset (the default) follows the session-wide default for this display type, falling back to on; an explicit true/false customizes the track (including customizing on over an off session default)
transcriptTypes
stringArray = 
[
    'mRNA',
    'transcript',
    'primary_transcript',
    'V_gene_segment',
    'C_gene_segment',
    'D_gene_segment',
    'J_gene_segment',
  ]
feature types admitted by the gene-only view (showOnlyGenes), plus the fallback for recognizing a CHILDLESS transcript as one of a gene's isoforms. It does not decide which glyph is drawn, whether UTRs are implied, whether a feature can be translated, or — for a transcript with subfeatures, which is nearly all of them — whether it is an isoform or gets a label row. Those are all structural (anything with a direct CDS child is a coding transcript; anything with children of its own takes a row), so org-specific and prokaryotic types render correctly without being listed here.
canonicalTranscriptField
string = 'tag'		feature attribute carrying an isoform's curated "this one represents the gene" tag. NCBI's GFF3 puts RefSeq Select / MANE Select in tag, and so do Ensembl and GENCODE (Ensembl_canonical, MANE_Select) — an annotation that names it somewhere else says so here. GFF3 attribute names reach a feature lowercased.
canonicalTranscriptTags
stringArray = 
[
    'MANE Select',
    'MANE_Select',
    'RefSeq Select',
    'Ensembl_canonical',
    'MANE Plus Clinical',
    'MANE_Plus_Clinical',
  ]
values of that attribute that mark an isoform as the gene's representative one, which is then ranked ahead of every other isoform: it is the transcript shown by longestCoding, and the first kept when auto caps a gene at the rows the track has. Matched case-insensitively, against a multi-valued attribute member-wise (tag=MANE Select,RefSeq Select). Ordered best-first, because a gene can carry two of these at once: MANE Plus Clinical marks an ADDITIONAL transcript beside the MANE Select one and is often the longer, so it sorts last and the coding-length ranking below never gets to break that tie the wrong way. NCBI and Ensembl/GENCODE both emit the MANE tags and spell them differently — spaces in NCBI's GFF3, underscores in GENCODE's — so MANE Select and MANE Plus Clinical are each listed twice. RefSeq Select comes from NCBI alone and Ensembl_canonical from Ensembl/GENCODE alone, so one spelling serves each. Empty turns the whole rule off.
containerTypes
stringArray = ['proteoform_orf']		top-level feature types that always stack their children on separate rows. Container detection is otherwise structural — a feature whose children have children of their own stacks anyway — so this is only needed for a type whose children look like leaves but should still each get a row.
subParts
string = 'CDS,UTR,five_prime_UTR,three_prime_UTR'		subparts for a glyph
impliedUTRs
boolean = true		imply UTRs from exon/CDS differences on transcript glyphs that carry no explicit UTR subfeatures
hideSourceFeatures
boolean = true		hide the GFF3 source record, the whole-molecule type=region feature NCBI RefSeq emits per sequence (gbkey=Src). It spans the entire chromosome and carries only taxon/strain metadata, so it draws as a bar across every window. Set false to draw it. No effect on files that carry no gbkey attribute
labels.name
string = 'jexl:get(feature,'name') || get(feature,'id')'		the primary name of the feature to show
callback args: feature
labels.description
string = 
'jexl:get(feature,'note') || get(feature,'description') || get(feature,'function')'
the text description to show
callback args: feature
heightMode
maybeStringEnum (fixed, grow, fit) = 'fixed' promotable		Track-sizing strategy — how the track responds when there are more features than fit (shared vocabulary with the alignments display, exposed in the "Track sizing" menu). Unset (the default) follows the session-wide default for this display type, falling back to fixed; fixed keeps a scrollable fixed height, grow expands the track to show all features, fit squeezes features to fill the current height. Orthogonal to the per-feature size set by displayMode. Unifies the former autoHeight (grow) + squeezeToDisplayHeight (fit) settings.
growMaxHeight
number = 800		Ceiling in pixels for the "autogrow track height" sizing mode; a track with more content than this grows to the ceiling and scrolls the rest. Does not apply to the fixed or fit modes. Raising it past maxHeight has no effect, since that clamps the content height first
advanced
Inherited from BaseLinearDisplay5 slots
maxFeatureScreenDensity
number = 1		maximum features per pixel before showing a "too many features" message
advanced
height
number = 100		default height for the track
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
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