Pangenome (HPRC) part 1: the graph's alleles and the haplotypes that have them
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.
The Human Pangenome Reference Consortium's release 2 builds 464 human haplotypes into a pangenome graph; the phased VCF used here lists 462 of them. Where the haplotypes differ, the graph forms a bubble, and each route through a bubble is an allele. HPRC writes each haplotype's route through every bubble as a phased VCF, so a record lists which haplotypes have which allele. We open the graph and the VCF from the HPRC page on genomes.jbrowse.org as tracks of a linear view of GRCh38, and:
- read a whole chromosome, one node per bubble
- at C4 (complement genes), read the graph's backbone, bubbles and alleles
- at MHC class II, trace an allele beside HLA-DRB5 to the assembly it came from
- list every haplotype with that allele from the VCF
- back at C4, read the same alleles as aligned bases in HPRC's multiple alignment
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.
The graph and the page also leave real variation out, at some of the best-known loci in the genome. Read what they do not show before trusting an empty or simple picture.
Prerequisites
- the GraphGenomeView plugin. In your own JBrowse, install it from the plugin store; every launch from the HPRC page already loads it
- for the alignment on your own data: taffy
Where the data comes from
Nothing to download: the HPRC page's launches read the files of HPRC release 2, and our tabix index of its graph, by URL.
The files
- the structural-variant graph (
sv.gfa) the index files are cut from: https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.sv.gfa.gz - the phased VCF, one record per allele, 462 haplotypes: https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.pgbi.vcf.gz
- the multiple alignment of every haplotype against GRCh38: https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.full.maf.gz
Launching tracks from the HPRC page
Open the HPRC page. Click an
Examples entry, or type a gene symbol or a region such as
chr6:32,510,001-32,600,000 into the Gene or region box and press Show.
The page draws the window in JBrowse, with a row of buttons choosing what it
draws:
- Graph: the region drawn as a graph, with the structural variants each haplotype has under it
- Variants: the structural variants each haplotype has, over the genes
- Haplotypes: one lane per structural form, commonest first
- BandageJS: the same haplotypes in BandageJS
Open in full JBrowse opens the view shown in a tab of its own. Under the view, a sentence counts the structural forms the 464 haplotypes fall into in the window, and a Lane / Structure / Haplotypes / Share table names the haplotype that stands for each form, how the form differs from GRCh38 and how many share it. Haplotypes and BandageJS open those lanes. A window over 150 kb offers the graph alone.
What the graph and the page do not show
The examples are loci where at least one launch draws something readable. At other loci, a picture that looks simple or empty is often one of the cases below. We measured each on HPRC release 2.1 in October 2026.
- Near-identical duplications draw as a single thread. The graph puts the copies at RHD / RHCE and CYP2D6 on one path, so those examples offer no Graph launch. SMN1 / SMN2, SRGAP2 and the 8p23.1 beta-defensin cluster are not examples at all: the graph over each is a thread, and no launch showed their copy number. A gene-level graph is the better tool for that question.
- The graph does not align every haplotype everywhere. A haplotype the graph does not align across a window gets no lane, and the page counts them: "116 haplotypes are not aligned at any of them and have no lane" at FLNA / EMD, where those are the haplotypes without an X chromosome. Elsewhere the sequence exists in the assembly and the graph leaves it out. At NPHP1, 326 of the 462 haplotypes are aligned at two of the window's four sites and not at the rest, so the commonest lane reads "not aligned at 2 sites".
- The VCF has no record for the largest events. HPRC removes every site with an allele over 100 kb from the VCF and keeps the smaller sites nested inside it. The Variants launch therefore cannot show UGT2B17's 117 kb deletion, which 229 haplotypes have. AMY1, GYPA / GYPB, PRSS1 / PRSS2, UGT2B17 and NPHP1 offer no Variants launch, because the matrix over each is blank. The page's table restores those sites from the release's unfiltered VCF, so the table can name a deletion the Variants launch does not draw.
- The Structure column is a summary. A size is rounded to two figures, and a state fewer than 5 haplotypes have is folded into the commonest one. At a complex locus a row reads "14 size changes, largest a 10 kb deletion", which says little, and the HLA / MHC example has 34 forms of which the commonest holds 11% of haplotypes and the page lists 8. Two rows can have the same words for changes at different sites: four of PRSS1 / PRSS2's lanes read "20 kb insertion".
- A size in the table can be wrong where sites nest. A restored site's size is what the sites inside it leave unexplained. That subtraction checked out for 92.5% of the cases we could test and gave a size the haplotype does not have in 189, most of them at 8p23.1.
- Only the examples are checked. We looked at every launch of every example. A gene or region you type can still land where the graph is a thread or the VCF is blank, and the page will offer the launch anyway.
- No single launch shows the whole locus. The graph shows which sequence exists, the VCF which haplotypes have it, and the lanes how a few haplotypes are arranged. Reading a locus means opening more than one.
Overview of chr1 with one node per variant region
Press chr1 among the Whole chromosomes links under the box. Zoomed out
past the graph adapter's coarse level, JBrowse draws one node per bubble, so
the whole chromosome fits. A curve of segments per bubble (how many pieces of
sequence each bubble holds) shows how much the haplotypes disagree at each
locus.
Hosting your own graph builds this
overview and writes the coarse slot.
The C4 locus as a graph
Click the HLA / MHC example on the HPRC page, then Open in full JBrowse. The Graph view opens three tracks: genes, the graph in the force-directed layout, and under it a matrix of the structural variants each haplotype has, one row per haplotype. Then:
- Hide the variant matrix in the track selector, leaving the genes over the graph.
- Type
C4Ain the location box, pick the chr6 hit, and zoom out twice to take in C4B.
The graph has four kinds of object:
- the backbone is GRCh38's path, colored red to magenta by reference position
- a bubble is a place where haplotypes disagree
- an allele is a haplotype's sequence in place of the reference, drawn in charcoal because it has no reference position
- an edge that skips sequence is a deletion, drawn as a dashed arc
Opening the haplotype the HLA-DRB5 allele came from
Type chr6:32,500,000-32,560,000, a window in MHC class II, a cluster of
immune-system HLA genes. Beside HLA-DRB5, a charcoal node is an allele much
shorter than the backbone stretch it hangs across. Left-click it. Its details
give contributingHaplotype, NA20809#2: the graph's SN tag records which
assembly minigraph first took the allele from.
Open in appears when the session has an assembly named or aliased
sample#haplotype, the graph's name for it. The launch's config declares every
release 2 haplotype that way. To declare one, load its contig sizes (or FASTA)
under a display name, with the graph's name as an alias:
Goes in the assemblies array of config.json. See Assemblies.
{
"name": "NA20809.2",
"aliases": ["NA20809#2"],
"uri": "https://jbrowse.org/pangenome/hprc-grch38/NA20809.2.chrom.sizes"
}jbrowse add-assembly https://jbrowse.org/pangenome/hprc-grch38/NA20809.2.chrom.sizes \
--name NA20809.2 \
--alias "NA20809#2"Right-click the allele and take Open in NA20809.2. A second linear view opens below the first, on that haplotype's chromosome 6, framed on the allele with its CAT (Comparative Annotation Toolkit) gene annotation. Zoom out a few steps.
The haplotype's CAT annotation has HLA-DRB9 and HLA-DRB6 either side of the allele and no HLA-DRB5, the gene it hangs across on hg38.
Listing every haplotype with the HLA-DRB5 allele
The graph names one source assembly per allele. HPRC's phased VCF lists every haplotype's allele at every bubble: a record is one allele written against GRCh38, and each sample's genotype holds a 1 for each of its haplotypes with that allele. We'll add it to the graph launch's session:
Goes in the tracks array of config.json. See Tracks.
{
"type": "VariantTrack",
"trackId": "hprc2_pgbi_grch38",
"name": "HPRC release 2 phased VCF, one record per allele (462 haplotypes)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.pgbi.vcf.gz",
"fetchSizeLimit": 20000000
},
"displays": [
{
"type": "LinearMultiSampleVariantDisplay",
"unit": "haplotype",
"filter": ["jexl:alleleLength(feature)>=50"]
}
]
}jbrowse add-track-json '{
"type": "VariantTrack",
"trackId": "hprc2_pgbi_grch38",
"name": "HPRC release 2 phased VCF, one record per allele (462 haplotypes)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.pgbi.vcf.gz",
"fetchSizeLimit": 20000000
},
"displays": [
{
"type": "LinearMultiSampleVariantDisplay",
"unit": "haplotype",
"filter": ["jexl:alleleLength(feature)>=50"]
}
]
}'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": "VariantTrack",
"trackId": "hprc2_pgbi_grch38",
"name": "HPRC release 2 phased VCF, one record per allele (462 haplotypes)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "VcfTabixAdapter",
"uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.pgbi.vcf.gz",
"fetchSizeLimit": 20000000
},
"displays": [
{
"type": "LinearMultiSampleVariantDisplay",
"unit": "haplotype",
"filter": ["jexl:alleleLength(feature)>=50"]
}
]
}Open this track in JBrowse Web ↗
Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)
unit: "haplotype"draws one row per haplotype.filterdrops records, andalleleLength(feature)>=50keeps alleles of 50 bp and up, the size of the bubbles minigraph draws.alleleLengthis the length of the record's longest allele, so it counts an insertion's inserted bases.fetchSizeLimitraises the download cap past its default. The VCF spells out each inserted allele, which puts the MHC class II window over the default.- Filter by... → Edit filters... in the track menu shows the filter and changes it.
- Advanced → Edit plot... in the track menu shows
unitandfilteras text and applies edits live.
Take Clustering → Cluster rows by genotype... in the track menu and press Run clustering. The rows reorder so haplotypes with the same alleles sit together, with a dendrogram beside them.
Right-click the charcoal allele beside HLA-DRB5 in the force-directed graph and take Highlight in hg38: a band marks the span of GRCh38 it replaces, which covers most of HLA-DRB5.
The VCF holds the HLA-DRB5 allele as four records, one for each of its sequences, which differ by a base or two. The blue block under the band is the haplotypes with any of the four, plus a smaller block with an 86 kb deletion that removes the whole stretch.
Reading C4's alleles as aligned bases
HPRC also publishes its alignment as hprc-v2.1-mc-grch38.full.maf.gz, a
multiple alignment with one row of bases per haplotype. A .tai index beside
the 53 GB file makes a locus one ranged read:
Goes in the tracks array of config.json. See Tracks.
{
"type": "MafTrack",
"trackId": "hprc_v2_1_mc_grch38",
"name": "HPRC release 2 pangenome alignment (464 haplotypes)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BgzipMafAdapter",
"uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.full.maf.gz"
}
}jbrowse add-track-json '{
"type": "MafTrack",
"trackId": "hprc_v2_1_mc_grch38",
"name": "HPRC release 2 pangenome alignment (464 haplotypes)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BgzipMafAdapter",
"uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.full.maf.gz"
}
}'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": "MafTrack",
"trackId": "hprc_v2_1_mc_grch38",
"name": "HPRC release 2 pangenome alignment (464 haplotypes)",
"assemblyNames": ["hg38"],
"adapter": {
"type": "BgzipMafAdapter",
"uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.1/hprc-v2.1-mc-grch38/hprc-v2.1-mc-grch38.full.maf.gz"
}
}Open this track in JBrowse Web ↗
Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)
The uri shorthand resolves the sibling .tai. For a MAF of your own, taffy
writes the index beside it:
# writes alignment.maf.gz.tai, which the adapter finds by its name
taffy index -i alignment.maf.gzGo back to the C4 window, chr6:31,980,000-32,050,000, with the genes, the VCF
and this alignment over the graph track. A white stretch in an alignment row is
sequence that haplotype lacks. Then:
- Clustering → Cluster rows by genotype... on the VCF orders its rows.
- Clustering → Cluster rows by identity... on the alignment clusters over the window in view, because HPRC's file ships no guide tree.
- Reset row order restores the order in the file.
The VCF's widest blue block is one record, a deletion of a whole C4-CYP21-TNX module, which is the dashed arc in the C4 graph. Every alignment row in the white block has that deletion in the VCF. The narrower blocks are the 6.4 kb HERV-K (endogenous retrovirus) insertion in a C4 gene's intron, the difference between a long and a short C4. The configured track draws all the alignment rows.
Reproduce it end to end
Hosting your own graph builds the
index files and the bubbles track in one command that runs on any rGFA. Run on
hprc-v2.1-mc-grch38.sv.gfa.gz, it writes the files we host, and
README.txt beside them records
their provenance. For a graph of your own, minigraph can list each assembly's
route through every bubble; see
Which haplotypes pass through each segment.
See also
- Tutorial: Pangenome (HPRC) part 2: haplotypes against each other
- Tutorial: Pangenome (HPRC) part 3: repeat lengths across haplotypes
- Tutorial: Pangenome (hosting your own graph)
- Tutorial: Pangenome (mouse)
- Tutorial: Pangenome (cattle)
- User guide: Graph genome view
- User guide: Multi-sample variant display
- User guide: MAF track
External links
- Li H.
The rGFA format and
gfatools, which define the
SN/SO/SRtags this page opens the graph by, and whosebubblesubcommand calls the bubbles it reads. - taffy, which writes the
.taiindex that makes the alignment addressable by locus.
Citations
- HPRC release 2, the release this
page opens: the Minigraph-Cactus graph, the multiple alignment and the VCFs
vg deconstructwrites from the graph.
Feedback on this tutorial is welcome: contact us.