Skip to main content

The HPRC pangenome on genomes.jbrowse.org

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

The Human Pangenome Reference Consortium's release 2 builds 464 human haplotypes into one graph, which records where they differ in structure: a deleted gene, an extra copy, an inverted stretch. The hosted page staging.genomes.jbrowse.org/pangenomes/hprc lists twenty loci where they do and opens JBrowse on each one, as the graph, as the callset or as one lane per haplotype. Everything it opens is already built and served.

Experimental

The graph view is a beta plugin, so the pangenome pages live on staging, staging.genomes.jbrowse.org, rather than on genomes.jbrowse.org, until JBrowse 5 ships: the plugin needs a build newer than the released hosts. Every page link below is a staging link. We welcome your feedback.

Prerequisites

  • nothing to install: this is a click-path through a hosted page and the sessions it launches
  • to build the graph indexes yourself, or to add the same tracks to your own JBrowse, take the HPRC pangenome tutorial instead; every launch below opens a config it describes

Where the data comes from

Everything the page opens comes from HPRC release 2.

The locus table

Open the HPRC page. Under a row of whole-chromosome links, the Loci table gives each locus its gene cluster, the kind of variation it is known for and its GRCh38 region, and ends the row in its launches:

  • graph: the locus as a graph, under a linear view of the same window
  • variants: the callset as a haplotype matrix beside the RefSeq genes, which part 2 reads
  • haplotypes: one lane per structural configuration the callset finds at the locus
  • gene hub: genomes.jbrowse.org's ortholog explorer for the locus's gene
The HPRC page: the whole-chromosome links, then the head of the locus table, where each row ends in its launches. The RHD / RHCE and SMN1 / SMN2 rows open only the callset and the gene hub. The boxed link is the graph launch the next section follows. Open the HPRC page ↗

Each launch opens a window of at most 150 kb at the locus, where the graph draws segment by segment. RHD / RHCE, SMN1 / SMN2 and CYP2D6 have no graph launch, because minigraph merges their near-identical copies onto one path.

A locus as a graph

Press graph on the HLA / MHC row. The session is two panels. Above, a linear view with the RefSeq genes, the bubbles lane, the allele inventory and the rGFA segments. Below, the graph, colored along the reference from red at the window's start to magenta at its end, with a segment that has no reference coordinate in charcoal. Hovering a node highlights its segment in the lane above, and the reverse.

The MHC class II window from the graph launch: RefSeq genes, bubbles, the allele inventory and the rGFA segments above, and the same window as a force-directed graph below, on the reference-position ramp, with the genes drawn along the backbone and each bubble haloed and labelled. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

The steps behind the figure above, run against your own data.

  1. Open pane 1: Add → Linear genome view.
  2. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).Pane 1 — This figure uses hg38.
  3. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hg38_ncbiRefSeq_ucsc” track.
  4. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hprc_minigraph_bubbles” track.
  5. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hprc_minigraph_alleles” track.
  6. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hprc_minigraph_segments” track.
  7. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr6:32510000-32600000.
  8. Click the view's title in its header and enter "HLA / MHC graph"Pane 2.
  9. Track menu (on the graph segments track) → Launch → Graph genome view (this region)Launching from the track is what ties the two panels together: the graph is cut from the same file the lane above it draws.Pane 2.
  10. Set the location box before launching the graph view.The cut is the window the linear view was showing, so the graph covers what you were looking at.Pane 2.
  11. Graph view toolbar → Color → Reference positionPane 2.

Some settings have no written step yet — see the Session spec tab.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fpangenome%2Fhprc-grch38%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22id%22%3A%22pangenome-locus-lgv%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr6%3A32510000-32600000%22%2C%22tracks%22%3A%5B%22hg38_ncbiRefSeq_ucsc%22%2C%22hprc_minigraph_bubbles%22%2C%22hprc_minigraph_alleles%22%2C%22hprc_minigraph_segments%22%5D%7D%2C%7B%22type%22%3A%22GraphGenomeView%22%2C%22displayName%22%3A%22HLA+%2F+MHC+graph%22%2C%22loadedTrackId%22%3A%22hprc_minigraph_segments%22%2C%22loadedRegion%22%3A%7B%22refName%22%3A%22chr6%22%2C%22start%22%3A32510000%2C%22end%22%3A32600000%2C%22assemblyName%22%3A%22hg38%22%7D%2C%22connectedViewId%22%3A%22pangenome-locus-lgv%22%2C%22colorScheme%22%3A%22reference-position%22%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgenomes_hprc_mhc_graph

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "id": "pangenome-locus-lgv",
      "assembly": "hg38",
      "loc": "chr6:32510000-32600000",
      "tracks": [
        "hg38_ncbiRefSeq_ucsc",
        "hprc_minigraph_bubbles",
        "hprc_minigraph_alleles",
        "hprc_minigraph_segments"
      ]
    },
    {
      "type": "GraphGenomeView",
      "displayName": "HLA / MHC graph",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr6",
        "start": 32510000,
        "end": 32600000,
        "assemblyName": "hg38"
      },
      "connectedViewId": "pangenome-locus-lgv",
      "colorScheme": "reference-position"
    }
  ]
}

Loaded against config: https://jbrowse.org/pangenome/hprc-grch38/config.json

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "id": "pangenome-locus-lgv",
      "assembly": "hg38",
      "loc": "chr6:32510000-32600000",
      "tracks": [
        "hg38_ncbiRefSeq_ucsc",
        "hprc_minigraph_bubbles",
        "hprc_minigraph_alleles",
        "hprc_minigraph_segments"
      ]
    },
    {
      "type": "GraphGenomeView",
      "displayName": "HLA / MHC graph",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr6",
        "start": 32510000,
        "end": 32600000,
        "assemblyName": "hg38"
      },
      "connectedViewId": "pangenome-locus-lgv",
      "colorScheme": "reference-position"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/pangenome/hprc-grch38/config.json \
  --session 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.

Inside the session, the segments track's menu has Launch → Graph genome view (this region), and rubberbanding a span offers Graph genome view (this selection), so a zoomed-in window reopens as a graph without the page. The graph reaches back the same way. Hovering a node bands its interval across the lanes above, right-clicking one offers Highlight in hg38 and Open in hg38, and the view's own Launch menu reopens the whole window as a linear view. The HPRC tutorial walks a node back to its coordinates.

A whole chromosome

The Whole chromosome links above the table open the same two panels over a whole chromosome. Past 150 kb the launch swaps the segment-level lanes for the bubble tier the HPRC tutorial builds with build_bubble_tier.sh, one node per top-level bubble, and a curve of segments per bubble. At that scale the curve shows where the graph varies, and the tier lane places each bubble. Part 2 walks a whole chromosome at that scale.

A locus's haplotypes

Press haplotypes on the CFH / CFHR row. The session opens the RefSeq genes over one lane per haplotype. Each lane is that haplotype's walk, read out of the graph's gbz-base database in the browser and drawn in its own contig coordinates, and ribbons join each lane to the one above. The page chose the haplotypes from the callset: haplotypes with identical genotypes at every structural site in the window share a configuration, and each lane stands for one configuration, largest group first, up to eight.

The largest configuration at this locus skips the common CFHR3-CFHR1 deletion (Hughes et al. 2006). Lanes → Choose lanes... in the track menu swaps in any other haplotype the graph names. A row with no haplotypes launch is a locus whose window holds no top-level structural site in the callset.

💡 See also

Part 3 opens the same lane track on four deletion carriers and four non-carriers, each drawing its own gene models.

The other two graphs

Each graph on staging has its own page in the same shape: chromosome links, a locus table and a files table. /pangenomes/mouse is 18 inbred and wild-derived strains on GRCm39, and /pangenomes/bovine is the taurine, indicine, yak, bison and gaur super-pangenome on ARS-UCD1.2. The pangenomes landing page links all three. Their loci come from the graph itself, ranked by segment count, and neither page has a haplotypes launch. The mouse graph was built with minigraph, which writes no haplotype paths, so it has no callset: its rows open bubbles where the others open variants. The mouse and cattle tutorials build those two.

Adding the same tracks to your own instance

The graph and haplotypes launches open https://jbrowse.org/pangenome/hprc-grch38/config.json, a plain JBrowse config, and the variants launch opens genomes.jbrowse.org's own hg38 config with the callset added as a session track. The HPRC pangenome tutorial walks each track, and you can write the session-spec URLs the page builds by hand. A graph launch is a LinearGenomeView with an id, and a GraphGenomeView carrying loadedTrackId, loadedRegion and connectedViewId naming that id. A haplotypes launch is a LinearGenomeView whose hprc_v2_1_gbz_lanes track carries laneFilter and domain, both listing the panel's haplotypes.

See also

References