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.

A complete config.json with one assembly and one BigBed track, showing where a track 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"
      }
    }
  ]
}

• trackId is the unique id every session and link names the track by; assemblyNames ties it to the assembly above; category nests it in the track selector. Every slot common to all track types is on the BaseTrack config docs.
• The adapter uses the uri shorthand (longhand here: "bigBedLocation": { "uri": "..." }). A { "uri": "..." } location needs "locationType" only where the type cannot be inferred, such as a local file path on desktop.

The shortest track#

The same 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 type, adapter and index location come from the extension, the same guess the "Add track" dialog makes, name defaults to the file name, and a config with one assembly supplies assemblyNames. Any key written beside uri wins over the guess (the whole-track shorthand lists the extensions). Two places imply no assembly: a session's sessionTracks, where a track without assemblyNames belongs to nothing, and a config with several assemblies. Name it there.

Configuring displays#

Appearance settings belong to a track's displays, the ways a track can be drawn. A displayDefaults object routes each setting to every display whose schema has a slot by that name:

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

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

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

• Differently named slots land on different displays. color reaches the linear display and strokeColor the circular (chord) one.
• A shared name reaches every display. height sets all of them.
• A name no display defines is ignored, with a console warning so typos show up.

A displays array gives precise control: two displays with different values for one setting, a non-default display type, or an explicit displayId (default {trackId}-{displayType}). An 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'"
    }
  ]
}

jbrowse add-track-json '{
  "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'\''"
    }
  ]
}'

{
  "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, grouped by the track type they attach to:

Copying a track's config out of the app#

• Copy track in the track menu copies the track's full config JSON; "Copy and open track" also opens the copy in the current view.
• Settings in the same menu opens the configuration editor, where every slot's current value can be read off. A non-admin's edits become a per-session override of the shared config.json, and "Reset track settings" clears it.

The "Zoom in to see more features" limits#

Two limits guard a region, and either one shows "Zoom in to see features or force load (may be slow)" with a Force load button: the bytes the fetch would download, and the features that would land on screen. Regions under about 20 kb are never held back, and adapters that summarize at screen resolution (bigWig, Hi-C, MultiWiggle, sequence) are never too large.

Alignments and MAF tracks are the exception: their cost per reference base scales with read depth or with the number of aligned species, which zooming does not reduce, so the message can appear at any zoom and offers only Force load.

Raising the feature limit#

maxFeatureScreenDensity is features per pixel of track width, 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

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

Where nobody can press the button (an embedded view, a notebook, a screenshot), forceLoad on the display loads the region regardless.

Raising the byte limit#

fetchSizeLimit is a byte count. The BAM, CRAM and VCF adapters carry their own fetchSizeLimit, which 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
  }
}'

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

See also#

• Supported file types
• Hierarchical track selector
• Deploying JBrowse Web
• Display settings
• Config reference, every slot of every track, display and adapter type