Multi-row feature track
The multi-row feature display splits one interval file into a stack of labeled rows, one per value of a column you nominate, and paints each feature as a colored block. A cohort of per-sample interval data (chromatin states per cell type, copy number per tumor, ancestry per haplotype, genotype per strain) becomes a single track with one config, one adapter, and one fetch.
Any BED, BigBed, GFF3, or GTF track can be switched to it from the track menu:
Display types → Multi-row display. It draws the features as a plot of marks,
a rect per feature, so
Advanced → Edit plot... and Edit marks...
reach every mark, scale, filter and facet setting.
Turning a feature track into rows
A track whose config names no rows takes a row per feature type: a GFF3's
gene, mRNA and pseudogene, a ClinVar bigBed's variant types. A window
holding one type shows one labelled row. A RepeatMasker table has no type, so
its track opens in one row; pick repClass in the One row per picker for a
labelled row per repeat class.
- No value: where the features in view have no value for the row field (no
type, as a plain BED's or a RepeatMasker table's), the display draws every feature in one row and opens One row per once; a One row per... chip at the head of the track brings it back - Track menu: One row per offers Type, the default,
Attribute..., which opens the picker, and None (one row), which writes
rows: ""so the default does not come back - Repartitioning: a saved row order, its labels and colors, and a clustering run are kept by row value, so they apply to no row under a new partition and apply again when the field comes back
To fix the column in config, set
rows in the track
config:
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "chromhmm",
"name": "ChromHMM states",
"uri": "https://example.com/chromhmm.bed.gz",
"assemblyNames": ["hg19"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType"
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "chromhmm",
"name": "ChromHMM states",
"uri": "https://example.com/chromhmm.bed.gz",
"assemblyNames": ["hg19"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType"
}
]
}'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": "chromhmm",
"name": "ChromHMM states",
"uri": "https://example.com/chromhmm.bed.gz",
"assemblyNames": ["hg19"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType"
}
]
}rows names the feature attribute whose value assigns a feature to a row.
Features sharing a value stack into the same row, and the value becomes the row
label. rows: { "field": "cellType", ... } is the same as rows: "cellType",
and rows: "" is one row.
The plot is a rect per feature, spanning the whole feature. Advanced → Edit
plot... offers two other plots as examples: a BED12 row's or a transcript's
blocks joined by a line, as a gene track draws exons, where a hover or a click
on any block reports the whole feature; and a transcript drawn with its protein
domains over its coding exons, as Protein domains on gene models writes it.
Hovering a feature names it on the tooltip's first line, above its locus and
row: its name, else its ID. The
tooltip field points it at another
attribute, "tooltip": "_mouseOver" for a UCSC track's hover text.
The rows come from the values of the features in the window and follow it as it pans, so a file that gains a sample or a category needs no config change, and a window missing one has no row for it.
Partitioning with a jexl expression
A file can have the category without a column for it, in which case rows takes
a jexl expression instead of an attribute name.
UCSC's bigRmskBed is the common case: the repeat class is a suffix on the name
(L1HS#LINE/L1), so an attribute lookup splits on the full repeat name, which
is thousands of rows rather than twenty.
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "genark_rmsk",
"name": "RepeatMasker by class",
"uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/019/238/085/GCF_019238085.1/bbi/GCF_019238085.1_USGS_WTPT01.rmsk.bb",
"assemblyNames": ["GCF_019238085.1"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "jexl:split(split(feature.name,'#')[1],'/')[0]"
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "genark_rmsk",
"name": "RepeatMasker by class",
"uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/019/238/085/GCF_019238085.1/bbi/GCF_019238085.1_USGS_WTPT01.rmsk.bb",
"assemblyNames": ["GCF_019238085.1"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "jexl:split(split(feature.name,'\''#'\'')[1],'\''/'\'')[0]"
}
]
}'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": "genark_rmsk",
"name": "RepeatMasker by class",
"uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/019/238/085/GCF_019238085.1/bbi/GCF_019238085.1_USGS_WTPT01.rmsk.bb",
"assemblyNames": ["GCF_019238085.1"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "jexl:split(split(feature.name,'#')[1],'/')[0]"
}
]
}The final [0] selects class; swap it for [1] to split by family.
The multi-row display isn't the track's default, so it needs an explicit
displays entry rather than the displayDefaults shorthand (whose
encoding.color would also reach the default display).
Preparing the file
The input is one file holding every sample's intervals, with a column naming the
sample. For BED, name the columns with a #-prefixed header line so the adapter
picks them up, then bgzip and tabix as usual:
#chrom chromStart chromEnd name score strand thickStart thickEnd itemRgb cellType
chr1 10000 10600 15_Repetitive/CNV 0 . 10000 10600 245,245,245 GM12878
chr1 10000 10600 15_Repetitive/CNV 0 . 10000 10600 245,245,245 K562Any extra column works the same way, so rows can be sample, cellType,
strain, haplotype, or whatever you called it. A GFF3/GTF attribute or BigBed
extra field works by name.
Coloring the blocks
The blocks take the first of these that names a color:
encoding.color, a per-feature fill: a CSS color as itsvalue, or a field whose values each take a color through a scale (a color per value, a color per interval between cut points, or a gradient) with a key naming them. Color by writes it: Strand, Attribute..., which picks a field from the features in view, or Solid color....- The row's color:
rows.colors, a color pinned on a row by its value, elserows.color, a color per value of a row attribute such as itsrows.groupsgroup. Use it when the row identity is the signal (one color per population, per treatment arm). - A feature's own color, its BED
itemRgb(a bigBed'sreserved, a BED9's ninth column): ChromHMM state colors, for one. Color by → Default returns to it. A placeholder0or0,0,0, which plain BED files write for no color, is no color here. - Otherwise the default feature color.
A file states its colors but not what they mean, so the file's own colors draw
no key until the config names them: encoding.color.scale.type: "identity" with
scale.domain listing the colors and scale.names naming each, as
ChromHMM chromatin states writes the chromatin states. An identity scale
written this way also reads 0,0,0 as black, as UCSC's itemRgb on does, and a
field beside it reads the CSS colors a column holds.
Binning a numeric column onto a diverging scale is the common case, e.g. segment
mean copy number, with scale.names naming each interval in the key:
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "tcga_brca_cnv",
"name": "TCGA-BRCA copy number",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_cnv.bed.gz",
"csi": true,
"assemblyNames": ["hg38"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "sample",
"encoding": {
"color": {
"field": "segmean",
"scale": {
"type": "threshold",
"domain": [-1, -0.3, 0.3, 1],
"range": ["#2166ac", "#92c5de", "#f7f7f7", "#f4a582", "#b2182b"],
"names": [
"Deep loss (log2 < -1)",
"Loss",
"Balanced",
"Gain",
"Amplification (log2 > 1)"
]
},
"legend": { "title": "Copy number (log2)" }
}
}
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "tcga_brca_cnv",
"name": "TCGA-BRCA copy number",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_cnv.bed.gz",
"csi": true,
"assemblyNames": ["hg38"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "sample",
"encoding": {
"color": {
"field": "segmean",
"scale": {
"type": "threshold",
"domain": [-1, -0.3, 0.3, 1],
"range": ["#2166ac", "#92c5de", "#f7f7f7", "#f4a582", "#b2182b"],
"names": [
"Deep loss (log2 < -1)",
"Loss",
"Balanced",
"Gain",
"Amplification (log2 > 1)"
]
},
"legend": { "title": "Copy number (log2)" }
}
}
}
]
}'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": "tcga_brca_cnv",
"name": "TCGA-BRCA copy number",
"uri": "https://jbrowse.org/demos/tcga/tcga_brca_cnv.bed.gz",
"csi": true,
"assemblyNames": ["hg38"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "sample",
"encoding": {
"color": {
"field": "segmean",
"scale": {
"type": "threshold",
"domain": [-1, -0.3, 0.3, 1],
"range": ["#2166ac", "#92c5de", "#f7f7f7", "#f4a582", "#b2182b"],
"names": [
"Deep loss (log2 < -1)",
"Loss",
"Balanced",
"Gain",
"Amplification (log2 > 1)"
]
},
"legend": { "title": "Copy number (log2)" }
}
}
}
]
}The key and its categories:
- Show → Show legend keys the colors the config names
- Categories, the submenu beside it, hides individual categories and leaves the rest painted. It counts what is hidden and offers Show all categories to put them back
- Order:
encoding.color.scale.domainsets the order the categories read in, the values it lists first and the rest sorted, the same rulerows.sortorders the track's rows by - Single rows: pick a color from a row's swatch in Edit
colors/arrangement..., which writes it as a
rows.colorsentry and applies with no refetch
Row height
The rows divide the track height between them, as a multi-row wiggle's do, so more samples shrink the rows and the track keeps its height. Drag the track taller to give a deep cohort more room per row, or pick Row height to give each row a fixed height and scroll the rest. Show → Show row separators draws a line between rows once they are tall enough to hold one.
Ordering and clustering rows
Rows start sorted by value, digits by magnitude, with the row of features with no value last. To change the order:
- Edit colors/arrangement... reorders, relabels or hand-picks rows in a
dialog, and
rows.sortpins an explicit order in config: the values it lists lead, and the rest sort. - Sort rows by field here, from a feature's right-click menu, orders rows by the value each has at that exact base, like an alignments track's sort-by-base. Rows compare on what colors the blocks, the same as clustering: the color's field, a feature's own color, or with one color for everything whether a row has a feature there. Numbers sort highest first; other values form contiguous blocks, the largest first, so at a QTL peak the rows split by allele.
- Clustering → Cluster rows by similarity... reorders rows so that samples with similar paintings sit together, and draws a dendrogram in the sidebar. See Clustering rows.
Each writes the track's
rows setting, so undo
reaches an arrangement, a shared session contains it, and it survives turning
the track off and on. Reset row order appears in the track menu once any of
them has run, and returns the rows, their labels and their colors to what the
config declares.
rows.groups tags each row with a
group, the first { match, group } entry whose regex its name matches, and
facet: "group" stacks
the rows in bands by it, each band named in a strip beside the dendrogram and
keeping its rows in their arranged order; clustering then runs within each band.
A group takes its color from rows.color:
{
"facet": "group",
"rows": {
"field": "sample",
"groups": [
{ "match": "^CLUP", "group": "Wolf" },
{ "match": "^CLAT", "group": "Coyote" }
],
"color": {
"field": "group",
"scale": {
"domain": ["Wolf", "Coyote"],
"range": ["rgb(27,120,55)", "rgb(224,130,20)"]
}
}
}
}Facet a long list of groups and use the colors as a second cue: a band's position stays readable where many colors are hard to tell apart.
Show → Show tree toggles the dendrogram once one has been computed, and Show → Show row labels the labels beside it, which are useful with no clustering run.
A row with a color draws a bar of it at the left of its label:
- Which rows: one that
rows.colorspins, or thatrows.colorcolors by an attribute such as its group - No value: a row with no value of that attribute, such as one no
rows.groupsentry matches, takes no color unlessrows.color'sscale.domainpairs""with one - Per-feature colors: on a track colored per feature (an
itemRgbpainting, a jexlencoding.color) the bar is the only place a row's color shows
Worked examples
Each of these builds the input file and the track config end to end:
- ChromHMM chromatin states - many cell types from one merged BED, colored by
itemRgband keyed by state - Protein domains on gene models - a transcript per row, its protein domains over its coding exons
- RepeatMasker as one row per class - a RepeatMasker track split into a row per class
- CNV cohort (TCGA) - a thousand tumors, colored by the interval a numeric column falls in
- QTL mapping (BXD mice) - strain genotype painting beside a QTL Manhattan plot, sorted at the peak
- Phased trio analysis (1000 Genomes) - IBD blocks and local ancestry per haplotype
See also
- User guide: Quantitative track - the same one-row-per-sample idea for signal data
- User guide: Variant sample rows
- Config guide: Customizing feature colors
- Reference: LinearMultiRowFeatureDisplay config schema