Skip to main content

ChromHMM chromatin states

JBrowse v5 beta

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.13. Desktop beta builds are coming soon.

ChromHMM labels each region of the genome with a chromatin state, promoter, enhancer, heterochromatin and so on, once per cell type. We merge many per-cell-type segmentation BEDs into one file, which JBrowse draws as a single track with one color-coded row per cell type. We read it at two loci: the HOXA cluster, where each cell type opens the genes matching its place along the body axis, and PAX5, a B-cell gene with genic enhancers only in B cells.

Prerequisites

On Debian/Ubuntu, apt install wget tabix covers wget and htslib; node comes from nodejs.org.

Where the data comes from

Two hg19 ChromHMM releases, both 15-state segmentations: UCSC's nine-cell-type ENCODE Broad HMM set, and the Roadmap Epigenomics compendium across 127 epigenomes.

The build scripts fetch these files, so there is nothing to download by hand.

Read by URL (no download needed)

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 9 cell types (or 127) 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  K562

The #-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 -p bed multirow.bed.gz

A 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

Both releases are 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"
  }
}
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.txt

hg19 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Show all available genomes and pick it. To load the files of this config instead:

In JBrowse Desktop, Open new 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.2bit

JBrowse 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"
  }
}
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 hg19

In 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

Click Next. 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 ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

The track config below opens the merged file in a multi-row feature display partitioned on cellType. For your own segmentations, swap uri for the bgzipped, tabix-indexed BED from the merge above:

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",
        "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)",
  "uri": "wgEncodeBroadHmm.multirow.bed.gz",
  "assemblyNames": ["hg19"],
  "category": ["ENCODE", "Chromatin state"],
  "displays": [
    {
      "type": "LinearMultiRowFeatureDisplay",
      "rows": {
        "field": "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)",
  "uri": "wgEncodeBroadHmm.multirow.bed.gz",
  "assemblyNames": ["hg19"],
  "category": ["ENCODE", "Chromatin state"],
  "displays": [
    {
      "type": "LinearMultiRowFeatureDisplay",
      "rows": {
        "field": "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.

JBrowse finds the .bed.gz.tbi beside the file. In grammar-of-graphics terms, rows assigns the rows:

  • field is the attribute to split rows by, so every distinct cellType becomes a labeled row
  • domain pins the rows to an order, here ENCODE's tiers; without it the rows sort by value

JBrowse paints each feature with its itemRgb. The color slot is a color scale that overrides this, mapping the values of a field through its domain to its 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 nine ENCODE cell types over HOXA, one row each in ENCODE's tier order, under the RefSeq genes. HUVEC, HSMM and NHEK are active into the posterior genes, NHLF stops at HOXA7 and HMEC fades past it, the blood lines GM12878 and K562 are repressed across the cluster, and H1-hESC is poised.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%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%7B%22trackId%22%3A%22ncbi_gff_hg19%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22name%22%2C%22filter%22%3A%5B%22jexl%3Afeature.type%21%3D%27pseudogene%27%22%5D%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22broad_chromhmm_multirow_hg19%22%2C%22type%22%3A%22LinearMultiRowFeatureDisplay%22%2C%22height%22%3A240%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+chromhmm_encode_hoxa

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg19)”.
    1. Track menu → Show... → Labels → Name only
    2. Track menu → Filter by... → add the expressionThis figure filters on feature.type!='pseudogene'.
  3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ChromHMM chromatin state (Broad ENCODE, 9 cell types)”.
  4. Type your region of interest into the location box and press Enter.This figure is at chr7:27,110,000-27,265,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr7:27,110,000-27,265,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "height": 110
        },
        {
          "trackId": "broad_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 240
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr7:27,110,000-27,265,000",
            "tracks": [
                {
                    "trackId": "ncbi_gff_hg19",
                    "type": "LinearBasicDisplay",
                    "showLabels": "name",
                    "filter": [
                        "jexl:feature.type!='pseudogene'"
                    ],
                    "height": 110
                },
                {
                    "trackId": "broad_chromhmm_multirow_hg19",
                    "type": "LinearMultiRowFeatureDisplay",
                    "height": 240
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg19 --loc chr7:27,110,000-27,265,000 \
  --track ncbi_gff_hg19 display:LinearBasicDisplay '{"showLabels":"name","filter":["jexl:feature.type!='\''pseudogene'\''"],"height":110}' \
  --track broad_chromhmm_multirow_hg19 display:LinearMultiRowFeatureDisplay '{"height":240}' \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr7:27,110,000-27,265,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "height": 110
        },
        {
          "trackId": "broad_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 240
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --width 1500 --height 620 \
  --timeout 120000 \
  --spec session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

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

JBrowse builds the key from the state colors, one entry per distinct color, labeled with the first state name seen in it. States sharing a color collapse into one entry, so in the Broad 15-state model 4_Strong_Enhancer shares its entry with 5_. An identity color scale keeps the file's colors and relabels them in the key.

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. Unchecking the quiescent and repressed states leaves 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 column and pick Sort rows by color here to rank the rows by the state each has at that base.

Roadmap's 127 epigenomes at PAX5 and HOXA

The Roadmap Epigenomics 15-state segmentations of 127 epigenomes merge the same way, into one track and one fetch. Their state names are mnemonics (12_EnhBiv, 14_ReprPCWk), so this track labels its colors with scale: "identity": the file's itemRgb still paints each block, and labels spells out the fifteen domain colors in order. The merged file is hosted, so the track loads as it stands. The track omits three settings the PAX5 figure uses: a rows.domain naming every epigenome, grouped by tissue, and the rowGroups and rowColor built later in this section 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",
      "color": {
        "scale": "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)"
        ],
        "labels": [
          "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
    }
  ]
}
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",
      "color": {
        "scale": "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)"
        ],
        "labels": [
          "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",
      "color": {
        "scale": "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)"
        ],
        "labels": [
          "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 ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

Red is active TSS, yellow enhancer, green transcription, grey Polycomb, and speckled olive bivalent.

Type chr9:34,700,000-38,420,000 into the location box, the chr9 stretch from FAM205A to ALDH1B1. The figure below adds a facet whose domain lists the tissue groups in the paper's order, which 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
All 127 Roadmap epigenomes over chr9 from FAM205A to ALDH1B1, rows in the paper's tissue order and banded by tissue group with facet, each label tinted by its group. Promoters are red in every tissue; PAX5 (boxed) is transcribed with genic enhancers only in the B cell rows and GM12878.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%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%7B%22trackId%22%3A%22ncbi_gff_hg19%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22name%22%2C%22filter%22%3A%5B%22jexl%3Afeature.type%21%3D%27pseudogene%27%22%5D%2C%22displayMode%22%3A%22compact%22%2C%22height%22%3A80%7D%2C%7B%22trackId%22%3A%22roadmap_chromhmm_multirow_hg19%22%2C%22type%22%3A%22LinearMultiRowFeatureDisplay%22%2C%22facet%22%3A%7B%22field%22%3A%22group%22%2C%22domain%22%3A%5B%22IMR90%22%2C%22ESC%22%2C%22iPSC%22%2C%22ES-deriv%22%2C%22Blood+%26+T-cell%22%2C%22HSC+%26+B-cell%22%2C%22Mesench%22%2C%22Myosat%22%2C%22Epithelial%22%2C%22Neurosph%22%2C%22Thymus%22%2C%22Brain%22%2C%22Adipose%22%2C%22Muscle%22%2C%22Heart%22%2C%22Sm.+Muscle%22%2C%22Digestive%22%2C%22Other%22%2C%22ENCODE2012%22%5D%7D%2C%22height%22%3A900%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+chromhmm

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg19)”.
    1. Track menu → Show... → Labels → Name only
    2. Track menu → Filter by... → add the expressionThis figure filters on feature.type!='pseudogene'.
    3. Track menu → Feature height → Compact
  3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ChromHMM chromatin state (Roadmap, 127 epigenomes)”.
    1. Track menu → Group by... → groupThe submenu lists the attributes the loaded rows carry. This figure also fixes the band order, which the config sets.
  4. Type your region of interest into the location box and press Enter.This figure is at chr9:34,700,000-38,420,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr9:34,700,000-38,420,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "displayMode": "compact",
          "height": 80
        },
        {
          "trackId": "roadmap_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "facet": {
            "field": "group",
            "domain": [
              "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"
            ]
          },
          "height": 900
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr9:34,700,000-38,420,000",
            "tracks": [
                {
                    "trackId": "ncbi_gff_hg19",
                    "type": "LinearBasicDisplay",
                    "showLabels": "name",
                    "filter": [
                        "jexl:feature.type!='pseudogene'"
                    ],
                    "displayMode": "compact",
                    "height": 80
                },
                {
                    "trackId": "roadmap_chromhmm_multirow_hg19",
                    "type": "LinearMultiRowFeatureDisplay",
                    "facet": {
                        "field": "group",
                        "domain": [
                            "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"
                        ]
                    },
                    "height": 900
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg19 --loc chr9:34,700,000-38,420,000 \
  --track ncbi_gff_hg19 display:LinearBasicDisplay '{"showLabels":"name","filter":["jexl:feature.type!='\''pseudogene'\''"],"displayMode":"compact","height":80}' \
  --track roadmap_chromhmm_multirow_hg19 display:LinearMultiRowFeatureDisplay '{"facet":{"field":"group","domain":["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"]},"height":900}' \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr9:34,700,000-38,420,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "displayMode": "compact",
          "height": 80
        },
        {
          "trackId": "roadmap_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "facet": {
            "field": "group",
            "domain": [
              "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"
            ]
          },
          "height": 900
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "box",
    "anchor": {
      "trackId": "roadmap_chromhmm_multirow_hg19",
      "loc": "chr9:36,833,266-37,034,265"
    },
    "pad": 2
  },
  {
    "type": "text",
    "text": "PAX5 transcribed, with genic enhancers, in B cells only",
    "leader": true,
    "anchor": {
      "trackId": "roadmap_chromhmm_multirow_hg19",
      "loc": "chr9:36,900,000",
      "fracY": 0.3188976377952756
    },
    "dx": -260,
    "dy": -60
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --width 1500 --height 1230 \
  --timeout 180000 \
  --spec session.json --annotations callouts.json -o figure.png

The figure's clicks expand the legend to its full list, which this command does not do, so its picture differs there.

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Listing six epigenome names in rows.domain (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",
              "domain": [
                "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
          }
        ]
      }
    ]
  }
}
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",
            "domain": [
              "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
        }
      ]
    }
  ]
}
EOF

Advanced → Edit plot... in the track menu shows rows with its domain and kept as text and applies the same subset to an open track live.

Lung fibroblasts, foreskin fibroblasts and ES cells over HOXA. Lung fibroblasts keep HOXA1-A7 (red box) active and HOXA9-A13 (blue box) Polycomb-repressed, foreskin fibroblasts the reverse, and ES cells hold the whole cluster repressed.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%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%7B%22trackId%22%3A%22ncbi_gff_hg19%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22name%22%2C%22filter%22%3A%5B%22jexl%3Afeature.type%21%3D%27pseudogene%27%22%5D%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22roadmap_chromhmm_multirow_hg19%22%2C%22type%22%3A%22LinearMultiRowFeatureDisplay%22%2C%22rows%22%3A%7B%22field%22%3A%22cellType%22%2C%22domain%22%3A%5B%22NHLF+Lung+Fibroblast+Primary+Cells%22%2C%22IMR90+fetal+lung+fibroblasts+Cell+Line%22%2C%22Foreskin+Fibroblast+Primary+Cells+skin01%22%2C%22Foreskin+Fibroblast+Primary+Cells+skin02%22%2C%22H1+Cells%22%2C%22H9+Cells%22%5D%2C%22kept%22%3A%5B%22NHLF+Lung+Fibroblast+Primary+Cells%22%2C%22IMR90+fetal+lung+fibroblasts+Cell+Line%22%2C%22Foreskin+Fibroblast+Primary+Cells+skin01%22%2C%22Foreskin+Fibroblast+Primary+Cells+skin02%22%2C%22H1+Cells%22%2C%22H9+Cells%22%5D%7D%2C%22height%22%3A240%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+chromhmm_hoxa_fibroblasts

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg19)”.
    1. Track menu → Show... → Labels → Name only
    2. Track menu → Filter by... → add the expressionThis figure filters on feature.type!='pseudogene'.
  3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ChromHMM chromatin state (Roadmap, 127 epigenomes)”.
    1. Track menu → One row per... → cellTypeThe list is built from the attributes the loaded features carry, so a track whose data has not loaded yet offers nothing.
  4. Type your region of interest into the location box and press Enter.This figure is at chr7:27,110,000-27,265,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr7:27,110,000-27,265,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "height": 110
        },
        {
          "trackId": "roadmap_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "rows": {
            "field": "cellType",
            "domain": [
              "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
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr7:27,110,000-27,265,000",
            "tracks": [
                {
                    "trackId": "ncbi_gff_hg19",
                    "type": "LinearBasicDisplay",
                    "showLabels": "name",
                    "filter": [
                        "jexl:feature.type!='pseudogene'"
                    ],
                    "height": 110
                },
                {
                    "trackId": "roadmap_chromhmm_multirow_hg19",
                    "type": "LinearMultiRowFeatureDisplay",
                    "rows": {
                        "field": "cellType",
                        "domain": [
                            "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
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg19 --loc chr7:27,110,000-27,265,000 \
  --track ncbi_gff_hg19 display:LinearBasicDisplay '{"showLabels":"name","filter":["jexl:feature.type!='\''pseudogene'\''"],"height":110}' \
  --track roadmap_chromhmm_multirow_hg19 display:LinearMultiRowFeatureDisplay '{"rows":{"field":"cellType","domain":["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}' \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr7:27,110,000-27,265,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "height": 110
        },
        {
          "trackId": "roadmap_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "rows": {
            "field": "cellType",
            "domain": [
              "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
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "box",
    "anchor": {
      "trackId": "roadmap_chromhmm_multirow_hg19",
      "loc": "chr7:27,132,613-27,196,294"
    },
    "pad": 2
  },
  {
    "type": "box",
    "anchor": {
      "trackId": "roadmap_chromhmm_multirow_hg19",
      "loc": "chr7:27,202,056-27,246,878"
    },
    "pad": 2,
    "color": "#1565c0"
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --width 1500 --height 620 \
  --timeout 120000 \
  --spec session.json --annotations callouts.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

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.

Clustering the 127-epigenome ChromHMM track over HOXA. The rows open in Roadmap's tissue order; the track menu's Cluster rows by similarity re-lays them out into blocks and draws the dendrogram beside them.

Open the session the video starts in ↗, then take the steps it shows:

  1. Rows in Roadmap's tissue order: a clean tissue stripe, no blocks
  2. Cluster the epigenomes by their chromatin states
  3. Clustered: epigenomes with HOXA active, red, sit apart from those holding it repressed, grey

Open this view in JBrowse Web ↗ · Open this view in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fconfig_demo.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%22chr7%3A26%2C950%2C000-27%2C450%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_gff_hg19%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22name%22%2C%22filter%22%3A%5B%22jexl%3Afeature.type%21%3D%27pseudogene%27%22%5D%2C%22height%22%3A120%7D%2C%7B%22trackId%22%3A%22roadmap_chromhmm_multirow_hg19%22%2C%22type%22%3A%22LinearMultiRowFeatureDisplay%22%2C%22height%22%3A520%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+epigenomics%2Fchromhmm_cluster

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg19)”.
    1. Track menu → Show... → Labels → Name only
    2. Track menu → Filter by... → add the expressionThis figure filters on feature.type!='pseudogene'.
  3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ChromHMM chromatin state (Roadmap, 127 epigenomes)”.
  4. Type your region of interest into the location box and press Enter.This figure is at chr7:26,950,000-27,450,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_demo.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr7:26,950,000-27,450,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "height": 120
        },
        {
          "trackId": "roadmap_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 520
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/config_demo.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "chr7:26,950,000-27,450,000",
            "tracks": [
                {
                    "trackId": "ncbi_gff_hg19",
                    "type": "LinearBasicDisplay",
                    "showLabels": "name",
                    "filter": [
                        "jexl:feature.type!='pseudogene'"
                    ],
                    "height": 120
                },
                {
                    "trackId": "roadmap_chromhmm_multirow_hg19",
                    "type": "LinearMultiRowFeatureDisplay",
                    "height": 520
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --assembly hg19 --loc chr7:26,950,000-27,450,000 \
  --track ncbi_gff_hg19 display:LinearBasicDisplay '{"showLabels":"name","filter":["jexl:feature.type!='\''pseudogene'\''"],"height":120}' \
  --track roadmap_chromhmm_multirow_hg19 display:LinearMultiRowFeatureDisplay '{"height":520}' \
  --width 1920 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "chr7:26,950,000-27,450,000",
      "tracks": [
        {
          "trackId": "ncbi_gff_hg19",
          "type": "LinearBasicDisplay",
          "showLabels": "name",
          "filter": [
            "jexl:feature.type!='pseudogene'"
          ],
          "height": 120
        },
        {
          "trackId": "roadmap_chromhmm_multirow_hg19",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 520
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_demo.json \
  --width 1920 --height 892 \
  --spec session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

With 127 rows in one track a row is a few pixels tall and its label barely legible, so we group the rows by the 19 Roadmap tissue groups with three settings:

  • rowGroups tags each row with a group, taking one { match, group } per tissue, where match is a regex over the row names
  • facet "group" splits the display into stacked sections, one per tissue
  • rowColor with field: "group" is a color scale on each row's label bar that pairs each tissue with a color

The file's itemRgb still paints the blocks their state colors, so the tissue color appears on the label bar alone. Two of the nineteen tissues look like this:

{
  "rowGroups": [
    { "match": "^(Adipose Nuclei)$", "group": "Adipose" },
    {
      "match": "^(Aorta|Fetal Heart|Left Ventricle|Right Atrium|Right Ventricle)$",
      "group": "Heart"
    }
  ],
  "facet": "group",
  "rowColor": {
    "field": "group",
    "domain": ["Adipose", "Heart"],
    "range": ["#AF5B39", "#D56F80"]
  }
}

The GROUP and COLOR columns of EID_metadata.tab supply both lists. 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])
  | { rowGroups: map({ match: ("^(" + (map(.[4] | gsub("(?<c>[.()+*?\\[\\]^$|\\\\{}])"; "\\" + .c)) | join("|")) + ")$"),
                       group: .[0][1] }),
      rowColor: { field: "group", domain: map(.[0][1]), range: map(.[0][2]) } }' EID_metadata.tab > tissues.json

Merge the two keys of tissues.json into the display. 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.domain and leaves facet out, so clustering runs over all 127 together and the label bars show which tissues a cluster spans. The PAX5 figure adds facet with this domain, which stacks the groups in the paper's order:

{
  "facet": {
    "field": "group",
    "domain": [
      "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"
    ]
  }
}

The 19 groups in EID_metadata.tab include 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's ANATOMY column splits them finer, and TYPE sorts them by how the sample was collected.

Reproduce it end to end

One script does the whole path, build_chromhmm_multirow.sh:

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 URL

The script downloads the nine segmentation BEDs, merges, bgzips and tabixes them, downloads JBrowse, and writes the config.json above, opening on HOXA.

build_chromhmm_roadmap.sh builds the 127-epigenome track by the same merge. Roadmap's segmentations are bare BED4, so the script fills in what the ENCODE files had:

  1. paints each segment its state's color from colormap_15_coreMarks.tab, giving the merged file the itemRgb column that draws it
  2. 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
  3. 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.bed
curl -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/jbrowse2

EIDS picks a subset, here the four Roadmap re-analyses of the ENCODE lines in the nine-cell-type track. Leave it out for all 127, which takes about twenty minutes and ~12 GB of scratch.

See also