Skip to main content

Pangenome (HPRC): who carries each allele

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

A pangenome graph stores each allele once, credited to the first assembly that contributed it, so the graph alone cannot say who else carries it. The Human Pangenome Reference Consortium's release 2 publishes that answer beside its graph as a callset, one genotype per haplotype for all 464, and we open both from the consortium's page on genomes.jbrowse.org at the MHC class II locus. We:

  • cluster the callset's haplotypes by the alleles they share
  • find who carries the HLA-DRB5 allele in the callset and the graph at once
  • read carriage at the graph's own granularity
  • check both against the multiple alignment they come from, and settle a 1q21.1 inversion the graph cannot

Browsing the graph traces that allele to the one haplotype the graph credits it to.

Prerequisites

  • the GraphGenomeView plugin, which the HPRC page's graph launches load; both callsets are a URL any JBrowse reads with no plugin

Where the data comes from

The data is HPRC release 2. JBrowse reads its callsets and its multiple alignment directly from S3, and reads the bubble projections from our host.

The variant callset

Open the HPRC page and press variants on the HLA / MHC row. JBrowse opens on the MHC class II window, chr6:32,510,001-32,600,000, with the release's decomposed callset as a matrix of haplotypes. Indexed alongside the 2.3 GB VCF, the track is this config:

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

{
  "type": "VariantTrack",
  "trackId": "hprc2_wave_grch38",
  "name": "HPRC2 pangenome",
  "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.wave.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "renderingMode": "phased"
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "hprc2_wave_grch38",
  "name": "HPRC2 pangenome",
  "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.wave.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "renderingMode": "phased"
    }
  ]
}'

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_wave_grch38",
  "name": "HPRC2 pangenome",
  "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.wave.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "renderingMode": "phased"
    }
  ]
}

renderingMode: "phased" splits each sample into its two haplotypes, one row each. The launch filters the fully decomposed VCF to the structural tier; open the track menu's Edit filters to read it:

jexl:feature.INFO.LV[0]==0 && alleleLength(feature)>=50

alleleLength is the longest allele the record describes, over end - start since an insertion consumes no reference; LV==0 keeps the top-level sites of vg's snarl tree, so a nested child does not paint twice.

Open the track menu again and take Clustering → Cluster rows by genotype..., then Run clustering: the rows reorder by genotype similarity with a dendrogram beside them, and haplotypes that share alleles gather into blocks.

The 464-haplotype lane clustered from the track menu: Clustering, Cluster rows by genotype, Run clustering, and the rows arriving in their new order with a dendrogram beside them. Open the session this video starts in ↗

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

  1. Cluster the 464 haplotypes by genotype

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fhprc.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr6%3A32%2C510%2C000-32%2C600%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hg38_ncbiRefSeq_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22displayMode%22%3A%22compact%22%2C%22height%22%3A60%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_segments%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22none%22%2C%22heightMode%22%3A%22grow%22%2C%22color%22%3A%22jexl%3Aget%28feature%2C%27rank%27%29%3E0+%3F+%27rgb%2860%2C65%2C72%29%27+%3A+%27hsl%28%27+%2B+min%28300%2C+max%280%2C+%28%28get%28feature%2C%27start%27%29%2Bget%28feature%2C%27end%27%29%29%2F2+-+32510000%29+%2F+90000+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%7D%2C%7B%22trackId%22%3A%22hprc2_wave_grch38%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22height%22%3A340%2C%22jexlFilters%22%3A%5B%22jexl%3Afeature.INFO.LV%5B0%5D%3D%3D0+%26%26+alleleLength%28feature%29%3E%3D50%22%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_cluster_callset

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).This figure uses hg38.
  2. Add your own track: File → Open track..., then 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 (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (60px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Show... → Labels → None
    2. Track menu → Feature height → Track sizing → Fixed feature height + autogrow track height
    3. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
    1. Drag the bar at the bottom edge of the track to resize it (340px here).
    2. Track menu → Filter by... → add the expressionThis figure filters on feature.INFO.LV[0]==0 && alleleLength(feature)>=50.
  5. Type your region of interest into the location box and press Enter.This figure is at chr6:32,510,000-32,600,000.

Open this view in JBrowse Web ↗

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38.
  2. Add your own track: File → Open track..., then 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 (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (60px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Show... → Labels → None
    2. Track menu → Feature height → Track sizing → Fixed feature height + autogrow track height
    3. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
    1. Drag the bar at the bottom edge of the track to resize it (340px here).
    2. Track menu → Filter by... → add the expressionThis figure filters on feature.INFO.LV[0]==0 && alleleLength(feature)>=50.
  5. Type your region of interest into the location box and press Enter.This figure is at chr6:32,510,000-32,600,000.

This session spec draws the figure from test_data/graphgenomeview/hprc.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:32,510,000-32,600,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 60
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "heightMode": "grow",
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 32510000) / 90000 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 340,
          "jexlFilters": [
            "jexl:feature.INFO.LV[0]==0 && alleleLength(feature)>=50"
          ]
        }
      ]
    }
  ]
}

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",
      "assembly": "hg38",
      "loc": "chr6:32,510,000-32,600,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 60
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "heightMode": "grow",
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 32510000) / 90000 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 340,
          "jexlFilters": [
            "jexl:feature.INFO.LV[0]==0 && alleleLength(feature)>=50"
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.json \
  --width 1920 --height 750 \
  --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.

The graph beside the callset

minigraph collapses variation under about 50 bp, so the callset filtered to 50 bp and up holds the same tier as the graph. The graph records an allele and its length, the callset who carries it.

Press graph on the same HLA / MHC row for the graph track under the genes, the bubbles and the allele inventory. Turn on HPRC2 pangenome callset (464 haplotypes) from the track selector and filter it as before, admitting the HLA-DRB5 deletion by position since vcfwave nests it one level down:

jexl:(feature.INFO.LV[0]==0 || feature.start==32517421) && alleleLength(feature)>=50

Cluster it, hide the bubbles and the allele inventory, pick Layout → Force-directed layout, and right-click the charcoal allele beside HLA-DRB5 for Highlight in hg38.

One window, both products. The band is the HLA-DRB5 deletion site from the callset, over every haplotype clustered by genotype: grey where a haplotype matches the reference, teal where it carries the alt allele, magenta for another alt. Below, the force-directed graph, where an arrow runs from the band to the same deletion as the graph draws it, alleles in charcoal. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fhprc.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr6%3A32%2C510%2C000-32%2C600%2C000%22%2C%22highlight%22%3A%5B%226%3A32%2C517%2C422-32%2C529%2C435%22%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hg38_ncbiRefSeq_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22displayMode%22%3A%22compact%22%2C%22height%22%3A60%7D%2C%7B%22trackId%22%3A%22hprc2_wave_grch38%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22height%22%3A340%2C%22jexlFilters%22%3A%5B%22jexl%3A%28feature.INFO.LV%5B0%5D%3D%3D0+%7C%7C+feature.start%3D%3D32517421%29+%26%26+alleleLength%28feature%29%3E%3D50%22%5D%2C%22runClustering%22%3Atrue%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22maxRegionBp%22%3A99001%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_graph_vs_callset

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).This figure uses hg38.
  2. Add your own track: File → Open track..., then 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 (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (60px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
    1. Drag the bar at the bottom edge of the track to resize it (340px here).
    2. Track menu → Filter by... → add the expressionThis figure filters on (feature.INFO.LV[0]==0 || feature.start==32517421) && alleleLength(feature)>=50.
    3. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Drag the bar at the bottom edge of the track to resize it (600px here).
  5. Type your region of interest into the location box and press Enter.This figure is at chr6:32,510,000-32,600,000.
  6. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

Open this view in JBrowse Web ↗

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38.
  2. Add your own track: File → Open track..., then 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 (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (60px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
    1. Drag the bar at the bottom edge of the track to resize it (340px here).
    2. Track menu → Filter by... → add the expressionThis figure filters on (feature.INFO.LV[0]==0 || feature.start==32517421) && alleleLength(feature)>=50.
    3. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Drag the bar at the bottom edge of the track to resize it (600px here).
  5. Type your region of interest into the location box and press Enter.This figure is at chr6:32,510,000-32,600,000.
  6. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

This session spec draws the figure from test_data/graphgenomeview/hprc.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:32,510,000-32,600,000",
      "highlight": [
        "6:32,517,422-32,529,435"
      ],
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 60
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 340,
          "jexlFilters": [
            "jexl:(feature.INFO.LV[0]==0 || feature.start==32517421) && alleleLength(feature)>=50"
          ],
          "runClustering": true
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "maxRegionBp": 99001,
          "height": 600
        }
      ]
    }
  ]
}

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",
      "assembly": "hg38",
      "loc": "chr6:32,510,000-32,600,000",
      "highlight": [
        "6:32,517,422-32,529,435"
      ],
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 60
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 340,
          "jexlFilters": [
            "jexl:(feature.INFO.LV[0]==0 || feature.start==32517421) && alleleLength(feature)>=50"
          ],
          "runClustering": true
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "maxRegionBp": 99001,
          "height": 600
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.json \
  --width 1000 --height 1340 \
  --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.

Carriage at the graph's own granularity

vcfwave splits a snarl's alleles into smaller records, so a callset record need not line up with a bubble. Release 2 also publishes the undecomposed form, one record per snarl, as the pgbi.vcf.gz beside each build: read it to find who carries a given bubble, since its rows are the graph's own alleles. Add it to the same session:

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

{
  "type": "VariantTrack",
  "trackId": "hprc2_pgbi_grch38",
  "name": "HPRC2 pangenome carriage (snarl-level, 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"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "renderingMode": "phased"
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "hprc2_pgbi_grch38",
  "name": "HPRC2 pangenome carriage (snarl-level, 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"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "renderingMode": "phased"
    }
  ]
}'

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": "HPRC2 pangenome carriage (snarl-level, 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"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "renderingMode": "phased"
    }
  ]
}

Apply the same LV==0 filter from Edit filters, and the lane cuts to the tier the graph's bubbles hold, matched to a bubble by interval.

The alignment underneath both

The graph and the callset both derive from the multiple alignment, and release 2.1 publishes it too: hprc-v2.1-mc-grch38.full.maf.gz, 53 GB, beside a .tai index written by taffy that makes a locus one ranged read:

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

{
  "type": "MafTrack",
  "trackId": "hprc_v2_0_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_0_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_0_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"
  }
}

The uri shorthand resolves the sibling .tai. Release 2.0 publishes the same alignment as a 5.9 GB TAF, read by BgzipTaffyAdapter with the same shorthand: a quarter of the bytes per locus, but an earlier build with more underalignment and unpatched centromeres.

Type the C4 window, chr6:31,980,000-32,050,000, and show three lanes over the graph track: the genes, the filtered callset and this alignment. A row that drops out belongs to a haplotype that does not carry that segment.

Order the rows with Clustering → Cluster rows by genotype... on the callset and Clustering → Cluster rows by identity... on the alignment (computed over the window in view, since HPRC's file ships no guide tree); Reset row order puts back the file's own order.

C4 on one axis: the RefSeq genes, the callset's haplotypes clustered by genotype, a subtree of them as alignment rows clustered by identity, white where a haplotype has no aligned sequence, and the graph track drawing the window force-directed. The band marks the pseudogene pair between C4A and C4B, and the haplotypes with no sequence across the module gather into one block. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fhprc.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22ncbi_genes_hg38_ucsc%22%2C%22name%22%3A%22NCBI+RefSeq+%28UCSC%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22Gff3TabixAdapter%22%2C%22gffGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fhg38.gff.gz%22%2C%22locationType%22%3A%22UriLocation%22%7D%2C%22index%22%3A%7B%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fhg38.gff.gz.csi%22%2C%22locationType%22%3A%22UriLocation%22%7D%2C%22indexType%22%3A%22CSI%22%7D%7D%7D%2C%7B%22type%22%3A%22MafTrack%22%2C%22trackId%22%3A%22hprc_v2_0_mc_grch38%22%2C%22name%22%3A%22HPRC+release+2+pangenome+alignment+%28464+haplotypes%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22BgzipMafAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fhuman-pangenomics%2Fpangenomes%2Ffreeze%2Frelease2%2Fminigraph-cactus%2Fv2.1%2Fhprc-v2.1-mc-grch38%2Fhprc-v2.1-mc-grch38.full.maf.gz%22%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr6%3A31%2C980%2C000-32%2C050%2C000%22%2C%22highlight%22%3A%5B%22chr6%3A32%2C005%2C691-32%2C011%2C057%22%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ncbi_genes_hg38_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22heightMode%22%3A%22grow%22%7D%2C%7B%22trackId%22%3A%22hprc2_wave_grch38%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22height%22%3A240%2C%22runClustering%22%3Atrue%7D%2C%7B%22trackId%22%3A%22hprc_v2_0_mc_grch38%22%2C%22type%22%3A%22LinearMafDisplay%22%2C%22rows%22%3A%7B%22kept%22%3A%5B%22GRCh38%22%2C%22CHM13.1%22%2C%22CHM13.2%22%2C%22HG00097.1%22%2C%22HG00097.2%22%2C%22HG00099.1%22%2C%22HG00099.2%22%2C%22HG00126.1%22%2C%22HG00126.2%22%2C%22HG00128.1%22%2C%22HG00128.2%22%2C%22HG00133.1%22%2C%22HG00133.2%22%2C%22HG00140.1%22%2C%22HG00140.2%22%2C%22HG00146.1%22%2C%22HG00146.2%22%2C%22HG002.1%22%2C%22HG002.2%22%2C%22HG00232.1%22%2C%22HG00232.2%22%2C%22HG00235.1%22%2C%22HG00235.2%22%2C%22HG00253.1%22%2C%22HG00253.2%22%2C%22HG00280.1%22%2C%22HG00280.2%22%2C%22HG00290.1%22%2C%22HG00290.2%22%2C%22HG00320.1%22%2C%22HG00320.2%22%2C%22HG00321.1%22%2C%22HG00321.2%22%5D%7D%2C%22runClustering%22%3Atrue%2C%22showBranchLength%22%3Afalse%2C%22rowProportion%22%3A1%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22showBubbles%22%3Afalse%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+maf_hprc_pangenome

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).This figure uses hg38.
  2. Add your own track: File → Open track..., then 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 (UCSC)”.
    1. Track menu → Show only genes (checked)
    2. Track menu → Gene glyph → Representative transcript
    3. Track menu → Feature height → Track sizing → Fixed feature height + autogrow track height
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
    1. Drag the bar at the bottom edge of the track to resize it (240px here).
    2. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 pangenome alignment (464 haplotypes)”.
    1. Track menu → Edit colors/arrangement... → untick the rows you do not wantThis figure keeps 33 rows. The dendrogram is pruned to match, so it stays the tree of what is drawn.
    2. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
    3. Track menu → Row heightEach preset there sets the row height and the glyph's share of it (1 here) together, so this follows from the same click as the height above.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Mark bubbles (unchecked)
    4. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr6:31,980,000-32,050,000.
  7. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

Open this view in JBrowse Web ↗

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38.
  2. Add your own track: File → Open track..., then 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 (UCSC)”.
    1. Track menu → Show only genes (checked)
    2. Track menu → Gene glyph → Representative transcript
    3. Track menu → Feature height → Track sizing → Fixed feature height + autogrow track height
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
    1. Drag the bar at the bottom edge of the track to resize it (240px here).
    2. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 pangenome alignment (464 haplotypes)”.
    1. Track menu → Edit colors/arrangement... → untick the rows you do not wantThis figure keeps 33 rows. The dendrogram is pruned to match, so it stays the tree of what is drawn.
    2. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
    3. Track menu → Row heightEach preset there sets the row height and the glyph's share of it (1 here) together, so this follows from the same click as the height above.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Mark bubbles (unchecked)
    4. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr6:31,980,000-32,050,000.
  7. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "ncbi_genes_hg38_ucsc",
  "name": "NCBI RefSeq (UCSC)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "https://jbrowse.org/ucsc/hg38/hg38.gff.gz",
      "locationType": "UriLocation"
    },
    "index": {
      "location": {
        "uri": "https://jbrowse.org/ucsc/hg38/hg38.gff.gz.csi",
        "locationType": "UriLocation"
      },
      "indexType": "CSI"
    }
  }
}'

jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "hprc_v2_0_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"
  }
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hg38 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Spec tab, or jbrowse set-default-session.

This session spec draws the figure from test_data/graphgenomeview/hprc.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "ncbi_genes_hg38_ucsc",
      "name": "NCBI RefSeq (UCSC)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/ucsc/hg38/hg38.gff.gz",
          "locationType": "UriLocation"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/ucsc/hg38/hg38.gff.gz.csi",
            "locationType": "UriLocation"
          },
          "indexType": "CSI"
        }
      }
    },
    {
      "type": "MafTrack",
      "trackId": "hprc_v2_0_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"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:31,980,000-32,050,000",
      "highlight": [
        "chr6:32,005,691-32,011,057"
      ],
      "tracks": [
        {
          "trackId": "ncbi_genes_hg38_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "geneGlyphMode": "longestCoding",
          "heightMode": "grow"
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 240,
          "runClustering": true
        },
        {
          "trackId": "hprc_v2_0_mc_grch38",
          "type": "LinearMafDisplay",
          "rows": {
            "kept": [
              "GRCh38",
              "CHM13.1",
              "CHM13.2",
              "HG00097.1",
              "HG00097.2",
              "HG00099.1",
              "HG00099.2",
              "HG00126.1",
              "HG00126.2",
              "HG00128.1",
              "HG00128.2",
              "HG00133.1",
              "HG00133.2",
              "HG00140.1",
              "HG00140.2",
              "HG00146.1",
              "HG00146.2",
              "HG002.1",
              "HG002.2",
              "HG00232.1",
              "HG00232.2",
              "HG00235.1",
              "HG00235.2",
              "HG00253.1",
              "HG00253.2",
              "HG00280.1",
              "HG00280.2",
              "HG00290.1",
              "HG00290.2",
              "HG00320.1",
              "HG00320.2",
              "HG00321.1",
              "HG00321.2"
            ]
          },
          "runClustering": true,
          "showBranchLength": false,
          "rowProportion": 1
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "showBubbles": false,
          "height": 600
        }
      ]
    }
  ]
}

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'
{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "ncbi_genes_hg38_ucsc",
      "name": "NCBI RefSeq (UCSC)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/ucsc/hg38/hg38.gff.gz",
          "locationType": "UriLocation"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/ucsc/hg38/hg38.gff.gz.csi",
            "locationType": "UriLocation"
          },
          "indexType": "CSI"
        }
      }
    },
    {
      "type": "MafTrack",
      "trackId": "hprc_v2_0_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"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:31,980,000-32,050,000",
      "highlight": [
        "chr6:32,005,691-32,011,057"
      ],
      "tracks": [
        {
          "trackId": "ncbi_genes_hg38_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "geneGlyphMode": "longestCoding",
          "heightMode": "grow"
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 240,
          "runClustering": true
        },
        {
          "trackId": "hprc_v2_0_mc_grch38",
          "type": "LinearMafDisplay",
          "rows": {
            "kept": [
              "GRCh38",
              "CHM13.1",
              "CHM13.2",
              "HG00097.1",
              "HG00097.2",
              "HG00099.1",
              "HG00099.2",
              "HG00126.1",
              "HG00126.2",
              "HG00128.1",
              "HG00128.2",
              "HG00133.1",
              "HG00133.2",
              "HG00140.1",
              "HG00140.2",
              "HG00146.1",
              "HG00146.2",
              "HG002.1",
              "HG002.2",
              "HG00232.1",
              "HG00232.2",
              "HG00235.1",
              "HG00235.2",
              "HG00253.1",
              "HG00253.2",
              "HG00280.1",
              "HG00280.2",
              "HG00290.1",
              "HG00290.2",
              "HG00320.1",
              "HG00320.2",
              "HG00321.1",
              "HG00321.2"
            ]
          },
          "runClustering": true,
          "showBranchLength": false,
          "rowProportion": 1
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "showBubbles": false,
          "height": 600
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.json \
  --width 1500 --height 1850 \
  --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.

The figure keeps thirty-two haplotype rows so each has the height for its name beside it; the track as configured above draws every haplotype.

Inversions

An inversion is the same reference sequence, walked backwards. gfatools bubble flags it as an inversion boolean when a bubble's paths disagree about orientation. Show the bubbles lane again, open Edit filters, and enter:

jexl:feature.inversion

Type chr1:144,260,000-144,610,000, the 1q21.1 locus. The lane's one flagged bubble cannot distinguish a polymorphic inversion from an inverted paralog in a segmental duplication, and the graph draws its breakpoints as two deletion arcs since its edges carry no orientation. The alignments settle it: the figure below comes from build_hprc_inversion_synteny.sh under Reproduce it end to end, which classifies every haplotype at the bubble from HPRC's all-vs-GRCh38 PAF and slices out a carrier and a non-carrier, each with its CAT annotation. The hg38 row between them agrees with the non-carrier.

The 1q21.1 bubble the graph flags as an inversion, drawn as alignments. The pink ribbons are each haplotype's alignment to hg38, and a ribbon that crosses itself is an inversion. Between the two haplotype rows are the RefSeq genes, the bubble lane cut to inversion-flagged bubbles, and the rGFA segments. The boxed pair on each row is PPIAL4F and PPIAL4E, in opposite orders on the two haplotypes. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session.

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fhprc.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%5B%22hprc_inv_synteny_HG01891_1%22%5D%2C%5B%22hprc_inv_synteny_HG02698_2%22%5D%5D%2C%22drawCurves%22%3Atrue%2C%22cigarMode%22%3A%22off%22%2C%22levelHeights%22%3A%5B150%2C90%5D%2C%22collapseEmptyRows%22%3Atrue%2C%22views%22%3A%5B%7B%22assembly%22%3A%22HG01891.1%22%2C%22loc%22%3A%22JAGYVO020000062.1%3A6%2C437%2C000-6%2C868%2C942%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hprc_inv_genes_HG01891_1%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22displayMode%22%3A%22compact%22%2C%22height%22%3A70%7D%5D%7D%2C%7B%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%3A144%2C260%2C000-144%2C610%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr1%22%2C%22start%22%3A144419292%2C%22end%22%3A144572458%2C%22color%22%3A%22rgba%2860%2C65%2C72%2C0.10%29%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hg38_ncbiRefSeq_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22displayMode%22%3A%22compact%22%2C%22height%22%3A70%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22jexlFiltersSetting%22%3A%5B%22jexl%3Afeature.inversion%22%5D%2C%22height%22%3A60%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_segments%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22none%22%2C%22heightMode%22%3A%22fit%22%2C%22color%22%3A%22jexl%3Aget%28feature%2C%27rank%27%29%3E0+%3F+%27rgb%2860%2C65%2C72%29%27+%3A+%27hsl%28%27+%2B+min%28300%2C+max%280%2C+%28%28get%28feature%2C%27start%27%29%2Bget%28feature%2C%27end%27%29%29%2F2+-+144260000%29+%2F+350000+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%2C%22height%22%3A45%7D%5D%7D%2C%7B%22assembly%22%3A%22HG02698.2%22%2C%22loc%22%3A%22JBHDTM010000033.1%3A3%2C912%2C000-4%2C309%2C991%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hprc_inv_genes_HG02698_2%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22displayMode%22%3A%22compact%22%2C%22height%22%3A70%7D%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_inversion

With your own data, the steps behind the figure:

  1. Open your genomes: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one), then File → Open genome... for each of the rest.This figure's rows, top to bottom: HG01891.1, hg38, HG02698.2.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file. This one needs a PAF file (.paf).A synteny track the session already has is quicker: pick it under Quick start, which fills in the rows itself.This figure uses “HG01891.1 vs GRCh38 at 1q21.1 (HPRC release 2 alignment)”.
  4. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file. This one needs a PAF file (.paf).This figure uses “HG02698.2 vs GRCh38 at 1q21.1 (HPRC release 2 alignment)”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Synteny display settings (the sliders button in the view header) → CIGAR indels → Off - don't draw CIGAR indelsThe row appears only when the alignments actually carry CIGAR ops — a coarse-tier PIF or a CIGAR-less PAF has none to draw.
  8. Drag the bar below a synteny level to resize it.This figure's 2 levels are 150, 90px tall.
  9. Row 1 (HG01891.1)
    1. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “HG01891.1 genes (HPRC release 2 CAT annotation)”.
      1. Track menu → Gene glyph → Representative transcript
      2. Track menu → Feature height → Compact
      3. Drag the bar at the bottom edge of the track to resize it (70px here).
    2. Type your region of interest into the location box and press Enter.This figure is at JAGYVO020000062.1:6,437,000-6,868,942.
  10. Row 2 (hg38)
    1. Add your own track: open this view's track selector, click + and choose Add track, then 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 (hg38)”.
      1. Track menu → Gene glyph → Representative transcript
      2. Track menu → Feature height → Compact
      3. Drag the bar at the bottom edge of the track to resize it (70px here).
    2. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
      1. Track menu → Filter by... → add the expressionThis figure filters on feature.inversion.
      2. Drag the bar at the bottom edge of the track to resize it (60px here).
    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.This figure uses “HPRC release 2 graph (rGFA segments)”.
      1. Track menu → Show... → Labels → None
      2. Track menu → Feature height → Track sizing → Fit feature height to track height
      3. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
      4. Drag the bar at the bottom edge of the track to resize it (45px here).
    4. Type your region of interest into the location box and press Enter.This figure is at chr1:144,260,000-144,610,000.
    5. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.
  11. Row 3 (HG02698.2)
    1. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “HG02698.2 genes (HPRC release 2 CAT annotation)”.
      1. Track menu → Gene glyph → Representative transcript
      2. Track menu → Feature height → Compact
      3. Drag the bar at the bottom edge of the track to resize it (70px here).
    2. Type your region of interest into the location box and press Enter.This figure is at JBHDTM010000033.1:3,912,000-4,309,991.

Open this view in JBrowse Web ↗

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genomes in your JBrowse Web's config.json: run jbrowse add-assembly once for each.This figure's rows, top to bottom: HG01891.1, hg38, HG02698.2.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file. This one needs a PAF file (.paf).A synteny track the session already has is quicker: pick it under Quick start, which fills in the rows itself.This figure uses “HG01891.1 vs GRCh38 at 1q21.1 (HPRC release 2 alignment)”.
  4. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file. This one needs a PAF file (.paf).This figure uses “HG02698.2 vs GRCh38 at 1q21.1 (HPRC release 2 alignment)”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Synteny display settings (the sliders button in the view header) → CIGAR indels → Off - don't draw CIGAR indelsThe row appears only when the alignments actually carry CIGAR ops — a coarse-tier PIF or a CIGAR-less PAF has none to draw.
  8. Drag the bar below a synteny level to resize it.This figure's 2 levels are 150, 90px tall.
  9. Row 1 (HG01891.1)
    1. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “HG01891.1 genes (HPRC release 2 CAT annotation)”.
      1. Track menu → Gene glyph → Representative transcript
      2. Track menu → Feature height → Compact
      3. Drag the bar at the bottom edge of the track to resize it (70px here).
    2. Type your region of interest into the location box and press Enter.This figure is at JAGYVO020000062.1:6,437,000-6,868,942.
  10. Row 2 (hg38)
    1. Add your own track: open this view's track selector, click + and choose Add track, then 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 (hg38)”.
      1. Track menu → Gene glyph → Representative transcript
      2. Track menu → Feature height → Compact
      3. Drag the bar at the bottom edge of the track to resize it (70px here).
    2. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
      1. Track menu → Filter by... → add the expressionThis figure filters on feature.inversion.
      2. Drag the bar at the bottom edge of the track to resize it (60px here).
    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.This figure uses “HPRC release 2 graph (rGFA segments)”.
      1. Track menu → Show... → Labels → None
      2. Track menu → Feature height → Track sizing → Fit feature height to track height
      3. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
      4. Drag the bar at the bottom edge of the track to resize it (45px here).
    4. Type your region of interest into the location box and press Enter.This figure is at chr1:144,260,000-144,610,000.
    5. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.
  11. Row 3 (HG02698.2)
    1. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “HG02698.2 genes (HPRC release 2 CAT annotation)”.
      1. Track menu → Gene glyph → Representative transcript
      2. Track menu → Feature height → Compact
      3. Drag the bar at the bottom edge of the track to resize it (70px here).
    2. Type your region of interest into the location box and press Enter.This figure is at JBHDTM010000033.1:3,912,000-4,309,991.

This session spec draws the figure from test_data/graphgenomeview/hprc.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": [
        [
          "hprc_inv_synteny_HG01891_1"
        ],
        [
          "hprc_inv_synteny_HG02698_2"
        ]
      ],
      "drawCurves": true,
      "cigarMode": "off",
      "levelHeights": [
        150,
        90
      ],
      "collapseEmptyRows": true,
      "views": [
        {
          "assembly": "HG01891.1",
          "loc": "JAGYVO020000062.1:6,437,000-6,868,942",
          "tracks": [
            {
              "trackId": "hprc_inv_genes_HG01891_1",
              "type": "LinearBasicDisplay",
              "geneGlyphMode": "longestCoding",
              "displayMode": "compact",
              "height": 70
            }
          ]
        },
        {
          "assembly": "hg38",
          "loc": "chr1:144,260,000-144,610,000",
          "highlight": [
            {
              "refName": "chr1",
              "start": 144419292,
              "end": 144572458,
              "color": "rgba(60,65,72,0.10)"
            }
          ],
          "tracks": [
            {
              "trackId": "hg38_ncbiRefSeq_ucsc",
              "type": "LinearBasicDisplay",
              "geneGlyphMode": "longestCoding",
              "displayMode": "compact",
              "height": 70
            },
            {
              "trackId": "hprc_minigraph_bubbles",
              "type": "LinearBasicDisplay",
              "jexlFiltersSetting": [
                "jexl:feature.inversion"
              ],
              "height": 60
            },
            {
              "trackId": "hprc_minigraph_segments",
              "type": "LinearBasicDisplay",
              "showLabels": "none",
              "heightMode": "fit",
              "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 144260000) / 350000 * 300)) + ',70%,50%)'",
              "height": 45
            }
          ]
        },
        {
          "assembly": "HG02698.2",
          "loc": "JBHDTM010000033.1:3,912,000-4,309,991",
          "tracks": [
            {
              "trackId": "hprc_inv_genes_HG02698_2",
              "type": "LinearBasicDisplay",
              "geneGlyphMode": "longestCoding",
              "displayMode": "compact",
              "height": 70
            }
          ]
        }
      ]
    }
  ]
}

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": "LinearSyntenyView",
      "tracks": [
        [
          "hprc_inv_synteny_HG01891_1"
        ],
        [
          "hprc_inv_synteny_HG02698_2"
        ]
      ],
      "drawCurves": true,
      "cigarMode": "off",
      "levelHeights": [
        150,
        90
      ],
      "collapseEmptyRows": true,
      "views": [
        {
          "assembly": "HG01891.1",
          "loc": "JAGYVO020000062.1:6,437,000-6,868,942",
          "tracks": [
            {
              "trackId": "hprc_inv_genes_HG01891_1",
              "type": "LinearBasicDisplay",
              "geneGlyphMode": "longestCoding",
              "displayMode": "compact",
              "height": 70
            }
          ]
        },
        {
          "assembly": "hg38",
          "loc": "chr1:144,260,000-144,610,000",
          "highlight": [
            {
              "refName": "chr1",
              "start": 144419292,
              "end": 144572458,
              "color": "rgba(60,65,72,0.10)"
            }
          ],
          "tracks": [
            {
              "trackId": "hg38_ncbiRefSeq_ucsc",
              "type": "LinearBasicDisplay",
              "geneGlyphMode": "longestCoding",
              "displayMode": "compact",
              "height": 70
            },
            {
              "trackId": "hprc_minigraph_bubbles",
              "type": "LinearBasicDisplay",
              "jexlFiltersSetting": [
                "jexl:feature.inversion"
              ],
              "height": 60
            },
            {
              "trackId": "hprc_minigraph_segments",
              "type": "LinearBasicDisplay",
              "showLabels": "none",
              "heightMode": "fit",
              "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 144260000) / 350000 * 300)) + ',70%,50%)'",
              "height": 45
            }
          ]
        },
        {
          "assembly": "HG02698.2",
          "loc": "JBHDTM010000033.1:3,912,000-4,309,991",
          "tracks": [
            {
              "trackId": "hprc_inv_genes_HG02698_2",
              "type": "LinearBasicDisplay",
              "geneGlyphMode": "longestCoding",
              "displayMode": "compact",
              "height": 70
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.json \
  --width 1000 --height 965 \
  --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.

Reproduce it end to end

Hosting your own graph builds the bubbles lane in one command that runs on any rGFA; pointed at hprc-v2.1-mc-grch38.sv.gfa.gz, it writes the files we host, and README.txt beside them records their provenance.

We do not rebuild carriage here, since HPRC publishes it as a file. Rebuilding it takes a 464-assembly download and a mapping run, one call per sample:

# --call asks, at every bubble, which path this assembly takes through the graph
minigraph -cxasm --call -t"$(nproc)" graph.gfa assembly.fa > sample.call.bed

build_minigraph_paths.sh wraps that call in the per-sample loop and the join, and the same page walks through the script.

A separate script builds the inversion figure from release 2's published all-vs-GRCh38 PAF:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_hprc_inversion_synteny.sh
bash build_hprc_inversion_synteny.sh  # writes ./hprc_inversion_synteny_build/

build_hprc_inversion_synteny.sh keeps the haplotypes whose alignments reverse the block while the flanks stay forward, then slices out one haplotype of each kind: the alignment, the contig length and the CAT genes.

See also

References

  • HPRC release 2, the release this page opens: the Minigraph-Cactus graph, the multiple alignment and the two callsets deconstructed from it.
  • Li H. The rGFA format and gfatools, whose bubble subcommand calls the bubbles this page reads.
  • taffy, which writes the .tai index that makes the alignment addressable by locus.