Tracks

TL;DR: a track is a trackId, a uri and the assemblyNames it sits on; JBrowse reads the track type and adapter off the file's extension. Write type and adapter out when the extension does not say enough, and put appearance settings (color, height, etc.) in a displayDefaults object, which JBrowse routes to the right display.

All tracks can contain:

• trackId - internal track ID, must be unique
• name - displayed track name
• assemblyNames - an array of assembly names a track is associated with, often just a single assemblyName
• category - (optional) array of categories to display in a hierarchical track selector

See the BaseTrack config docs for every slot common to all track types.

File locations in adapter configs use a { "uri": "..." } object. The "locationType": "UriLocation" field is optional for URI locations, and needed only where the type cannot be inferred (e.g. local file paths on desktop).

A complete config.json with one assembly and one BigBed track, showing where a track config sits:

{
  "assemblies": [
    {
      "name": "hg19",
      "uri": "https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz"
    }
  ],
  "tracks": [
    {
      "type": "FeatureTrack",
      "trackId": "repeats_hg19",
      "name": "Repeats",
      "assemblyNames": ["hg19"],
      "category": ["Annotation"],
      "adapter": {
        "type": "BigBedAdapter",
        "uri": "https://jbrowse.org/genomes/hg19/repeats.bb"
      }
    }
  ]
}

Two shorthands keep it short: the assembly is written as just { name, uri } (see assemblies), and the adapter uses the uri shorthand, whose longhand equivalent here is "bigBedLocation": { "uri": "..." }. The track's assemblyNames is what ties it to the hg19 assembly above.

The shortest track#

The same config, with the track written short:

{
  "assemblies": [
    {
      "name": "hg19",
      "uri": "https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz"
    }
  ],
  "tracks": [
    {
      "trackId": "repeats_hg19",
      "uri": "https://jbrowse.org/genomes/hg19/repeats.bb"
    }
  ]
}

The track type and adapter come from the file's extension, the same guess the "Add track" dialog makes (see file types for which extension gives which adapter), the index location is derived as the adapter shorthand derives it, and name defaults to the file name. With one assembly in the config the track is on it; with several, write assemblyNames. Any other key sits beside uri and wins over the guess — name, category, displayDefaults, index for an index that is not at the derived location, or type to pick a track type the extension would not. jbrowse validate accepts the form.

The same entry works in createViewState's tracks, where the component stamps on the assembly it was given, and in a session's sessionTracks, where nothing implies one: a session track written without assemblyNames gets an empty list and belongs to no assembly, so name it there.

Configuring displays#

Appearance settings (color, height, labels, jexl color callbacks, and so on) belong to a track's displays (the different ways a track can be drawn). There are two ways to set them: the displayDefaults object for the common case, or the full displays array when you need precise control.

Shorthand object#

Put your settings in a displayDefaults object and JBrowse applies each one to the display that defines it:

{
  "type": "FeatureTrack",
  "trackId": "repeats_hg19",
  "name": "Repeats",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "BigBedAdapter",
    "uri": "https://jbrowse.org/genomes/hg19/repeats.bb"
  },
  "displayDefaults": { "color": "green", "height": 200 }
}

jbrowse add-track https://jbrowse.org/genomes/hg19/repeats.bb \
  --trackId repeats_hg19 \
  --name Repeats \
  --assemblyNames hg19 \
  --displayDefaults '{"color":"green","height":200}'

A setting goes to every display whose config schema has a slot by that name. Displays drawn differently usually name their slots differently, so each setting lands on the display it belongs to: a VariantTrack colors its linear display with color and its circular (chord) display with strokeColor, both in the same object.

{
  "type": "VariantTrack",
  "trackId": "variants_hg19",
  "name": "Variants",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/file.vcf.gz"
  },
  "displayDefaults": { "color": "green", "strokeColor": "red" }
}

jbrowse add-track https://yourhost/file.vcf.gz \
  --trackId variants_hg19 \
  --name Variants \
  --assemblyNames hg19 \
  --displayDefaults '{"color":"green","strokeColor":"red"}'

Where a name is shared, the setting reaches all of them: height in displayDefaults sets the height of every display the track has. A setting no display defines is ignored, with a console warning so typos show up.

Full array#

For precise control (giving two displays different values for the same setting, choosing which display is the default, or setting an explicit displayId), pass displays as an array. Each entry names a display type; displayId is optional and defaults to {trackId}-{displayType}. The two forms combine, and an explicit entry wins over displayDefaults for any setting it names itself.

{
  "type": "FeatureTrack",
  "trackId": "repeats_hg19",
  "name": "Repeats",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "BigBedAdapter",
    "uri": "https://jbrowse.org/genomes/hg19/repeats.bb"
  },
  "displays": [
    {
      "type": "LinearBasicDisplay",
      "height": 200,
      "color": "jexl:feature.strand==1?'blue':'red'"
    }
  ]
}

The display types available, grouped by the track type they attach to. Most tracks can be drawn more than one way, and the displays array picks which:

See the config guides for per-track display options.

Copying a track's config out of the app#

To get the raw JSON of a track you configured in the app:

• Copy track: in the track menu (the dropdown on the track label), choose "Copy track" to copy the track's full config JSON. "Copy and open track" does the same and immediately opens the copy in the current view.
• Settings: also in the track menu, "Settings" opens the configuration editor for that track, where you can review and copy every slot's current value. Any user can do this: a non-admin's edits become a per-session override rather than changes to the shared config.json, and "Reset track settings" clears it.

Either way the result pastes into config.json or into a generation script.

The "Zoom in to see more features" limits#

Two limits guard the region, and either one shows the message: how many bytes the fetch would download, and how many features would land on screen.

The message itself is "Zoom in to see features or force load (may be slow)", usually with the estimated size that tripped it, and the banner's Force load button downloads the region anyway.

On alignments and MAF tracks the message can appear at any zoom, and there it offers only Force load. Those two formats cost bytes per reference base times something zooming does not reduce — read depth, and the number of aligned species — so a gene-sized window over a deep pileup or a 470-way alignment is still tens of megabytes. Other tracks stop being guarded below about 20 kb, where a small region is a small download.

Raising the feature limit#

maxFeatureScreenDensity is features per pixel of track width, and it defaults to 1. So the feature count a track will draw is roughly the width of your browser window in pixels: about 1,500 features on a 1,500px-wide window. Doubling the slot to 2 allows about 3,000, and so on. It is a density because the same region drawn in a wider window has more room, so the budget grows with the window.

{
  "type": "FeatureTrack",
  "trackId": "dense_genes",
  "name": "Genes",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": { "maxFeatureScreenDensity": 5 }
}

jbrowse add-track volvox.sort.gff3.gz \
  --trackId dense_genes \
  --name Genes \
  --assemblyNames volvox \
  --displayDefaults '{"maxFeatureScreenDensity":5}' \
  --load copy

If you only want the region loaded once, the Force load button does that without touching the config. To force it without a click (an embedded view, a notebook, a screenshot, where nobody can press the button), set forceLoad on the display.

Raising the byte limit#

fetchSizeLimit is a plain byte count. Regions under 20kb are never held back, and adapters that summarize at screen resolution (bigWig, Hi-C, MultiWiggle, sequence) are never too large, so neither limit applies to them.

The BAM, CRAM and VCF adapters have their own fetchSizeLimit, and an adapter's limit takes priority over the display's, so for those formats set it on the adapter:

{
  "type": "AlignmentsTrack",
  "trackId": "volvox_cram",
  "name": "volvox CRAM (small fetch size limit)",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "CramAdapter",
    "uri": "volvox-sorted.cram",
    "fetchSizeLimit": 1000
  }
}

jbrowse add-track-json '{
  "type": "AlignmentsTrack",
  "trackId": "volvox_cram",
  "name": "volvox CRAM (small fetch size limit)",
  "assemblyNames": ["volvox"],
  "adapter": {
    "type": "CramAdapter",
    "uri": "volvox-sorted.cram",
    "fetchSizeLimit": 1000
  }
}'

Finding every option for a track or adapter type#

The config guides cover common settings. Every slot for every track, display, and adapter type is in the auto-generated config reference, built from source. For example:

• BamAdapter, VcfTabixAdapter, BigWigAdapter
• LinearAlignmentsDisplay, LinearWiggleDisplay

The full set of pages is in the Config reference section of the docs sidebar.

See also#

• Supported file types
• Hierarchical track selector
• Deploying JBrowse Web
• Display settings