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 — read
the same two ideas: a field (or, for multiway synteny, the assembly itself)
decides what gets its own section, and a domain 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 domain
Most of these displays take a facet object: { field, domain }. field is a
feature attribute, a dotted path into a structured one (INFO.SVTYPE), or a
jexl: expression — whatever value it returns gets its own section. domain 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 domain that the data never
produces is simply never drawn — domain orders sections, it does not create
them, so naming one ahead of time costs nothing and refetches nothing when it
later appears.
A short form exists for the common case of no ordering: "facet": "tags.HP" is
"facet": { "field": "tags.HP", "domain": [] }.
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 domain:
{
"facet": {
"field": "gene_biotype",
"domain": ["protein_coding", "snoRNA", "lncRNA", "pseudogene"]
},
"color": {
"field": "gene_biotype",
"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 dialogs, the Sections menu, and what Edit as JSON... accepts.
Alignments tracks
The alignments displays take facet the same way, plus a handful of read
dimensions no attribute expresses — strand, firstOfPairStrand,
pairOrientation, splitRead, 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
domain.
Variant tracks
LinearMultiSampleVariantDisplay 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", "domain": ["Standard", "In(2L)t"] }"facet": { "field": "karyotype", "domain": ["2L+a/2L+a", "2La/2L+a", "2La/2La"] }The domain in each case is a genetics decision, not an alphabetical one: dosage order in the mosquito figure, standard-before-carrier in the fly figure, both read straight off the figure's caption. Population genomics and LD in mosquitoes work through both.
The mark display
LinearMarkDisplay takes the same facet object, and separately, a row
channel that packs features within a section (a BAM's own 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 its own
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 domain.
Multiway synteny
MultiWaySyntenyDisplay draws one lane per assembly rather than one section per
field value, so there is no facet — domain sits directly on the display and
lists assembly names. It composes with ribbonColor, which paints each ribbon
by a field of its own — here, the relative strand between the two lanes a ribbon
joins:
{
"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": [
{ "uri": "grape.bed" },
{ "uri": "peach.bed" },
{ "uri": "cacao.bed" },
{ "uri": "poplar.bed" },
{ "uri": "citrus.bed" },
{ "uri": "arabidopsis.bed" },
{ "uri": "tomato.bed" }
]
},
"displays": [
{
"type": "MultiWaySyntenyDisplay",
"displayId": "grape_peach_cacao_blocks-MultiWaySyntenyDisplay",
"domain": ["peach", "cacao", "poplar", "citrus", "arabidopsis", "tomato"],
"ribbonColor": { "field": "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": [
{ "uri": "grape.bed" },
{ "uri": "peach.bed" },
{ "uri": "cacao.bed" },
{ "uri": "poplar.bed" },
{ "uri": "citrus.bed" },
{ "uri": "arabidopsis.bed" },
{ "uri": "tomato.bed" }
]
},
"displays": [
{
"type": "MultiWaySyntenyDisplay",
"displayId": "grape_peach_cacao_blocks-MultiWaySyntenyDisplay",
"domain": ["peach", "cacao", "poplar", "citrus", "arabidopsis", "tomato"],
"ribbonColor": { "field": "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": [
{ "uri": "grape.bed" },
{ "uri": "peach.bed" },
{ "uri": "cacao.bed" },
{ "uri": "poplar.bed" },
{ "uri": "citrus.bed" },
{ "uri": "arabidopsis.bed" },
{ "uri": "tomato.bed" }
]
},
"displays": [
{
"type": "MultiWaySyntenyDisplay",
"displayId": "grape_peach_cacao_blocks-MultiWaySyntenyDisplay",
"domain": ["peach", "cacao", "poplar", "citrus", "arabidopsis", "tomato"],
"ribbonColor": { "field": "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.
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 grape/peach/cacao tutorial works through picking the lane order itself.
Row-partitioned tracks
LinearMultiRowFeatureDisplay fixes one row per value rather than a foldable
section — no chip, no hide, no overflow merge — through partitionField instead
of facet, with the same domain. Nine ENCODE cell types, pinned to ENCODE's
own tiers rather than alphabetical order:
{
"type": "FeatureTrack",
"trackId": "broad_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Broad ENCODE, 9 cell types)",
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"adapter": {
"type": "BedTabixAdapter",
"uri": "wgEncodeBroadHmm.multirow.bed.gz"
},
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"partitionField": "cellType",
"domain": [
"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)",
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"adapter": {
"type": "BedTabixAdapter",
"uri": "wgEncodeBroadHmm.multirow.bed.gz"
},
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"partitionField": "cellType",
"domain": [
"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)",
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"adapter": {
"type": "BedTabixAdapter",
"uri": "wgEncodeBroadHmm.multirow.bed.gz"
},
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"partitionField": "cellType",
"domain": [
"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.
The same mechanism at a larger scale — a domain of six names narrowing a
127-epigenome track to the three tissues a figure is actually about, in the
order the comparison reads:
The ChromHMM tutorial
has both tracks in full, plus what an unset domain 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 domain
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. A session saved after reordering carries the new order in config.json
terms, not as separate runtime-only state.
See also
- Gene track
- Mark display
- Config guide: Alignments track
- Synteny track
- LinearMultiSampleVariantDisplay
- LinearMultiRowFeatureDisplay
- MultiWaySyntenyDisplay
- Synteny from an ortholog table (grape, peach, cacao)
- Synteny from a pangenome graph (eight HPRC haplotypes)
- ChromHMM chromatin states
- Selection scans (Drosophila DGRP)
- LD across an inversion (mosquitoes)