Skip to main content

Settings every track shares

A track's appearance is set by a few objects that mean the same thing on every track type. encoding.color says how features are colored, encoding.y how a value is plotted, facet how features split into sections, rows how a row display orders and labels its rows, and filter which features are drawn. They follow the grammar of graphics as Vega-Lite spells it, so a color written for a gene track is written the same way for reads or variants, and the track menu, the legend, "Edit plot..." and a share link all read and write the same object.

SettingSays
encoding.colorunset, one constant color, or a field painted through a scale, with its key
encoding.ythe plotted field, its scale, its axis and any fixed reference lines
facetthe field that splits features into sections, and the order of the sections
rowsa row display's rows: which field names them, their order, labels and colors
filtera list of tests on fields; a feature failing any test is not drawn
markson the mark display, the layers it draws

Each display's page in the config reference lists which of these it takes, and which members of each.

Color

encoding.color is in one of three states. Unset, the track paints its own default. A value paints every feature one color. A field paints each feature by its value through a scale, and the track's key comes from the same object. A bare field name is short for { "field": … }. The same threshold object reads mapping quality on reads and score on genes:

Goes in the tracks array of config.json. See Tracks.

{
  "type": "AlignmentsTrack",
  "trackId": "reads_by_mapq",
  "name": "Reads (low MAPQ grey)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "mapq",
        "scale": {
          "type": "threshold",
          "domain": [20],
          "range": ["#bbbbbb", "#0068d1"]
        }
      }
    }
  }
}
jbrowse add-track volvox-sorted.bam \
  --trackId reads_by_mapq \
  --name "Reads (low MAPQ grey)" \
  --assemblyNames volvox \
  --displayDefaults '{"encoding":{"color":{"field":"mapq","scale":{"type":"threshold","domain":[20],"range":["#bbbbbb","#0068d1"]}}}}' \
  --load copy

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:

{
  "type": "AlignmentsTrack",
  "trackId": "reads_by_mapq",
  "name": "Reads (low MAPQ grey)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "mapq",
        "scale": {
          "type": "threshold",
          "domain": [20],
          "range": ["#bbbbbb", "#0068d1"]
        }
      }
    }
  }
}

volvox-sorted.bam is relative to a config.json. Replace it with its URL or its path on this computer.

Goes in the tracks array of config.json. See Tracks.

{
  "type": "FeatureTrack",
  "trackId": "genes_by_score",
  "name": "Genes (low score grey)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "score",
        "scale": {
          "type": "threshold",
          "domain": [20],
          "range": ["#bbbbbb", "#0068d1"]
        }
      }
    }
  }
}
jbrowse add-track volvox.sort.gff3.gz \
  --trackId genes_by_score \
  --name "Genes (low score grey)" \
  --assemblyNames volvox \
  --displayDefaults '{"encoding":{"color":{"field":"score","scale":{"type":"threshold","domain":[20],"range":["#bbbbbb","#0068d1"]}}}}' \
  --load copy

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:

{
  "type": "FeatureTrack",
  "trackId": "genes_by_score",
  "name": "Genes (low score grey)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "Gff3TabixAdapter", "uri": "volvox.sort.gff3.gz" },
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "score",
        "scale": {
          "type": "threshold",
          "domain": [20],
          "range": ["#bbbbbb", "#0068d1"]
        }
      }
    }
  }
}

volvox.sort.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

The recipes for each form (a color per value, chosen colors, a gradient, a file's own colors) are in the cookbook.

Value scale

encoding.y.scale sets how a plotted value maps to height: its type (linear, log or symlog), and domainMin and domainMax to pin its ends, which otherwise follow the loaded data. A display has one value scale, shared by everything it plots and read by its axis. Config guide: Quantitative track covers it in full.

Facet

facet names the field whose values split features into sections, and its sort list names the sections that stack first. A sort orders sections and never creates them. Grouping and lane order works it through on gene, alignments, variant and synteny tracks.

Rows

A row display, such as a multi-sample variant track or a multi-signal quantitative track, describes its rows in one rows object: the field that names them, their sort, their labels, a clustering tree, a row color read off sample metadata, and step, the row height or "fit". The variant track guide shows rows read from a sample sheet.

Filter

filter is a list of tests, each naming a field and one of equal, oneOf, lt, lte, gt, gte or valid. A feature is drawn when it passes every test. A jexl: string is accepted for a test no field states, and runs slower:

Goes in the tracks array of config.json. See Tracks.

{
  "type": "AlignmentsTrack",
  "trackId": "reads_mapq20",
  "name": "Reads (MAPQ 20 and up)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "filter": [{ "field": "mapq", "gte": 20 }]
  }
}
jbrowse add-track volvox-sorted.bam \
  --trackId reads_mapq20 \
  --name "Reads (MAPQ 20 and up)" \
  --assemblyNames volvox \
  --displayDefaults '{"filter":[{"field":"mapq","gte":20}]}' \
  --load copy

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add track from pasted JSON, and paste:

{
  "type": "AlignmentsTrack",
  "trackId": "reads_mapq20",
  "name": "Reads (MAPQ 20 and up)",
  "assemblyNames": ["volvox"],
  "adapter": { "type": "BamAdapter", "uri": "volvox-sorted.bam" },
  "displayDefaults": {
    "filter": [{ "field": "mapq", "gte": 20 }]
  }
}

volvox-sorted.bam is relative to a config.json. Replace it with its URL or its path on this computer.

Editing the settings in the app

The track menu's Advanced → Edit plot... shows a track's grammar settings as JSON, the same objects a config writes, with worked examples to start from. The Color by and Group by menus write the same encoding.color and facet objects, so an edit made from a menu reads back in Edit plot, survives a reload and travels in a share link.

For plugin developers

A display joins this vocabulary by reading these objects through the shared code rather than spelling its own settings. The grammar, stage by stage names the code behind each object, and the grammar of graphics spec the features declined so far.