# 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:

```json
{
  "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](https://jbrowse.org/jb2/docs/config_guides/track_selector). Every slot common to all
  track types is on the [BaseTrack config docs](https://jbrowse.org/jb2/docs/config/basetrack).
- The adapter uses the
  [`uri` shorthand](https://jbrowse.org/jb2/docs/config_guides/file_types#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:

```json
{
  "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](https://jbrowse.org/jb2/docs/config_guides/file_types#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:

```json addtrack
{
  "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.

```json addtrack
{
  "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:

<!-- DISPLAY_TYPES START -->

<!-- prettier-ignore -->
| Track type | Display types |
| --- | --- |
| [](https://jbrowse.org/jb2/docs/config/alignmentstrack) | [](https://jbrowse.org/jb2/docs/config/linearalignmentsdisplay) |
| [](https://jbrowse.org/jb2/docs/config/featuretrack) | [](https://jbrowse.org/jb2/docs/config/lineararcdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearbasicdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearmultirowfeaturedisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearscoredisplay) |
| [](https://jbrowse.org/jb2/docs/config/gccontenttrack) | [](https://jbrowse.org/jb2/docs/config/lineargccontenttrackdisplay) |
| [](https://jbrowse.org/jb2/docs/config/gwastrack) | [](https://jbrowse.org/jb2/docs/config/linearmanhattandisplay) |
| [](https://jbrowse.org/jb2/docs/config/hictrack) | [](https://jbrowse.org/jb2/docs/config/linearhicdisplay) |
| [](https://jbrowse.org/jb2/docs/config/ldtrack) | [](https://jbrowse.org/jb2/docs/config/ldtrackdisplay) |
| [](https://jbrowse.org/jb2/docs/config/maftrack) | [](https://jbrowse.org/jb2/docs/config/linearmafdisplay) |
| [](https://jbrowse.org/jb2/docs/config/multiquantitativetrack) | [](https://jbrowse.org/jb2/docs/config/multilinearwiggledisplay) |
| [](https://jbrowse.org/jb2/docs/config/quantitativetrack) | [](https://jbrowse.org/jb2/docs/config/linearwiggledisplay) |
| [](https://jbrowse.org/jb2/docs/config/referencesequencetrack) | [](https://jbrowse.org/jb2/docs/config/lineargccontentdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearreferencesequencedisplay) |
| [](https://jbrowse.org/jb2/docs/config/syntenytrack) | [](https://jbrowse.org/jb2/docs/config/dotplotdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/lgvsyntenydisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearsyntenydisplay)<br/>[](https://jbrowse.org/jb2/docs/config/multiwaysyntenydisplay) |
| [](https://jbrowse.org/jb2/docs/config/varianttrack) | [](https://jbrowse.org/jb2/docs/config/chordvariantdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/lddisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearmultisamplevariantdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearmultisamplevariantmatrixdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearpairedarcdisplay)<br/>[](https://jbrowse.org/jb2/docs/config/linearvariantdisplay) |

<!-- DISPLAY_TYPES END -->

## 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`](https://jbrowse.org/jb2/docs/config/linearcanvasbasedisplay/#slot-maxfeaturescreendensity)
is features per pixel of track width, so the budget grows with the window:

```json addtrack
{
  "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`](https://jbrowse.org/jb2/docs/config/baselineardisplay/#slot-forceload) on the display
loads the region regardless.

### Raising the byte limit

[`fetchSizeLimit`](https://jbrowse.org/jb2/docs/config/baselineardisplay/#slot-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:

```json addtrack
{
  "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

- [](https://jbrowse.org/jb2/docs/config_guides/file_types)
- [](https://jbrowse.org/jb2/docs/config_guides/track_selector)
- [](https://jbrowse.org/jb2/docs/config_guides/deploying#generating-configjson-from-a-script)
- [](https://jbrowse.org/jb2/docs/tutorials/display_settings)
- [Config reference](https://jbrowse.org/jb2/docs/config), every slot of every track, display and
  adapter type