ChromHMM chromatin states
The tutorials target the JBrowse v5 beta, and the v4.3.0 release
on the download page lacks some of what they show. To install the
beta of JBrowse Web, run npm install -g @jbrowse/cli@next, then
jbrowse create jbrowse2 --branch v5.0.0-beta.22. Desktop beta builds for Linux and
macOS are on the releases page;
the Windows build waits on code signing.
ChromHMM labels each region of the genome with a chromatin state, promoter, enhancer, heterochromatin and so on, once per cell type. We:
- merge per-cell-type segmentation BEDs into one file
- load it as one feature track with a row per cell type, each segment colored by state, over HOXA
- read the state legend, hide states from it and cluster the rows by similarity
- load Roadmap's epigenomes banded by tissue group over PAX5, then narrow the rows to fibroblasts and ES cells over HOXA
Prerequisites
wget- htslib (
bgzip,tabix) node, for the JBrowse CLIpython3, for the Roadmap build onlyjq, for the Roadmap tissue groups only
# Debian/Ubuntu
sudo apt install tabix nodejs
# or conda, which has every tool above
conda install -c bioconda -c conda-forge htslib nodejs
# any platform
npm install -g @jbrowse/cli@nextThe data
Two hg19 ChromHMM releases, both 15-state segmentations: UCSC's ENCODE Broad HMM set, and the Roadmap Epigenomics compendium.
The page's commands build local files from these, and the tracks over those read them from disk; every other track reads a hosted copy. The build script fetches everything itself. The merge step takes your own per-cell-type segmentation BEDs.
| What it is | File |
|---|---|
| The nine ENCODE Broad HMM segmentation BEDs, one per cell type, merged into the multi-row file below | wgEncodeBroadHmm/ |
| The Roadmap segmentations, fetched either individually or as the whole 127-epigenome tarball | final/ |
The row labels, tissue groups and tissue colors, EID_metadata.tab |
EID_metadata.tab |
| The state colors, since the Roadmap segmentations themselves have none | colormap_15_coreMarks.tab |
Read by URL (no download needed)
| What it is | File |
|---|---|
| Both merged files, rehosted as bigBeds so the tracks below load without the build | wgEncodeBroadHmm.multirow.bb roadmap_15state_127epigenomes.bb |
Merging nine ENCODE segmentation BEDs into one file
ChromHMM writes one BED9 per cell type
(Gm12878.bed, K562.bed, ...), with the state in name (for example
1_Active_Promoter) and its color in itemRgb. The nine
UCSC ENCODE Broad HMM
15-state BEDs concatenate into one BED with a trailing cellType field, which
the multi-row feature display turns into one row per value, so any number of
cell types share one config, one adapter and one fetch:
#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 K562The #-prefixed defline gives the adapter its column names. The merge is one
pass:
# Each entry pairs a file's name token with the row label its segments get
CELL_TYPES=(
Gm12878:GM12878
H1hesc:H1-hESC
K562:K562
Hepg2:HepG2
Huvec:HUVEC
Hmec:HMEC
Hsmm:HSMM
Nhek:NHEK
Nhlf:NHLF
)
# awk appends the label to every segment of its file
{
printf '#chrom\tchromStart\tchromEnd\tname\tscore\tstrand\tthickStart\tthickEnd\titemRgb\tcellType\n'
for entry in "${CELL_TYPES[@]}"; do
gzip -dc "wgEncodeBroadHmm${entry%%:*}HMM.bed.gz" |
awk -v c="${entry##*:}" 'BEGIN{OFS="\t"} {print $0, c}'
done
} > multirow.bed
# `sort-bed` is `sort -k1,1 -k2,2n` with the #-defline kept on top, and pins
# LC_ALL=C so nine files' worth of refnames group the same way everywhere
jbrowse sort-bed multirow.bed | bgzip > multirow.bed.gz
tabix -f -C -p bed multirow.bed.gzA BigBedAdapter reads the hosted bigBed copies
of both merged files, as in the Roadmap track config below.
Configuring a multi-row display, one row per cell type
The Broad and Roadmap releases are both on hg19, so we load that assembly and a RefSeq gene track:
Goes in the assemblies array of config.json. See Assemblies.
{
"name": "hg19",
"uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bit",
"refNameAliases": {
"uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.chromAlias.txt"
}
}Edits config.json in the current folder, creating it if there is none. See JBrowse CLI with Desktop.
jbrowse add-assembly https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bit \
--name hg19 \
--refNameAliases https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.chromAlias.txthg19 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Browse hosted genomes and pick it. To load the files of this config instead:
In JBrowse Desktop, Open your own genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste:
https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bitJBrowse reads the format off the file name. Then fill in:
- Genome name:
hg19 - refName aliases (under More options):
https://hgdownload.soe.ucsc.edu/goldenPath/hg19/bigZips/hg19.chromAlias.txt
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "ncbi_gff_hg19",
"name": "NCBI RefSeq genes",
"assemblyNames": ["hg19"],
"adapter": {
"type": "Gff3TabixAdapter",
"uri": "https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz"
}
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz \
--trackId ncbi_gff_hg19 \
--name "NCBI RefSeq genes" \
--assemblyNames hg19In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:
- Main file:
https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz
JBrowse reads the adapter and track type off the file name. Then fill in:
- Track name:
NCBI RefSeq genes - Assembly:
hg19
Click Add.
Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg19%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22ncbi_gff_hg19%22%2C%22name%22%3A%22NCBI+RefSeq+genes%22%2C%22assemblyNames%22%3A%5B%22hg19%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22Gff3TabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fs3.amazonaws.com%2Fjbrowse.org%2Fgenomes%2Fhg19%2Fncbi_refseq%2FGRCh37_latest_genomic.sort.gff.gz%22%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr7%3A27%2C110%2C000-27%2C265%2C000%22%2C%22tracks%22%3A%5B%22ncbi_gff_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+NCBI+RefSeq+genesThis view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/ucsc/hg19/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"type": "FeatureTrack",
"trackId": "ncbi_gff_hg19",
"name": "NCBI RefSeq genes",
"assemblyNames": [
"hg19"
],
"adapter": {
"type": "Gff3TabixAdapter",
"uri": "https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz"
}
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg19",
"loc": "chr7:27,110,000-27,265,000",
"tracks": [
"ncbi_gff_hg19"
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/ucsc/hg19/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={[...(config.tracks ?? []), ...[
{
"type": "FeatureTrack",
"trackId": "ncbi_gff_hg19",
"name": "NCBI RefSeq genes",
"assemblyNames": [
"hg19"
],
"adapter": {
"type": "Gff3TabixAdapter",
"uri": "https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz"
}
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg19",
"loc": "chr7:27,110,000-27,265,000",
"tracks": [
"ncbi_gff_hg19"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"type": "FeatureTrack",
"trackId": "ncbi_gff_hg19",
"name": "NCBI RefSeq genes",
"assemblyNames": [
"hg19"
],
"adapter": {
"type": "Gff3TabixAdapter",
"uri": "https://s3.amazonaws.com/jbrowse.org/genomes/hg19/ncbi_refseq/GRCh37_latest_genomic.sort.gff.gz"
}
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg19/config.json \
--trackConfigs tracks.json \
--assembly hg19 --loc chr7:27,110,000-27,265,000 \
--track ncbi_gff_hg19 \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
The track config below opens the merged file in a multi-row feature display
partitioned on cellType. For your own segmentations, point uri at the
bgzipped BED from the merge above and index at its .csi:
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",
"csi": true,
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": {
"field": "cellType",
"sort": [
"GM12878",
"H1-hESC",
"K562",
"HepG2",
"HUVEC",
"HMEC",
"HSMM",
"NHEK",
"NHLF"
]
},
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,105,105)",
"rgb(207,11,198)",
"rgb(250,202,0)",
"rgb(255,252,4)",
"rgb(10,190,254)",
"rgb(0,176,80)",
"rgb(153,255,102)",
"rgb(127,127,127)",
"rgb(245,245,245)"
],
"names": [
"1 Active promoter",
"2 Weak promoter",
"3 Poised promoter",
"4-5 Strong enhancer",
"6-7 Weak enhancer",
"8 Insulator",
"9-10 Transcription",
"11 Weak transcription",
"12 Polycomb repressed",
"13-15 Heterochromatin / repetitive"
]
},
"legend": { "title": "Chromatin state" }
}
},
"height": 200
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
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",
"csi": true,
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": {
"field": "cellType",
"sort": [
"GM12878",
"H1-hESC",
"K562",
"HepG2",
"HUVEC",
"HMEC",
"HSMM",
"NHEK",
"NHLF"
]
},
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,105,105)",
"rgb(207,11,198)",
"rgb(250,202,0)",
"rgb(255,252,4)",
"rgb(10,190,254)",
"rgb(0,176,80)",
"rgb(153,255,102)",
"rgb(127,127,127)",
"rgb(245,245,245)"
],
"names": [
"1 Active promoter",
"2 Weak promoter",
"3 Poised promoter",
"4-5 Strong enhancer",
"6-7 Weak enhancer",
"8 Insulator",
"9-10 Transcription",
"11 Weak transcription",
"12 Polycomb repressed",
"13-15 Heterochromatin / repetitive"
]
},
"legend": { "title": "Chromatin state" }
}
},
"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",
"csi": true,
"assemblyNames": ["hg19"],
"category": ["ENCODE", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": {
"field": "cellType",
"sort": [
"GM12878",
"H1-hESC",
"K562",
"HepG2",
"HUVEC",
"HMEC",
"HSMM",
"NHEK",
"NHLF"
]
},
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,105,105)",
"rgb(207,11,198)",
"rgb(250,202,0)",
"rgb(255,252,4)",
"rgb(10,190,254)",
"rgb(0,176,80)",
"rgb(153,255,102)",
"rgb(127,127,127)",
"rgb(245,245,245)"
],
"names": [
"1 Active promoter",
"2 Weak promoter",
"3 Poised promoter",
"4-5 Strong enhancer",
"6-7 Weak enhancer",
"8 Insulator",
"9-10 Transcription",
"11 Weak transcription",
"12 Polycomb repressed",
"13-15 Heterochromatin / repetitive"
]
},
"legend": { "title": "Chromatin state" }
}
},
"height": 200
}
]
}wgEncodeBroadHmm.multirow.bed.gz is relative to a config.json. Replace it with its URL or its path on this computer.
In grammar-of-graphics terms,
rows assigns the rows:
fieldis the attribute to split rows by, so every distinctcellTypebecomes a labeled rowsortpins the rows to an order, here ENCODE's tiers; without it the rows sort by value
JBrowse paints each feature with its itemRgb, and
encoding.color names those colors
in the key: an identity scale paints the file's own colors, and scale.names
labels the scale.domain colors in order. Written with a field instead,
encoding.color is a color scale that overrides the file's colors, mapping the
field's values through its scale.domain to its scale.range. The adapter
needs columnNames only for a
file without a defline.
Type chr7:27,110,000-27,265,000 into the location box, the HOXA cluster:
The HOX genes are transcribed in the order they sit in, so each cell type opens
the stretch matching its position along the body axis and holds the rest under
Polycomb, a repressive chromatin complex. H1-hESC's magenta is
3_Poised_Promoter, the bivalent state HOX clusters are held in before a
lineage commits.
Chromatin-state legend, filtering and row order
The key lists the identity scale's scale.domain, each color under its
scale.names entry. A file states only the color, never what it means, so a
track whose config names no domain draws no key. States that share a color share
an entry, so in the Broad 15-state model 4_Strong_Enhancer and
5_Strong_Enhancer are one row, 4-5 Strong enhancer.
Most of any segmentation is quiescent or heterochromatic. The track menu has these actions for reading the rest:
- Show → Show legend turns the key off.
- The Categories submenu has a checkbox per legend entry. Uncheck the quiescent and repressed states to leave the promoters, enhancers and transcription.
- Clustering → Cluster rows by similarity... reorders the rows by the state each has across the region in view and draws the dendrogram in the sidebar.
- Right-click a state and pick Sort rows by color here to rank the rows by the state each has at that base.
Roadmap's epigenomes at PAX5 and HOXA
The nine ENCODE lines are a small sample of tissues. The
Roadmap Epigenomics
15-state segmentations of the Roadmap epigenomes merge the same way, into one
track and one fetch, and the merged file is hosted. Their state names are
mnemonics (12_EnhBiv, 14_ReprPCWk), so this track labels its colors with
scale.type: "identity": each block is still painted with the file's itemRgb,
and scale.names spells out the fifteen scale.domain colors in order.
The config below leaves out three settings the PAX5 figure uses: a rows.sort
naming every epigenome, grouped by tissue, and the rows.groups and
rows.color built further down that color the label bars. The hosted demo
config, https://jbrowse.org/code/jb2/main/test_data/config_demo.json, has the
track with all three:
Goes in the tracks array of config.json. See Tracks.
{
"type": "FeatureTrack",
"trackId": "roadmap_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Roadmap, 127 epigenomes)",
"uri": "https://jbrowse.org/demos/chromhmm/roadmap_15state_127epigenomes.bb",
"assemblyNames": ["hg19"],
"category": ["Roadmap Epigenomics", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType",
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,69,0)",
"rgb(50,205,50)",
"rgb(0,128,0)",
"rgb(0,100,0)",
"rgb(194,225,5)",
"rgb(255,255,0)",
"rgb(102,205,170)",
"rgb(138,145,208)",
"rgb(205,92,92)",
"rgb(233,150,122)",
"rgb(189,183,107)",
"rgb(128,128,128)",
"rgb(192,192,192)",
"rgb(255,255,255)"
],
"names": [
"1 Active TSS",
"2 Flanking active TSS",
"3 Transcribed 5'/3' flank",
"4 Strong transcription",
"5 Weak transcription",
"6 Genic enhancer",
"7 Enhancer",
"8 ZNF genes / repeats",
"9 Heterochromatin",
"10 Bivalent TSS",
"11 Flanking bivalent",
"12 Bivalent enhancer",
"13 Repressed Polycomb",
"14 Weak repressed Polycomb",
"15 Quiescent / low"
]
}
}
},
"height": 700
}
]
}Edits config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse add-track-json '{
"type": "FeatureTrack",
"trackId": "roadmap_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Roadmap, 127 epigenomes)",
"uri": "https://jbrowse.org/demos/chromhmm/roadmap_15state_127epigenomes.bb",
"assemblyNames": ["hg19"],
"category": ["Roadmap Epigenomics", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType",
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,69,0)",
"rgb(50,205,50)",
"rgb(0,128,0)",
"rgb(0,100,0)",
"rgb(194,225,5)",
"rgb(255,255,0)",
"rgb(102,205,170)",
"rgb(138,145,208)",
"rgb(205,92,92)",
"rgb(233,150,122)",
"rgb(189,183,107)",
"rgb(128,128,128)",
"rgb(192,192,192)",
"rgb(255,255,255)"
],
"names": [
"1 Active TSS",
"2 Flanking active TSS",
"3 Transcribed 5'\''/3'\'' flank",
"4 Strong transcription",
"5 Weak transcription",
"6 Genic enhancer",
"7 Enhancer",
"8 ZNF genes / repeats",
"9 Heterochromatin",
"10 Bivalent TSS",
"11 Flanking bivalent",
"12 Bivalent enhancer",
"13 Repressed Polycomb",
"14 Weak repressed Polycomb",
"15 Quiescent / low"
]
}
}
},
"height": 700
}
]
}'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": "roadmap_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Roadmap, 127 epigenomes)",
"uri": "https://jbrowse.org/demos/chromhmm/roadmap_15state_127epigenomes.bb",
"assemblyNames": ["hg19"],
"category": ["Roadmap Epigenomics", "Chromatin state"],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType",
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,69,0)",
"rgb(50,205,50)",
"rgb(0,128,0)",
"rgb(0,100,0)",
"rgb(194,225,5)",
"rgb(255,255,0)",
"rgb(102,205,170)",
"rgb(138,145,208)",
"rgb(205,92,92)",
"rgb(233,150,122)",
"rgb(189,183,107)",
"rgb(128,128,128)",
"rgb(192,192,192)",
"rgb(255,255,255)"
],
"names": [
"1 Active TSS",
"2 Flanking active TSS",
"3 Transcribed 5'/3' flank",
"4 Strong transcription",
"5 Weak transcription",
"6 Genic enhancer",
"7 Enhancer",
"8 ZNF genes / repeats",
"9 Heterochromatin",
"10 Bivalent TSS",
"11 Flanking bivalent",
"12 Bivalent enhancer",
"13 Repressed Polycomb",
"14 Weak repressed Polycomb",
"15 Quiescent / low"
]
}
}
},
"height": 700
}
]
}Open this track in JBrowse Web ↗
Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.
https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg19%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22roadmap_chromhmm_multirow_hg19%22%2C%22name%22%3A%22ChromHMM+chromatin+state+%28Roadmap%2C+127+epigenomes%29%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fchromhmm%2Froadmap_15state_127epigenomes.bb%22%2C%22assemblyNames%22%3A%5B%22hg19%22%5D%2C%22category%22%3A%5B%22Roadmap+Epigenomics%22%2C%22Chromatin+state%22%5D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearMultiRowFeatureDisplay%22%2C%22rows%22%3A%22cellType%22%2C%22encoding%22%3A%7B%22color%22%3A%7B%22scale%22%3A%7B%22type%22%3A%22identity%22%2C%22domain%22%3A%5B%22rgb%28255%2C0%2C0%29%22%2C%22rgb%28255%2C69%2C0%29%22%2C%22rgb%2850%2C205%2C50%29%22%2C%22rgb%280%2C128%2C0%29%22%2C%22rgb%280%2C100%2C0%29%22%2C%22rgb%28194%2C225%2C5%29%22%2C%22rgb%28255%2C255%2C0%29%22%2C%22rgb%28102%2C205%2C170%29%22%2C%22rgb%28138%2C145%2C208%29%22%2C%22rgb%28205%2C92%2C92%29%22%2C%22rgb%28233%2C150%2C122%29%22%2C%22rgb%28189%2C183%2C107%29%22%2C%22rgb%28128%2C128%2C128%29%22%2C%22rgb%28192%2C192%2C192%29%22%2C%22rgb%28255%2C255%2C255%29%22%5D%2C%22names%22%3A%5B%221+Active+TSS%22%2C%222+Flanking+active+TSS%22%2C%223+Transcribed+5%27%2F3%27+flank%22%2C%224+Strong+transcription%22%2C%225+Weak+transcription%22%2C%226+Genic+enhancer%22%2C%227+Enhancer%22%2C%228+ZNF+genes+%2F+repeats%22%2C%229+Heterochromatin%22%2C%2210+Bivalent+TSS%22%2C%2211+Flanking+bivalent%22%2C%2212+Bivalent+enhancer%22%2C%2213+Repressed+Polycomb%22%2C%2214+Weak+repressed+Polycomb%22%2C%2215+Quiescent+%2F+low%22%5D%7D%7D%7D%2C%22height%22%3A700%7D%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr9%3A34%2C700%2C000-38%2C420%2C000%22%2C%22tracks%22%3A%5B%22roadmap_chromhmm_multirow_hg19%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+ChromHMM+chromatin+state+%28Roadmap%2C+127+epigenomes%29This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.
from jbrowse_anywidget import JBrowseApp, fetch_hub
config = fetch_hub("https://jbrowse.org/ucsc/hg19/config.json")
app = JBrowseApp(
assemblies=config["assemblies"],
tracks=config.get("tracks", []) + [
{
"type": "FeatureTrack",
"trackId": "roadmap_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Roadmap, 127 epigenomes)",
"uri": "https://jbrowse.org/demos/chromhmm/roadmap_15state_127epigenomes.bb",
"assemblyNames": [
"hg19"
],
"category": [
"Roadmap Epigenomics",
"Chromatin state"
],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType",
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,69,0)",
"rgb(50,205,50)",
"rgb(0,128,0)",
"rgb(0,100,0)",
"rgb(194,225,5)",
"rgb(255,255,0)",
"rgb(102,205,170)",
"rgb(138,145,208)",
"rgb(205,92,92)",
"rgb(233,150,122)",
"rgb(189,183,107)",
"rgb(128,128,128)",
"rgb(192,192,192)",
"rgb(255,255,255)"
],
"names": [
"1 Active TSS",
"2 Flanking active TSS",
"3 Transcribed 5'/3' flank",
"4 Strong transcription",
"5 Weak transcription",
"6 Genic enhancer",
"7 Enhancer",
"8 ZNF genes / repeats",
"9 Heterochromatin",
"10 Bivalent TSS",
"11 Flanking bivalent",
"12 Bivalent enhancer",
"13 Repressed Polycomb",
"14 Weak repressed Polycomb",
"15 Quiescent / low"
]
}
}
},
"height": 700
}
]
}
],
views=[
{
"type": "LinearGenomeView",
"assembly": "hg19",
"loc": "chr9:34,700,000-38,420,000",
"tracks": [
"roadmap_chromhmm_multirow_hg19"
]
}
],
)
app # display the widgetThis view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.
import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'
const configUrl = "https://jbrowse.org/ucsc/hg19/config.json"
const configPromise = fetch(configUrl)
.then(res => res.json())
.then(config => {
addRelativeUris(config, new URL(configUrl))
return config
})
export default function Figure() {
const config = use(configPromise)
return (
<JBrowse
assemblies={config.assemblies}
tracks={[...(config.tracks ?? []), ...[
{
"type": "FeatureTrack",
"trackId": "roadmap_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Roadmap, 127 epigenomes)",
"uri": "https://jbrowse.org/demos/chromhmm/roadmap_15state_127epigenomes.bb",
"assemblyNames": [
"hg19"
],
"category": [
"Roadmap Epigenomics",
"Chromatin state"
],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType",
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,69,0)",
"rgb(50,205,50)",
"rgb(0,128,0)",
"rgb(0,100,0)",
"rgb(194,225,5)",
"rgb(255,255,0)",
"rgb(102,205,170)",
"rgb(138,145,208)",
"rgb(205,92,92)",
"rgb(233,150,122)",
"rgb(189,183,107)",
"rgb(128,128,128)",
"rgb(192,192,192)",
"rgb(255,255,255)"
],
"names": [
"1 Active TSS",
"2 Flanking active TSS",
"3 Transcribed 5'/3' flank",
"4 Strong transcription",
"5 Weak transcription",
"6 Genic enhancer",
"7 Enhancer",
"8 ZNF genes / repeats",
"9 Heterochromatin",
"10 Bivalent TSS",
"11 Flanking bivalent",
"12 Bivalent enhancer",
"13 Repressed Polycomb",
"14 Weak repressed Polycomb",
"15 Quiescent / low"
]
}
}
},
"height": 700
}
]
}
]]}
aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
configuration={config.configuration}
views={[
{
"type": "LinearGenomeView",
"assembly": "hg19",
"loc": "chr9:34,700,000-38,420,000",
"tracks": [
"roadmap_chromhmm_multirow_hg19"
]
}
]}
/>
)
}jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.
cat > tracks.json <<'JSON'
[
{
"type": "FeatureTrack",
"trackId": "roadmap_chromhmm_multirow_hg19",
"name": "ChromHMM chromatin state (Roadmap, 127 epigenomes)",
"uri": "https://jbrowse.org/demos/chromhmm/roadmap_15state_127epigenomes.bb",
"assemblyNames": [
"hg19"
],
"category": [
"Roadmap Epigenomics",
"Chromatin state"
],
"displays": [
{
"type": "LinearMultiRowFeatureDisplay",
"rows": "cellType",
"encoding": {
"color": {
"scale": {
"type": "identity",
"domain": [
"rgb(255,0,0)",
"rgb(255,69,0)",
"rgb(50,205,50)",
"rgb(0,128,0)",
"rgb(0,100,0)",
"rgb(194,225,5)",
"rgb(255,255,0)",
"rgb(102,205,170)",
"rgb(138,145,208)",
"rgb(205,92,92)",
"rgb(233,150,122)",
"rgb(189,183,107)",
"rgb(128,128,128)",
"rgb(192,192,192)",
"rgb(255,255,255)"
],
"names": [
"1 Active TSS",
"2 Flanking active TSS",
"3 Transcribed 5'/3' flank",
"4 Strong transcription",
"5 Weak transcription",
"6 Genic enhancer",
"7 Enhancer",
"8 ZNF genes / repeats",
"9 Heterochromatin",
"10 Bivalent TSS",
"11 Flanking bivalent",
"12 Bivalent enhancer",
"13 Repressed Polycomb",
"14 Weak repressed Polycomb",
"15 Quiescent / low"
]
}
}
},
"height": 700
}
]
}
]
JSON
npx @jbrowse/img --config https://jbrowse.org/ucsc/hg19/config.json \
--trackConfigs tracks.json \
--assembly hg19 --loc chr9:34,700,000-38,420,000 \
--track roadmap_chromhmm_multirow_hg19 \
--out figure.svgFor a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).
Red is active TSS, yellow enhancer, green transcription, grey Polycomb, and speckled olive bivalent.
With a row per epigenome in one track, a row is a few pixels tall and its label barely legible, so we group the rows by the Roadmap tissue groups with three settings:
rows.groupstags each row with agroup, taking one{ match, group }per tissue, wherematchis a regex over the row namesfacet"group"splits the display into stacked sections, one per tissuerows.colorwithfield: "group"is a color scale on each row's label bar that pairs each tissue with a color
The blocks are still painted in their itemRgb state colors, so the tissue
color appears on the label bar alone. Two of the nineteen tissues look like
this:
{
"facet": "group",
"rows": {
"field": "cellType",
"groups": [
{ "match": "^(Adipose Nuclei)$", "group": "Adipose" },
{
"match": "^(Aorta|Fetal Heart|Left Ventricle|Right Atrium|Right Ventricle)$",
"group": "Heart"
}
],
"color": {
"field": "group",
"scale": {
"domain": ["Adipose", "Heart"],
"range": ["#AF5B39", "#D56F80"]
}
}
}
}Both lists come from the GROUP and COLOR columns of
EID_metadata.tab.1 One jq call writes them from the STD_NAME
column, escaping the regex metacharacters in the names:
jq -R -s 'split("\n")[1:-1] | map(split("\t")) | group_by(.[1])
| { groups: map({ match: ("^(" + (map(.[4] | gsub("(?<c>[.()+*?\\[\\]^$|\\\\{}])"; "\\" + .c)) | join("|")) + ")$"),
group: .[0][1] }),
color: { field: "group",
scale: { domain: map(.[0][1]), range: map(.[0][2]) } } }' EID_metadata.tab > tissues.jsonMerge groups and color from tissues.json into the display's rows. The
build script also appends the mnemonic to a name that two epigenomes share,
which a STD_NAME match leaves as one row.
The hosted track orders the rows by tissue group through rows.sort and leaves
facet out, so clustering runs over all the rows together and the label bars
show which tissues a cluster spans. The PAX5 figure adds facet with this
sort, which stacks the groups in the paper's order:
{
"facet": {
"field": "group",
"sort": [
"IMR90",
"ESC",
"iPSC",
"ES-deriv",
"Blood & T-cell",
"HSC & B-cell",
"Mesench",
"Myosat",
"Epithelial",
"Neurosph",
"Thymus",
"Brain",
"Adipose",
"Muscle",
"Heart",
"Sm. Muscle",
"Digestive",
"Other",
"ENCODE2012"
]
}
}Type chr9:34,700,000-38,420,000 into the location box, the chr9 stretch from
FAM205A to ALDH1B1. With the groups stacked in the paper's order, the track
reproduces Roadmap Epigenomics 2015 Fig.
3a, all 127 epigenomes. Over PAX5:
- strong transcription with genic enhancers (green and yellow) marks only the B cells and the B-lymphoblastoid GM12878
- spleen and blood mononuclear cells, which hold B cells, and a few ES, iPS and neural progenitor lines show PAX5 transcribed without the enhancers
Listing epigenome names in rows.sort (the order) and rows.kept (the subset)
narrows the same track to lung fibroblasts, foreskin fibroblasts and ES cells
over HOXA, which reproduces the chromatin domains
Rinn et al. 2007 mapped in
fibroblasts from different parts of the body:
Goes at the top level of config.json, replacing any defaultSession there. See Default session.
{
"defaultSession": {
"name": "HOXA fibroblasts",
"views": [
{
"type": "LinearGenomeView",
"assembly": "hg19",
"loc": "chr7:27,110,000-27,265,000",
"tracks": [
{
"trackId": "roadmap_chromhmm_multirow_hg19",
"rows": {
"field": "cellType",
"sort": [
"NHLF Lung Fibroblast Primary Cells",
"IMR90 fetal lung fibroblasts Cell Line",
"Foreskin Fibroblast Primary Cells skin01",
"Foreskin Fibroblast Primary Cells skin02",
"H1 Cells",
"H9 Cells"
],
"kept": [
"NHLF Lung Fibroblast Primary Cells",
"IMR90 fetal lung fibroblasts Cell Line",
"Foreskin Fibroblast Primary Cells skin01",
"Foreskin Fibroblast Primary Cells skin02",
"H1 Cells",
"H9 Cells"
]
},
"height": 240
}
]
}
]
}
}Replaces any defaultSession in config.json in the current folder. See JBrowse CLI with Desktop.
jbrowse set-default-session --session - << 'EOF'
{
"name": "HOXA fibroblasts",
"views": [
{
"type": "LinearGenomeView",
"assembly": "hg19",
"loc": "chr7:27,110,000-27,265,000",
"tracks": [
{
"trackId": "roadmap_chromhmm_multirow_hg19",
"rows": {
"field": "cellType",
"sort": [
"NHLF Lung Fibroblast Primary Cells",
"IMR90 fetal lung fibroblasts Cell Line",
"Foreskin Fibroblast Primary Cells skin01",
"Foreskin Fibroblast Primary Cells skin02",
"H1 Cells",
"H9 Cells"
],
"kept": [
"NHLF Lung Fibroblast Primary Cells",
"IMR90 fetal lung fibroblasts Cell Line",
"Foreskin Fibroblast Primary Cells skin01",
"Foreskin Fibroblast Primary Cells skin02",
"H1 Cells",
"H9 Cells"
]
},
"height": 240
}
]
}
]
}
EOFAdvanced → Edit plot... in the track menu shows rows with its sort and
kept as text and applies the same subset to an open track live.
Clustering → Cluster rows by similarity... in the track menu replaces the tissue order with one derived from the data at whatever locus is in view.
Reproduce it end to end
build_chromhmm_multirow.sh
does the whole path. The script:
- Downloads the segmentation BEDs.
- Merges them, then bgzips and indexes the result.
- Downloads JBrowse and writes the
config.jsonabove, opening on HOXA.
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_chromhmm_multirow.sh
bash build_chromhmm_multirow.sh # builds ./chromhmm_build/jbrowse2
npx --yes serve chromhmm_build/jbrowse2 # then open the printed URLbuild_chromhmm_roadmap.sh
builds the Roadmap epigenome track by the same merge. Roadmap's segmentations
are bare BED4, so the script fills in what the ENCODE files had:
- paints each segment its state's color from
colormap_15_coreMarks.tab, giving the merged file theitemRgbcolumn JBrowse colors it by - labels each row with the epigenome's name from
EID_metadata.tab, adding its mnemonic where two epigenomes share a name, so the two never merge into one row - orders the rows by tissue group, so a tissue's epigenomes sit together under one label-bar color
One awk call joins the colors for an epigenome, looking each state's number
(the part of the name before the underscore) up in the colormap and appending
the itemRgb and cellType columns:
awk -F'\t' -v c="NHLF Lung Fibroblast Primary Cells" 'BEGIN { OFS = "\t" }
NR == FNR { rgb[$1] = $2; next }
{ split($4, s, "_"); print $1, $2, $3, $4, 0, ".", $2, $3, rgb[s[1]], c }' \
colormap_15_coreMarks.tab E128_15_coreMarks_mnemonics.bedcurl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_chromhmm_roadmap.sh
EIDS=E003,E116,E123,E127 bash build_chromhmm_roadmap.sh
npx --yes serve chromhmm_roadmap_build/jbrowse2EIDS picks a subset, here the Roadmap re-analyses of the ENCODE lines in the
ENCODE track. Leave it out for every epigenome, which takes tens of minutes and
gigabytes of scratch.
See also
- Tutorial: CNV cohort (TCGA)
- Tutorial: QTL mapping (BXD mice)
- Tutorial: Phased trio analysis (1000 Genomes)
- Tutorial: Single-cell RNA and ATAC pseudobulk
- Tutorial: A grammar of graphics over a BED (RepeatMasker Alu age)
- Tutorial: AlphaGenome predictions
- User guide: Clustering rows
- Config guide: Tracks
- Config guide: Grouping and lane order
Notes
-
The groups in
EID_metadata.tabinclude ENCODE2012. Roadmap folded the ENCODE 2012 reference epigenomes (GM12878, K562, HeLa-S3, HepG2, A549, HUVEC, NHEK and the rest) into the compendium as one group, which names a data source and spans several anatomies. The same file'sANATOMYcolumn splits them finer, andTYPErecords how each sample was collected. ↩
Feedback on this tutorial is welcome: contact us.