Grouping and lane order
Several unrelated-looking track settings — a gene track's biotype sections, an
alignments track's haplotype bands, a multi-sample variant track's karyotype
rows, a multiway synteny track's lanes, a multi-row display's partitions — use
the same two ideas: a field (or, for multiway synteny, the assembly itself)
splits the data into sections, and a sort list decides which section draws
first. This page is the shared mechanism; each example below links to the guide
or tutorial it is worked through in full.
field and sort
Most of these displays take a facet object: { field, sort }. field is a
feature attribute, a dotted path into a structured one (INFO.SVTYPE), or a
jexl: expression — each distinct value it returns makes one section. sort is
a list of values: the ones it names stack first, in that order, and every other
value found in the data follows, sorted. A value in sort that the data never
produces is never drawn, because sort orders sections and does not create
them. Naming one ahead of time therefore adds no refetch when it later appears.
A rows.sort orders a display's rows by the same rule, with one difference:
rows a source lists, such as a VCF's samples or a multi-BigWig's subtracks, keep
the source's order past the sort list rather than sorting.
A short form exists for the common case of no ordering: "facet": "tags.HP" is
"facet": { "field": "tags.HP", "sort": [] }.
Feature tracks
NCBI RefSeq genes on hg38, grouped and colored by gene_biotype, with the
protein-coding section pinned to the top and each biotype given a distinct color
from the same list:
{
"facet": {
"field": "gene_biotype",
"sort": ["protein_coding", "snoRNA", "lncRNA", "pseudogene"]
},
"encoding": {
"color": {
"field": "gene_biotype",
"scale": {
"domain": ["protein_coding", "snoRNA", "lncRNA", "pseudogene"]
}
}
}
}The gene track guide's Grouping features into sections section has the full mechanism — the Group by/Color by menus, the draggable chips, and what Edit plot... accepts.
Alignments tracks
The alignments displays take facet the same way, plus a handful of read
dimensions no attribute expresses — strand, firstOfPairStrand,
pairOrientation, pairing, split, spliced, mapq. The same idea over a
LinearMarkDisplay faceting a BAM by its HP haplotype tag:
The cookbook's alignments recipe has a
worked LinearAlignmentsDisplay config; the reordering rule is the same sort.
Variant tracks
LinearVariantDisplay takes the same facet object to band rows by a metadata
column instead of VCF file order. Bands are what makes two biologically
meaningful examples readable rather than a wall of samples in whatever order the
VCF lists them:
"facet": { "field": "karyotype", "sort": ["Standard", "In(2L)t"] }"facet": { "field": "karyotype", "sort": ["2L+a/2L+a", "2La/2L+a", "2La/2La"] }The order in each case is a genetics decision, not an alphabetical one: dosage
order in the mosquito figure, standard-before-inverted in the fly figure, both
read off the sort lists above.
LD in mosquitoes
works through the mosquito one, and
population genomics
reads the fly inversion as diversity in each arrangement.
The mark display
LinearMarkDisplay takes the same facet object, and separately, a row
channel that packs features within a section (a BAM's pileup, or any mark whose
transform runs a pileup step). Faceting and row-packing are independent — a
facet splits into sections first, and each mark packs rows inside each section:
The mark display guide's Facets section
has the full mechanism, including how the track menu's Sections list writes
a drag back into sort.
Multiway synteny
MultiWaySyntenyDisplay draws one lane per assembly rather than one section per
field value, so there is no facet — its rows is the lane arrangement, and
rows.sort lists assembly names. It composes with ribbons.encoding.color,
which paints each ribbon by a field — here, the relative strand between the two
lanes a ribbon joins:
Goes in the tracks array of config.json. See Tracks.
{
"type": "SyntenyTrack",
"trackId": "grape_peach_cacao_blocks",
"name": "Grape vs peach, cacao, arabidopsis, poplar, tomato, citrus (MCScan blocks)",
"assemblyNames": [
"grape",
"peach",
"cacao",
"poplar",
"citrus",
"arabidopsis",
"tomato"
],
"adapter": {
"type": "MCScanBlocksAdapter",
"uri": "grape_peach_cacao.blocks",
"blockAssemblies": [
"grape",
"peach",
"cacao",
"poplar",
"citrus",
"arabidopsis",
"tomato"
],
"bedLocations": [
"grape.bed",
"peach.bed",
"cacao.bed",
"poplar.bed",
"citrus.bed",
"arabidopsis.bed",
"tomato.bed"
]
},
"displays": [
{
"type": "MultiWaySyntenyDisplay",
"displayId": "grape_peach_cacao_blocks-MultiWaySyntenyDisplay",
"rows": {
"sort": ["peach", "cacao", "poplar", "citrus", "arabidopsis", "tomato"]
},
"ribbons": { "encoding": { "color": "strand" } }
}
]
}jbrowse add-track-json '{
"type": "SyntenyTrack",
"trackId": "grape_peach_cacao_blocks",
"name": "Grape vs peach, cacao, arabidopsis, poplar, tomato, citrus (MCScan blocks)",
"assemblyNames": [
"grape",
"peach",
"cacao",
"poplar",
"citrus",
"arabidopsis",
"tomato"
],
"adapter": {
"type": "MCScanBlocksAdapter",
"uri": "grape_peach_cacao.blocks",
"blockAssemblies": [
"grape",
"peach",
"cacao",
"poplar",
"citrus",
"arabidopsis",
"tomato"
],
"bedLocations": [
"grape.bed",
"peach.bed",
"cacao.bed",
"poplar.bed",
"citrus.bed",
"arabidopsis.bed",
"tomato.bed"
]
},
"displays": [
{
"type": "MultiWaySyntenyDisplay",
"displayId": "grape_peach_cacao_blocks-MultiWaySyntenyDisplay",
"rows": {
"sort": ["peach", "cacao", "poplar", "citrus", "arabidopsis", "tomato"]
},
"ribbons": { "encoding": { "color": "strand" } }
}
]
}'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": "SyntenyTrack",
"trackId": "grape_peach_cacao_blocks",
"name": "Grape vs peach, cacao, arabidopsis, poplar, tomato, citrus (MCScan blocks)",
"assemblyNames": [
"grape",
"peach",
"cacao",
"poplar",
"citrus",
"arabidopsis",
"tomato"
],
"adapter": {
"type": "MCScanBlocksAdapter",
"uri": "grape_peach_cacao.blocks",
"blockAssemblies": [
"grape",
"peach",
"cacao",
"poplar",
"citrus",
"arabidopsis",
"tomato"
],
"bedLocations": [
"grape.bed",
"peach.bed",
"cacao.bed",
"poplar.bed",
"citrus.bed",
"arabidopsis.bed",
"tomato.bed"
]
},
"displays": [
{
"type": "MultiWaySyntenyDisplay",
"displayId": "grape_peach_cacao_blocks-MultiWaySyntenyDisplay",
"rows": {
"sort": ["peach", "cacao", "poplar", "citrus", "arabidopsis", "tomato"]
},
"ribbons": { "encoding": { "color": "strand" } }
}
]
}grape_peach_cacao.blocks, grape.bed, peach.bed, cacao.bed, poplar.bed, citrus.bed, arabidopsis.bed, tomato.bed are relative to a config.json. Replace each with its URL or its path on this computer.
That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.
Unlisted assemblies still get a lane — they stack below the named ones, densest-first, so a ribbon chain through them is cut as late as possible. The synteny track guide covers the adapter side, and the multi-way synteny display guide the lane controls in the app.
Row-partitioned tracks
LinearMultiRowFeatureDisplay fixes one row per value rather than a foldable
section — no chip, no hide, no overflow merge — through rows instead of
facet, with the same sort. Nine ENCODE cell types, pinned to ENCODE's own
tiers rather than alphabetical order:
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "broad_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Broad ENCODE, 9 cell types)",
"uri": "wgEncodeBroadHmm.multirow.bed.gz",
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": {
"field": "cellType",
"sort": [
"GM12878",
"H1-hESC",
"K562",
"HepG2",
"HUVEC",
"HMEC",
"HSMM",
"NHEK",
"NHLF"
]
},
"height": 200
}
]
}jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "broad_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Broad ENCODE, 9 cell types)",
"uri": "wgEncodeBroadHmm.multirow.bed.gz",
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": {
"field": "cellType",
"sort": [
"GM12878",
"H1-hESC",
"K562",
"HepG2",
"HUVEC",
"HMEC",
"HSMM",
"NHEK",
"NHLF"
]
},
"height": 200
}
]
}'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": "broad_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Broad ENCODE, 9 cell types)",
"uri": "wgEncodeBroadHmm.multirow.bed.gz",
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": {
"field": "cellType",
"sort": [
"GM12878",
"H1-hESC",
"K562",
"HepG2",
"HUVEC",
"HMEC",
"HSMM",
"NHEK",
"NHLF"
]
},
"height": 200
}
]
}wgEncodeBroadHmm.multirow.bed.gz is relative to a config.json. Replace it with its URL or its path on this computer.
At a larger scale, a rows.sort of six names with rows.kept narrows a
127-epigenome track to the three tissues a figure is about, in the order the
comparison reads:
The ChromHMM tutorial
has both tracks in full, plus what an unset rows.sort does instead: Cluster
rows by similarity... derives a row order from the data itself.
Reordering at runtime
Every one of these displays writes a drag-to-reorder back into the same sort
slot it read the curated order from — the gene track and mark display's
Sections list, the alignments track menu's group-by sections, multiway
synteny's Lanes menu and lane-header drag, and the multi-row display's row
drag, which writes rows.sort. A session saved after reordering records the new
order in config.json terms, not as separate runtime-only state.
See also
- Tutorial: Synteny from an ortholog table (grape, peach, cacao)
- Tutorial: Pangenome (HPRC) part 2: haplotypes against each other
- Tutorial: ChromHMM chromatin states
- Tutorial: Selection scans (Drosophila DGRP)
- Tutorial: LD across an inversion (mosquitoes)
- User guide: Gene track
- Config guide: Mark display
- Config guide: Alignments track
- Config guide: Synteny track
- Reference: LinearVariantDisplay
- Reference: LinearMultiRowFeatureDisplay
- Reference: MultiWaySyntenyDisplay