Pangenome (HPRC) part 2: haplotypes against each other

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.20. Desktop beta builds for Linux and macOS are on the releases page; the Windows build waits on code signing.

We draw human haplotypes from the Human Pangenome Reference Consortium's release 2 side by side, one lane per haplotype drawn in that haplotype's assembly coordinates, and use the pangenome graph to show where neighbouring lanes match. We look at three loci: CFH, where some haplotypes lack two genes; GSTT1, a gene GRCh38's chromosome lacks; and FLNA / EMD, two genes some haplotypes have in the opposite order. We:

configure the haplotype lanes track, and read each lane's genes from that haplotype's own annotation
at CFH, open the lanes from the HPRC page's Haplotypes launch
at GSTT1, read how the launch stacks the lanes by structure
at FLNA / EMD, add the graph's bubbles track and filter it to inversions
at IGL, choose lanes by name from the Lanes menu

Experimental

The graph view is a beta plugin, and the HPRC page launches it on the JBrowse 5 development build until JBrowse 5 ships. We welcome your feedback.

A lane shows only what the graph aligned, and some haplotypes get no lane at all. Read what the lanes leave out before reading an absent or empty lane as a deletion.

Prerequisites

the GraphGenomeView plugin, for the GraphTrack below. In your own JBrowse, install it from the plugin store; the HPRC page's launches and the hosted config already load it

The data

You don't need these files to follow the page: the HPRC launches read the hosted tabix indexes, built from these files of HPRC release 2. Reproduce it end to end names the build. The config under Configuring the haplotype lanes track is the one to adapt for your own graph.

What it is	File
The release's minigraph-cactus graph as a GFA	hprc-v2.1-mc-grch38.gfa.gz
The assemblies	assemblies_release2_v1.0.index.csv
The CAT gene annotation index, one GFF3 per haplotype	cat_genes_hprc_r2_v1.3.index.csv

Read by URL (no download needed)

What it is	File
Our tabix index files of the graph's haplotype walks and bubbles, with the exact build recorded beside them	README.txt

Configuring the haplotype lanes track

One track draws the lanes, reading each haplotype's walk from tabix-indexed files we built from the release's graph. The HPRC page's Haplotypes launch adds it, and the config below is the one to adapt for your own graph:

A lane is one haplotype's walk, which lists in order the nodes that haplotype passes through.
assemblyNames starts with the anchor, the assembly the walk file's reference is loaded as. A haplotype needs no entry: its lane draws on an assembly whose sample#haplotype alias matches it (HG00097.1 is aliased HG00097#1), which one assembly entry declares, and a haplotype with no assembly is still a lane.
assemblyNameToPanSN names the walk of an assembly with no such alias, here GRCh38's.
The walk files for a graph of your own come from Hosting your own graph.

Config file

Goes in the tracks array of config.json. See Tracks.

{
  "type": "GraphTrack",
  "trackId": "hprc_v2_1_walk_lanes",
  "name": "HPRC v2.1 haplotypes vs GRCh38, read from the walk files",
  "assemblyNames": ["hg38", "HG00097.1", "HG00099.1"],
  "adapter": {
    "type": "WalkTabixSyntenyAdapter",
    "walksUri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38-f5s.GRCh38",
    "assemblyNames": ["hg38"],
    "assemblyNameToPanSN": { "hg38": "GRCh38#0" }
  },
  "displays": [
    { "type": "MultiWaySyntenyDisplay", "height": 600 },
    { "type": "LinearGraphDisplay" }
  ]
}

CLI (add-track-json)

jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "hprc_v2_1_walk_lanes",
  "name": "HPRC v2.1 haplotypes vs GRCh38, read from the walk files",
  "assemblyNames": ["hg38", "HG00097.1", "HG00099.1"],
  "adapter": {
    "type": "WalkTabixSyntenyAdapter",
    "walksUri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38-f5s.GRCh38",
    "assemblyNames": ["hg38"],
    "assemblyNameToPanSN": { "hg38": "GRCh38#0" }
  },
  "displays": [
    { "type": "MultiWaySyntenyDisplay", "height": 600 },
    { "type": "LinearGraphDisplay" }
  ]
}'

In the app

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": "GraphTrack",
  "trackId": "hprc_v2_1_walk_lanes",
  "name": "HPRC v2.1 haplotypes vs GRCh38, read from the walk files",
  "assemblyNames": ["hg38", "HG00097.1", "HG00099.1"],
  "adapter": {
    "type": "WalkTabixSyntenyAdapter",
    "walksUri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38-f5s.GRCh38",
    "assemblyNames": ["hg38"],
    "assemblyNameToPanSN": { "hg38": "GRCh38#0" }
  },
  "displays": [
    { "type": "MultiWaySyntenyDisplay", "height": 600 },
    { "type": "LinearGraphDisplay" }
  ]
}

Where each haplotype's genes come from

JBrowse draws each lane, and each bar under Walk rows, with the genes of that haplotype's own assembly, at its own coordinates. It does not lift GRCh38's genes across the graph.

The source: HPRC annotated each release 2 assembly but HG002's with CAT (the Comparative Annotation Toolkit), which projects GENCODE's GRCh38 genes onto it, in the CAT index above. HG002's two haplotypes are the Q100 assembly hg002v1.1, whose project annotated it with RefSeq's genes through JHU's Liftoff; we keep each gene's MANE Select transcript there, so a few symbols and isoforms differ from the CAT lanes. Liftoff leaves out the functional V, D and J segments of the antibody and T-cell receptor loci, so HG002's lanes there show only their pseudogene segments.
What we host: one gene model per named gene for each haplotype, as https://jbrowse.org/pangenome/hprc-grch38/genes/<sample>.<haplotype>.genes.bed.gz, chosen by these rules:
- Each model is the gene's Ensembl canonical transcript as CAT projected it, else its longest coding transcript.
- A gene with no symbol is dropped, and so is one spanning over 5 Mb.
- Where CAT projected two paralogs onto one locus, such as GSTM1 onto GSTM2, we keep the gene whose GRCh38 span the haplotype's walk crosses there, in the -f5s walk file the lanes read.
- CAT misses genes that only GRCh38's alternate contigs hold. We splice GENCODE's models of GSTT1, LILRA3, HLA-DRB3, HLA-DRB4 and HLA-DRB5 onto each haplotype's assembly instead, where its walk crosses them.
- README.txt beside the files gives every rule and what CAT still misses.
How a lane finds them: each haplotype is an assembly, such as HG00097.1 aliased HG00097#1, holding one track, CAT genes (HG00097 haplotype 1, HPRC release 2), or for HG002 RefSeq genes via JHU Liftoff v0.6. JBrowse draws that track in the haplotype's lane, and for each of the first 40 walk-row bars reads it over the bar's span on the haplotype's contig and boxes each gene where it falls along the bar.
Reading them:
- A gene missing from a lane is missing from that haplotype's annotation, through a deletion, a copy CAT did not project, or a gene the rules above dropped.
- CAT names each copy of a duplicated gene after the GRCh38 copy it projected, so a haplotype with extra AMY1 copies reads AMY1C several times. The number of AMY1 boxes gives the copy number, unless CAT missed a copy.

CFH: haplotypes missing two genes

Open the HPRC page and click the CFH / CFHR example, the complement factor H gene cluster. Under More about this window, click Haplotypes, which opens the lanes under the NCBI RefSeq genes (hg38), Known alleles and GWAS Catalog (NHGRI-EBI) tracks:

Each structural form gets lanes, more for a commoner form, and each lane's header counts the haplotypes that share its form.
A lane missing CFHR3 and CFHR1 (Hughes et al. 2006) opens a hole across both, under the Known alleles row naming the deletion.

The CFH cluster from the Haplotypes launch. The lanes missing CFHR3 and CFHR1 open a hole across both.

GSTT1: a gene GRCh38's chromosome lacks

GRCh38's chromosome 22 has the common GSTT1 deletion, so the gene sits on an alternate contig and no chr22 track draws it. Click the GSTT1 example on the HPRC page, then Haplotypes under More about this window:

The lanes stack by structure, each beside the one whose deletions and insertions against GRCh38 are most alike, so the lanes of one form sit together.
The band between two lanes aligns the two haplotypes on the nodes both walks share, and fans open where the lower lane has sequence the upper lacks.

GSTT1 from the Haplotypes launch, its lanes stacked by structure.

FLNA / EMD: two genes in the opposite order

FLNA and EMD sit between two inverted repeats on Xq28, and the block between them is inverted on many X chromosomes (Small et al. 1997). Click the FLNA / EMD example on the HPRC page, then Haplotypes under More about this window. Then:

The band between two lanes crosses itself, in blue, where the lower lane runs the block in the other direction, and an inverted lane's header names the inversion.
HPRC release 2 bubbles in the track selector adds the graph's bubbles. gfatools bubble flags one as inversion when its paths disagree about orientation.
Filter by → Edit filters... on that track keeps the flagged ones with this filter:
```
jexl:feature.inversion
```

FLNA / EMD from the Haplotypes launch, with the bubbles track filtered to inversions. The band crosses in blue where the inverted lanes meet the lanes in GRCh38's orientation.

What the lanes leave out

Five cases mislead in the lanes:

A haplotype the graph does not align has no lane of its own. Picked by hand under Lanes → Choose lanes..., it gets an empty row at the foot headed "no alignment in this window".
A stretch the haplotype skips across the window is a row with no ribbons. A haplotype with no step on the reference across the whole window shows as a row at the foot of the lanes, headed with the stretch's length, such as "no step on the reference across 150 kb". The row comes from the -f5s walk file's skip rows, so it appears only where the window lies in a 64 kb chunk the skip covers whole, for a skip up to about 2 Mb. A window in the skip's first or last chunk shows no row for that haplotype. Walk rows, which part 3 opens, draw the same haplotype as a row with no step on the reference. At IGH, IGK and IGL such a row is often the cell line's deletion, as part 1's limits explain.
A lane can stop partway, at the end of the graph's alignment of that haplotype; its sequence can run on past it.
One lane stands for many haplotypes. The page groups haplotypes into structural forms by their structural variants of 50 bp or more, so two haplotypes in one form can still differ in everything smaller.
Near-identical gene copies share one path, so where the graph merges the copies, as at SMN1 / SMN2, a lane cannot show how many copies a haplotype has.

Lanes → Choose lanes... picks lanes by name, for a haplotype the launch did not seat. At IGL, from any Haplotypes launch, type chr22:22,800,001-22,850,000 and choose HG00099.1, HG002.1, HG00097.1, HG002.2 and HG01074.1, which puts two skip rows at the foot.

IGL in five lanes. HG002 haplotype 2 and HG01074 haplotype 1 have no step on the reference across the window, so their rows at the foot draw no ribbons and are headed with the length of the stretch. HG002 haplotype 1 walks the window but draws only MIR650 and IGLV3-7, since its Liftoff annotation leaves out functional V segments.

Reproduce it end to end

Indexing haplotype walks builds the walk files the lanes read, with one command on the release's GFA, and README.txt beside the hosted files records their provenance. The same page converts the walks to PAF for a whole-genome synteny view.

External links

Li H. gfatools, whose bubble subcommand flags the inversion.
gfa-to-tabix, which files each haplotype's walk under the reference so a window is one range request.
ggbandage, which draws RHD and CYP2D6 deletions as arches over GRCh38 in ggplot2.
ggtubemap, which draws haplotypes against each other as a tube map in ggplot2, colored by phase.

Citations

HPRC release 2, the release whose graph, assemblies and CAT annotations this page reads.
Hughes et al. (2006). A common CFH haplotype, with deletion of CFHR1 and CFHR3, is associated with lower risk of age-related macular degeneration
Small et al. (1997). Emerin deletion reveals a common X-chromosome inversion mediated by inverted repeats

Feedback on this tutorial is welcome: contact us.

Pangenome (HPRC) part 2: haplotypes against each other

Prerequisites#

The data#

Configuring the haplotype lanes track#

Where each haplotype's genes come from#

CFH: haplotypes missing two genes#

GSTT1: a gene GRCh38's chromosome lacks#

FLNA / EMD: two genes in the opposite order#

What the lanes leave out#

Reproduce it end to end#

See also#

External links#

Citations#