Skip to main content

Pangenome (HPRC) part 3, every haplotype in its own coordinates

Parts 1 and 2 draw everything on GRCh38's axis, which makes hundreds of haplotypes comparable in one lane and leaves each assembly's own coordinates out of the picture. We start from the multiple alignment both products were derived from, then put each haplotype back on its own contigs straight out of the graph, and end on the one donor that has a published reference of its own.

Prerequisites

  • part 1, whose session this page adds to: hg38 with its genes, and the rGFA segments track loaded on it
  • the GraphGenomeView plugin, for the track that uses GbzBaseSyntenyAdapter and part 1's segments track; every other track here is a URL you can paste
  • bcftools, to genotype the panel out of the callset

Where the data comes from

HPRC release 2, whose multiple alignment and gbz-base database are read straight off S3, beside T2T-CHM13 from UCSC and the companion index we host.

The alignment and the assemblies

The graph as a walk database

T2T-CHM13

The alignment the graph and callset came from

The graph and the callset are both derived from the multiple alignment, and release 2 publishes that too: hprc-v2.0-mc-grch38.full.taf.gz, 5.9 GB, 464 haplotypes, beside a .tai index written by taffy. The index makes it addressable, so a locus is a ranged read rather than a download:

{
  "type": "MafTrack",
  "trackId": "hprc_v2_0_mc_grch38",
  "name": "HPRC release 2 pangenome alignment (464 haplotypes)",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "BgzipTaffyAdapter",
    "uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.0/hprc-v2.0-mc-grch38/hprc-v2.0-mc-grch38.full.taf.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": "BgzipTaffyAdapter",
    "uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.0/hprc-v2.0-mc-grch38/hprc-v2.0-mc-grch38.full.taf.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": "BgzipTaffyAdapter",
    "uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.0/hprc-v2.0-mc-grch38/hprc-v2.0-mc-grch38.full.taf.gz"
  }
}

The uri shorthand resolves the sibling .tai, which downloads once. The same alignment is published as a 53 GB MAF under v2.1/, which BgzipMafAdapter reads with the same shorthand, and the v2.0 TAF is the build the graph and the callset come from. The figure below puts all three products on one axis.

The C4 locus on one axis: the NCBI RefSeq genes, the graph's rGFA segments, the callset's haplotypes clustered by genotype, a subtree of those haplotypes as alignment rows clustered by identity, and the same window as a force-directed subgraph. The band marks the pseudogene pair between C4A and C4B, where the haplotypes that carry nothing there gather into a block. 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. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).Pane 1 — This figure uses “NCBI RefSeq (UCSC)”.
  4. Track menu → Show only genes (checked)Pane 1 · “NCBI RefSeq (UCSC)”.
  5. Track menu → Gene glyph → Representative transcriptPane 1 · “NCBI RefSeq (UCSC)”.
  6. Track menu → Set feature height → Track sizing → Fixed feature height + autogrow track heightPane 1 · “NCBI RefSeq (UCSC)”.
  7. 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 “HPRC release 2 graph (rGFA segments)”.
  8. Track menu → Show... → Labels → NonePane 1 · “HPRC release 2 graph (rGFA segments)”.
  9. Track menu → Set feature height → Track sizing → Fixed feature height + autogrow track heightPane 1 · “HPRC release 2 graph (rGFA segments)”.
  10. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a per-attribute palette, and the strand preset only, so an expression of any other shape is authored on the track config.Pane 1 · “HPRC release 2 graph (rGFA segments)”.
  11. 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 VCF (.vcf.gz + .tbi).Pane 1 — This figure uses “HPRC2 pangenome callset (464 haplotypes)”.
  12. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “HPRC2 pangenome callset (464 haplotypes)”.
  13. 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.Pane 1 · “HPRC2 pangenome callset (464 haplotypes)”.
  14. 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 “HPRC release 2 pangenome alignment (464 haplotypes)”.
  15. Track menu → Edit row 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.Pane 1 · “HPRC release 2 pangenome alignment (464 haplotypes)”.
  16. 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.Pane 1 · “HPRC release 2 pangenome alignment (464 haplotypes)”.
  17. 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.Pane 1 · “HPRC release 2 pangenome alignment (464 haplotypes)”.
  18. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr6:31,972,057-32,055,418.
  19. 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.Pane 1.
  20. 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.
  21. 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.
  22. Graph view toolbar → Layout → Force-directed layoutPane 2.
  23. 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=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%22BgzipTaffyAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fs3-us-west-2.amazonaws.com%2Fhuman-pangenomics%2Fpangenomes%2Ffreeze%2Frelease2%2Fminigraph-cactus%2Fv2.0%2Fhprc-v2.0-mc-grch38%2Fhprc-v2.0-mc-grch38.full.taf.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%2C972%2C057-32%2C055%2C418%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%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+-+31972056%29+%2F+83362+*+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%3A240%2C%22runClustering%22%3Atrue%7D%2C%7B%22trackId%22%3A%22hprc_v2_0_mc_grch38%22%2C%22type%22%3A%22LinearMafDisplay%22%2C%22subtreeFilter%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%2C%22runClustering%22%3Atrue%2C%22showBranchLength%22%3Afalse%2C%22rowProportion%22%3A1%7D%5D%7D%2C%7B%22type%22%3A%22GraphGenomeView%22%2C%22loadedTrackId%22%3A%22hprc_minigraph_segments%22%2C%22loadedRegion%22%3A%7B%22refName%22%3A%22chr6%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A31972056%2C%22end%22%3A32055418%7D%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%7D%5D%7D&sessionName=JBrowse+docs%3A+maf_hprc_pangenome

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": "BgzipTaffyAdapter",
    "uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.0/hprc-v2.0-mc-grch38/hprc-v2.0-mc-grch38.full.taf.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 Session spec tab, or jbrowse set-default-session.

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

{
  "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": "BgzipTaffyAdapter",
        "uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.0/hprc-v2.0-mc-grch38/hprc-v2.0-mc-grch38.full.taf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:31,972,057-32,055,418",
      "highlight": [
        "chr6:32,005,691-32,011,057"
      ],
      "tracks": [
        {
          "trackId": "ncbi_genes_hg38_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "geneGlyphMode": "longestCoding",
          "heightMode": "grow"
        },
        {
          "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 - 31972056) / 83362 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 240,
          "runClustering": true
        },
        {
          "trackId": "hprc_v2_0_mc_grch38",
          "type": "LinearMafDisplay",
          "subtreeFilter": [
            "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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr6",
        "assemblyName": "hg38",
        "start": 31972056,
        "end": 32055418
      },
      "layoutMode": "force",
      "colorScheme": "reference-position"
    }
  ]
}

Loaded against config: test_data/graphgenomeview/hprc.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr6:31,972,057-32,055,418",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "Gff3TabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "RgfaTabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track_3",
    "name": "My track 3",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "VcfTabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "MafTrack",
    "trackId": "my_track_4",
    "name": "My track 4",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "BgzipTaffyAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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": "BgzipTaffyAdapter",
        "uri": "https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/release2/minigraph-cactus/v2.0/hprc-v2.0-mc-grch38/hprc-v2.0-mc-grch38.full.taf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:31,972,057-32,055,418",
      "highlight": [
        "chr6:32,005,691-32,011,057"
      ],
      "tracks": [
        {
          "trackId": "ncbi_genes_hg38_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "geneGlyphMode": "longestCoding",
          "heightMode": "grow"
        },
        {
          "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 - 31972056) / 83362 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "hprc2_wave_grch38",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 240,
          "runClustering": true
        },
        {
          "trackId": "hprc_v2_0_mc_grch38",
          "type": "LinearMafDisplay",
          "subtreeFilter": [
            "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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr6",
        "assemblyName": "hg38",
        "start": 31972056,
        "end": 32055418
      },
      "layoutMode": "force",
      "colorScheme": "reference-position"
    }
  ]
}
JSON

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

The locus is C4, the example HPRCv2 itself opens with. Every alignment row is a human haplotype, so a row that drops out belongs to a person who does not carry that segment. Read down a column for who carries what, across for where each segment starts and stops.

Clustering the alignment is a run, since HPRC's file ships no guide tree to order its rows by. Cluster rows by identity... under the track menu's Clustering submenu computes it over the window in view, and Reset row order puts back whatever the file supplied. 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.

The MAF track guide covers the conservation band, per-row identity and codon view, all derived from the alignment with no extra files.

Every haplotype's walk, straight from the graph

The alignment above draws each haplotype on GRCh38's axis. A multi-way synteny track is the other reading: one lane per haplotype, each in that assembly's own contig coordinates and carrying that assembly's own CAT gene models. The graph already states what the lanes need. A .gbz holds one walk per haplotype, and release 2.1 publishes that graph as a gbz-base database, the graph in SQLite with its tables laid out so a window is a handful of range requests. Every graph-derived track on this page reads release 2.1, so a segment id in the rGFA tracks and a node id in this database are the same graph's.

Picking the panel out of the callset

Eight haplotypes carry the stack at the CFH cluster. build_hprc_cfhr_synteny.sh genotypes the CFHR3/CFHR1 deletion over all 464 haplotypes and keeps the homozygous samples whose own CAT annotation agrees with the genotype:

# the site as the callset states it. One record with two ALTs here, so the
# deletion allele is the one far shorter than the REF span rather than the one
# at a fixed index.
bcftools view -r chr1:196753075-196753075 -Oz -o cfhr_site.vcf.gz "$WAVE"

HG01109, HG01123, HG01960 and HG02055 carry the deletion; HG00097, HG00099, HG00128 and HG00133 do not. The script also slices each one's CAT annotation to the window, and those are the gene models the lanes draw.

The lanes from the database

{
  "type": "SyntenyTrack",
  "trackId": "hprc_v2_1_gbz_lanes",
  "name": "HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)",
  "assemblyNames": [
    "hg38",
    "HG00097.1",
    "HG00099.1",
    "HG00128.1",
    "HG00133.1",
    "HG01109.1",
    "HG01123.1",
    "HG01960.1",
    "HG02055.1"
  ],
  "adapter": {
    "type": "GbzBaseSyntenyAdapter",
    "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.gbz.db",
    "haplotypeIndexLocation": {
      "uri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.haplotype-index.anchored.db"
    },
    "assemblyNames": ["hg38"],
    "assemblyNameToPanSN": {
      "hg38": "GRCh38#0",
      "HG00097.1": "HG00097#1",
      "HG00099.1": "HG00099#1",
      "HG00128.1": "HG00128#1",
      "HG00133.1": "HG00133#1",
      "HG01109.1": "HG01109#1",
      "HG01123.1": "HG01123#1",
      "HG01960.1": "HG01960#1",
      "HG02055.1": "HG02055#1"
    },
    "context": 1000,
    "nodeLimit": 50000
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "hprc_v2_1_gbz_lanes-MultiWaySyntenyDisplay",
      "height": 600
    }
  ]
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "hprc_v2_1_gbz_lanes",
  "name": "HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)",
  "assemblyNames": [
    "hg38",
    "HG00097.1",
    "HG00099.1",
    "HG00128.1",
    "HG00133.1",
    "HG01109.1",
    "HG01123.1",
    "HG01960.1",
    "HG02055.1"
  ],
  "adapter": {
    "type": "GbzBaseSyntenyAdapter",
    "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.gbz.db",
    "haplotypeIndexLocation": {
      "uri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.haplotype-index.anchored.db"
    },
    "assemblyNames": ["hg38"],
    "assemblyNameToPanSN": {
      "hg38": "GRCh38#0",
      "HG00097.1": "HG00097#1",
      "HG00099.1": "HG00099#1",
      "HG00128.1": "HG00128#1",
      "HG00133.1": "HG00133#1",
      "HG01109.1": "HG01109#1",
      "HG01123.1": "HG01123#1",
      "HG01960.1": "HG01960#1",
      "HG02055.1": "HG02055#1"
    },
    "context": 1000,
    "nodeLimit": 50000
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "hprc_v2_1_gbz_lanes-MultiWaySyntenyDisplay",
      "height": 600
    }
  ]
}'

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": "SyntenyTrack",
  "trackId": "hprc_v2_1_gbz_lanes",
  "name": "HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)",
  "assemblyNames": [
    "hg38",
    "HG00097.1",
    "HG00099.1",
    "HG00128.1",
    "HG00133.1",
    "HG01109.1",
    "HG01123.1",
    "HG01960.1",
    "HG02055.1"
  ],
  "adapter": {
    "type": "GbzBaseSyntenyAdapter",
    "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.gbz.db",
    "haplotypeIndexLocation": {
      "uri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.haplotype-index.anchored.db"
    },
    "assemblyNames": ["hg38"],
    "assemblyNameToPanSN": {
      "hg38": "GRCh38#0",
      "HG00097.1": "HG00097#1",
      "HG00099.1": "HG00099#1",
      "HG00128.1": "HG00128#1",
      "HG00133.1": "HG00133#1",
      "HG01109.1": "HG01109#1",
      "HG01123.1": "HG01123#1",
      "HG01960.1": "HG01960#1",
      "HG02055.1": "HG02055#1"
    },
    "context": 1000,
    "nodeLimit": 50000
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "hprc_v2_1_gbz_lanes-MultiWaySyntenyDisplay",
      "height": 600
    }
  ]
}

The track opens on the assemblies its assemblyNames lists beside hg38, and assemblyNameToPanSN says which haplotype each one is. Choose lanes... on the track menu lists every haplotype the graph names, grouped by sample. Ticking every one draws the whole cohort, and the dialog's reset goes back to the eight.

The session below opens the CFH cluster at chr1:196,640,000-196,900,000:

{
  "defaultSession": {
    "name": "CFH cluster, one lane per haplotype walk",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "hg38",
        "loc": "chr1:196,640,000-196,900,000",
        "tracks": [
          {
            "trackId": "hg38_ncbiRefSeq_ucsc",
            "type": "LinearBasicDisplay",
            "showOnlyGenes": true,
            "displayMode": "compact"
          },
          {
            "trackId": "hprc_v2_1_gbz_lanes",
            "type": "MultiWaySyntenyDisplay",
            "rowOrder": [
              "HG00097.1",
              "HG00099.1",
              "HG00128.1",
              "HG00133.1",
              "HG01109.1",
              "HG01123.1",
              "HG01960.1",
              "HG02055.1"
            ],
            "height": 460
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "CFH cluster, one lane per haplotype walk",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:196,640,000-196,900,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact"
        },
        {
          "trackId": "hprc_v2_1_gbz_lanes",
          "type": "MultiWaySyntenyDisplay",
          "rowOrder": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "height": 460
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse

rowOrder puts every non-carrier above every carrier, which is what makes the deletion readable. Every lane sits at a different coordinate on a different contig. Between the last non-carrier and the first carrier the ribbon over CFHR3 and CFHR1 narrows to a point, because the carriers' walks skip that stretch of GRCh38, and the carriers' own annotations have no model there.

The CFH cluster's eight lanes read from the graph at load time, the non-carriers above the carriers, from two hosted files and no offline step. Each lane is one haplotype's walk aligned to hg38 as a CIGAR, and because the eight assemblies are in the session, each draws that haplotype's own CAT genes at its own coordinates over it. 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 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 figure uses the “hg38_ncbiRefSeq_ucsc” track.
  3. Track menu → Show only genes (checked)“hg38_ncbiRefSeq_ucsc”.
  4. Track menu → Set feature height → Compact“hg38_ncbiRefSeq_ucsc”.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “hprc_v2_1_gbz_lanes” track.
  6. Drag the bar at the bottom edge of the track to resize it.“hprc_v2_1_gbz_lanes”.
  7. Type your region of interest into the location box and press Enter.This figure is at chr1:196,640,000-196,900,000.

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%2Fdemos%2Fhprc%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%3A196%2C640%2C000-196%2C900%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hg38_ncbiRefSeq_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%7D%2C%7B%22trackId%22%3A%22hprc_v2_1_gbz_lanes%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22rowOrder%22%3A%5B%22HG00097.1%22%2C%22HG00099.1%22%2C%22HG00128.1%22%2C%22HG00133.1%22%2C%22HG01109.1%22%2C%22HG01123.1%22%2C%22HG01960.1%22%2C%22HG02055.1%22%5D%2C%22height%22%3A460%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_gbz_cfhr_lanes

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:196,640,000-196,900,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact"
        },
        {
          "trackId": "hprc_v2_1_gbz_lanes",
          "type": "MultiWaySyntenyDisplay",
          "rowOrder": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "height": 460
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/hprc/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr1:196,640,000-196,900,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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": "chr1:196,640,000-196,900,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact"
        },
        {
          "trackId": "hprc_v2_1_gbz_lanes",
          "type": "MultiWaySyntenyDisplay",
          "rowOrder": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "height": 460
        }
      ]
    }
  ]
}
JSON

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

GbzBaseSyntenyAdapter answers a window: it locates the window on GRCh38's own path through the graph and emits one record per haplotype walk, in that haplotype's contig coordinates and carrying the walk's CIGAR. Upstream gbz-base reports unknown#1, unknown#2 for those walks, so the companion file at haplotypeIndexLocation names them and carries anchors a named set can be walked from. The lanes in force, the track's own or whatever the reader picks from Choose lanes..., reach the adapter as the set to fetch. A lane hidden from its header menu stays in that set, so showing it again draws it at once.

context defaults to 1000, the nodes read on either side of the window. nodeLimit refuses a window that would not fit and names a zoom that would. AMY1 returns more records than there are haplotypes, because an extra copy of the repeat unit revisits the same stretch of GRCh38 and those pieces of one walk stay separate; those extra records are where a copy count per haplotype would be read off the graph.

The graph view from the GBZ, for a chosen set

The same track feeds the graph view. Launch → Graph genome view (this region) in the linear view's own menu cuts the window from the database for the lanes on screen, which are the track's configured lanes until Choose lanes... picks others. The cut carries one W line per haplotype walk, named through the companion, and Sample rows in the Layout dropdown gives each haplotype a row.

The same cut force-directed is where the walks say most. A node draws thicker the more of the nine walks carry it, so the reference is fat and each haplotype's private run of kringle copies is a thin loop. The Walk dropdown lifts one haplotype out: its route keeps its ink, the rest fades, and a readout gives its length against the reference walk.

The KIV-2 array cut from the GBZ for eight haplotypes, force-directed under the same window's genes, bubble and rGFA segments, with HG00133's walk lifted. The labelled loop is copies HG00133 walks and GRCh38 does not, its links drawn dark, and the readout states the walk's excess over GRCh38. 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. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).Pane 1 — This figure uses “NCBI RefSeq genes (hg38)”.
  4. Track menu → Gene glyph → Representative transcriptPane 1 · “NCBI RefSeq genes (hg38)”.
  5. Track menu → Set feature height → CompactPane 1 · “NCBI RefSeq genes (hg38)”.
  6. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “NCBI RefSeq genes (hg38)”.
  7. 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 “HPRC release 2 bubbles”.
  8. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “HPRC release 2 bubbles”.
  9. 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 “HPRC release 2 graph (rGFA segments)”.
  10. Track menu → Show... → Labels → NonePane 1 · “HPRC release 2 graph (rGFA segments)”.
  11. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “HPRC release 2 graph (rGFA segments)”.
  12. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a per-attribute palette, and the strand preset only, so an expression of any other shape is authored on the track config.Pane 1 · “HPRC release 2 graph (rGFA segments)”.
  13. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr6:160,616,002-160,646,753.
  14. Click the view's title in its header and enter "KIV-2 from the GBZ, eight haplotypes"Pane 2.
  15. Open the view: Add → Graph genome view, then on its "Load a GFA graph" form paste the URL and click Open (or Choose file for a local .gfa)Loads the whole graph, so it suits a subgraph or a small assembly. A window of a large one is cut from a segments track instead.Pane 2.
  16. Graph view toolbar → Layout → Force-directed layoutPane 2.
  17. Graph view menu → Settings → Reference path → GRCh38Which path the anchored layouts draw x against. Only offered when the file states more than one.Pane 2.
  18. Graph view toolbar → Color → Reference positionPane 2.
  19. Graph view menu → Settings → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.Pane 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=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%3A160%2C616%2C002-160%2C646%2C753%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%3A40%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A50%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_segments%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22none%22%2C%22height%22%3A70%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+-+160616002%29+%2F+30751+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%7D%5D%7D%2C%7B%22type%22%3A%22GraphGenomeView%22%2C%22displayName%22%3A%22KIV-2+from+the+GBZ%2C+eight+haplotypes%22%2C%22gfaLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fhprc%2Fhprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa%22%7D%2C%22layoutMode%22%3A%22force%22%2C%22referencePath%22%3A%22GRCh38%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22colorDomain%22%3A%7B%22refName%22%3A%22chr6%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A160616002%2C%22end%22%3A160646753%7D%2C%22bubbleSpread%22%3A%22compress%22%2C%22showBubbles%22%3Afalse%2C%22paneHeight%22%3A400%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_kiv2_walks

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,616,002-160,646,753",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 50
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 70,
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 160616002) / 30751 * 300)) + ',70%,50%)'"
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "displayName": "KIV-2 from the GBZ, eight haplotypes",
      "gfaLocation": {
        "uri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa"
      },
      "layoutMode": "force",
      "referencePath": "GRCh38",
      "colorScheme": "reference-position",
      "colorDomain": {
        "refName": "chr6",
        "assemblyName": "hg38",
        "start": 160616002,
        "end": 160646753
      },
      "bubbleSpread": "compress",
      "showBubbles": false,
      "paneHeight": 400
    }
  ]
}

Loaded against config: test_data/graphgenomeview/hprc.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr6:160,616,002-160,646,753",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "Gff3TabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "MinigraphBubbleAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_3",
    "name": "My track 3",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "RgfaTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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:160,616,002-160,646,753",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 50
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 70,
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 160616002) / 30751 * 300)) + ',70%,50%)'"
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "displayName": "KIV-2 from the GBZ, eight haplotypes",
      "gfaLocation": {
        "uri": "https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa"
      },
      "layoutMode": "force",
      "referencePath": "GRCh38",
      "colorScheme": "reference-position",
      "colorDomain": {
        "refName": "chr6",
        "assemblyName": "hg38",
        "start": 160616002,
        "end": 160646753
      },
      "bubbleSpread": "compress",
      "showBubbles": false,
      "paneHeight": 400
    }
  ]
}
JSON

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

Part 4 walks through that drawing from the rGFA window to the lifted haplotype.

Preparing a graph of your own

HPRC publishes the database this track reads, so nothing above builds one. For a .gbz of your own, three commands stand between it and the same track, none of them JBrowse: vg chains for the snarl decomposition, gbz-base construct for the database, and gbz-haplotype-index for the companion that names the walks. Preparing your own graph shows all three. The companion HPRC does not publish has a script of its own under Reproduce it end to end.

T2T-CHM13 as hs1

CHM13 is the contributor with a published reference behind it, T2T-CHM13v2.0, which UCSC serves as hs1; Comparing one genome's two haplotypes (T2T-HG002) loads HG002, the other donor with a reference of its own.

{
  "name": "hs1",
  "displayName": "Human (T2T-CHM13v2.0/hs1)",
  "uri": "https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.2bit"
}
jbrowse add-assembly https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.2bit \
  --name hs1 \
  --displayName "Human (T2T-CHM13v2.0/hs1)"

In JBrowse Desktop, Open new genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste:

https://hgdownload.soe.ucsc.edu/goldenPath/hs1/bigZips/hs1.2bit

JBrowse reads the format off the file name. Then fill in:

  • Genome name: hs1
  • Assembly display name (under More options): Human (T2T-CHM13v2.0/hs1)

The segments track draws on hs1, and a CHM13 node opens there, once hs1 joins its assemblyNames and "hs1": "CHM13" its assemblyNameToPanSN, the two edits part 1 makes for NA20809.2.

With both assemblies loaded a CHM13 node opens on either one, and on hs1 its coordinates are the donor's own. The node in the figure below is 142 kb of chr17 that GRCh38 does not carry, near the end of the chromosome, and RepeatMasker tiles it with long L1 elements.

A donor node on both coordinate systems: the GRCh38 window, the graph cut from it, then that node on hs1's own chr17 tiled by long L1 elements in red. 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 “HPRC release 2 bubbles”.
  4. Track menu → Filter by... → add the expressionThis figure filters on `feature.longestAlleleLength>100000`.Pane 1 · “HPRC release 2 bubbles”.
  5. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “HPRC release 2 bubbles”.
  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 “HPRC release 2 graph (rGFA segments)”.
  7. Track menu → Show... → Labels → NonePane 1 · “HPRC release 2 graph (rGFA segments)”.
  8. Track menu → Set feature height → Track sizing → Fixed feature height + autogrow track heightPane 1 · “HPRC release 2 graph (rGFA segments)”.
  9. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a per-attribute palette, and the strand preset only, so an expression of any other shape is authored on the track config.Pane 1 · “HPRC release 2 graph (rGFA segments)”.
  10. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr17:83,010,000-83,040,000.
  11. Click the view's title in its header and enter "hg38 (GRCh38) — no coordinates for this sequence"Pane 1.
  12. 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.Pane 1.
  13. Click the view's title in its header and enter "HPRC release 2 graph, cut from the window above"Pane 2.
  14. 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.
  15. 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.
  16. Graph view toolbar → Layout → Force-directed layoutPane 2.
  17. Graph view toolbar → Color → Reference positionPane 2.
  18. Open pane 3: Add → Linear genome view.
  19. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).Pane 3 — This figure uses hs1.
  20. 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 BigBed file (.bb).Pane 3 — This figure uses “RepeatMasker (T2T-CHM13v2.0), LINE elements in red”.
  21. Track menu → Set feature height → CollapsedPane 3 · “RepeatMasker (T2T-CHM13v2.0), LINE elements in red”.
  22. Track menu → Show... → Labels → NonePane 3 · “RepeatMasker (T2T-CHM13v2.0), LINE elements in red”.
  23. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a per-attribute palette, and the strand preset only, so an expression of any other shape is authored on the track config.Pane 3 · “RepeatMasker (T2T-CHM13v2.0), LINE elements in red”.
  24. Track menu → Set feature height → Track sizing → Fixed feature height + autogrow track heightPane 3 · “RepeatMasker (T2T-CHM13v2.0), LINE elements in red”.
  25. Drag the bar at the bottom edge of the track to resize it.Pane 3 · “RepeatMasker (T2T-CHM13v2.0), LINE elements in red”.
  26. 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 3 — This figure uses “HPRC release 2 graph (rGFA segments)”.
  27. Track menu → Show... → Labels → NonePane 3 · “HPRC release 2 graph (rGFA segments)”.
  28. Track menu → Set feature height → Track sizing → Fixed feature height + autogrow track heightPane 3 · “HPRC release 2 graph (rGFA segments)”.
  29. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a per-attribute palette, and the strand preset only, so an expression of any other shape is authored on the track config.Pane 3 · “HPRC release 2 graph (rGFA segments)”.
  30. Type your region of interest into the location box and press Enter.Pane 3 — This figure is at chr17:83,880,000-84,060,000.
  31. Click the view's title in its header and enter "T2T-CHM13v2.0 (hs1) — an ordinary interval"Pane 3.
  32. 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.Pane 3.

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=test_data%2Fgraphgenomeview%2Fhprc.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22hs1_rmsk_ucsc%22%2C%22name%22%3A%22RepeatMasker+%28T2T-CHM13v2.0%29%2C+LINE+elements+in+red%22%2C%22assemblyNames%22%3A%5B%22hs1%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22BigBedAdapter%22%2C%22bigBedLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fhgdownload.soe.ucsc.edu%2Fgbdb%2Fhs1%2Ft2tRepeatMasker%2Fchm13v2.0_rmsk.bb%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22displayName%22%3A%22hg38+%28GRCh38%29+%E2%80%94+no+coordinates+for+this+sequence%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr17%3A83%2C010%2C000-83%2C040%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr17%22%2C%22start%22%3A83022324%2C%22end%22%3A83023252%2C%22color%22%3A%22rgba%2860%2C65%2C72%2C0.10%29%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hprc_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22jexlFiltersSetting%22%3A%5B%22jexl%3Afeature.longestAlleleLength%3E100000%22%5D%2C%22height%22%3A46%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+-+83010000%29+%2F+30000+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%7D%5D%7D%2C%7B%22type%22%3A%22GraphGenomeView%22%2C%22displayName%22%3A%22HPRC+release+2+graph%2C+cut+from+the+window+above%22%2C%22loadedTrackId%22%3A%22hprc_minigraph_segments%22%2C%22loadedRegion%22%3A%7B%22refName%22%3A%22chr17%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A83010000%2C%22end%22%3A83040000%7D%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22paneHeight%22%3A320%7D%2C%7B%22type%22%3A%22LinearGenomeView%22%2C%22displayName%22%3A%22T2T-CHM13v2.0+%28hs1%29+%E2%80%94+an+ordinary+interval%22%2C%22assembly%22%3A%22hs1%22%2C%22loc%22%3A%22chr17%3A83%2C880%2C000-84%2C060%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr17%22%2C%22start%22%3A83899717%2C%22end%22%3A84041427%2C%22color%22%3A%22rgba%2860%2C65%2C72%2C0.10%29%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hs1_rmsk_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22displayMode%22%3A%22collapsed%22%2C%22showLabels%22%3A%22none%22%2C%22color%22%3A%22jexl%3Aincludes%28get%28feature%2C%27name%27%29%2C%27%23LINE%27%29+%3F+%27rgb%28200%2C60%2C45%29%27+%3A+%27rgb%28158%2C158%2C158%29%27%22%2C%22heightMode%22%3A%22grow%22%2C%22height%22%3A90%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+-+83010000%29+%2F+30000+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_chm13_allele

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": "hs1_rmsk_ucsc",
  "name": "RepeatMasker (T2T-CHM13v2.0), LINE elements in red",
  "assemblyNames": [
    "hs1"
  ],
  "adapter": {
    "type": "BigBedAdapter",
    "bigBedLocation": {
      "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hs1/t2tRepeatMasker/chm13v2.0_rmsk.bb",
      "locationType": "UriLocation"
    }
  }
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hs1 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 Session spec tab, or jbrowse set-default-session.

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

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "hs1_rmsk_ucsc",
      "name": "RepeatMasker (T2T-CHM13v2.0), LINE elements in red",
      "assemblyNames": [
        "hs1"
      ],
      "adapter": {
        "type": "BigBedAdapter",
        "bigBedLocation": {
          "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hs1/t2tRepeatMasker/chm13v2.0_rmsk.bb",
          "locationType": "UriLocation"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "displayName": "hg38 (GRCh38) — no coordinates for this sequence",
      "assembly": "hg38",
      "loc": "chr17:83,010,000-83,040,000",
      "highlight": [
        {
          "refName": "chr17",
          "start": 83022324,
          "end": 83023252,
          "color": "rgba(60,65,72,0.10)"
        }
      ],
      "tracks": [
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "jexlFiltersSetting": [
            "jexl:feature.longestAlleleLength>100000"
          ],
          "height": 46
        },
        {
          "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 - 83010000) / 30000 * 300)) + ',70%,50%)'"
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "displayName": "HPRC release 2 graph, cut from the window above",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr17",
        "assemblyName": "hg38",
        "start": 83010000,
        "end": 83040000
      },
      "layoutMode": "force",
      "colorScheme": "reference-position",
      "paneHeight": 320
    },
    {
      "type": "LinearGenomeView",
      "displayName": "T2T-CHM13v2.0 (hs1) — an ordinary interval",
      "assembly": "hs1",
      "loc": "chr17:83,880,000-84,060,000",
      "highlight": [
        {
          "refName": "chr17",
          "start": 83899717,
          "end": 84041427,
          "color": "rgba(60,65,72,0.10)"
        }
      ],
      "tracks": [
        {
          "trackId": "hs1_rmsk_ucsc",
          "type": "LinearBasicDisplay",
          "displayMode": "collapsed",
          "showLabels": "none",
          "color": "jexl:includes(get(feature,'name'),'#LINE') ? 'rgb(200,60,45)' : 'rgb(158,158,158)'",
          "heightMode": "grow",
          "height": 90
        },
        {
          "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 - 83010000) / 30000 * 300)) + ',70%,50%)'"
        }
      ]
    }
  ]
}

Loaded against config: test_data/graphgenomeview/hprc.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr17:83,010,000-83,040,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "MinigraphBubbleAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "RgfaTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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": "hs1_rmsk_ucsc",
      "name": "RepeatMasker (T2T-CHM13v2.0), LINE elements in red",
      "assemblyNames": [
        "hs1"
      ],
      "adapter": {
        "type": "BigBedAdapter",
        "bigBedLocation": {
          "uri": "https://hgdownload.soe.ucsc.edu/gbdb/hs1/t2tRepeatMasker/chm13v2.0_rmsk.bb",
          "locationType": "UriLocation"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "displayName": "hg38 (GRCh38) — no coordinates for this sequence",
      "assembly": "hg38",
      "loc": "chr17:83,010,000-83,040,000",
      "highlight": [
        {
          "refName": "chr17",
          "start": 83022324,
          "end": 83023252,
          "color": "rgba(60,65,72,0.10)"
        }
      ],
      "tracks": [
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "jexlFiltersSetting": [
            "jexl:feature.longestAlleleLength>100000"
          ],
          "height": 46
        },
        {
          "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 - 83010000) / 30000 * 300)) + ',70%,50%)'"
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "displayName": "HPRC release 2 graph, cut from the window above",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr17",
        "assemblyName": "hg38",
        "start": 83010000,
        "end": 83040000
      },
      "layoutMode": "force",
      "colorScheme": "reference-position",
      "paneHeight": 320
    },
    {
      "type": "LinearGenomeView",
      "displayName": "T2T-CHM13v2.0 (hs1) — an ordinary interval",
      "assembly": "hs1",
      "loc": "chr17:83,880,000-84,060,000",
      "highlight": [
        {
          "refName": "chr17",
          "start": 83899717,
          "end": 84041427,
          "color": "rgba(60,65,72,0.10)"
        }
      ],
      "tracks": [
        {
          "trackId": "hs1_rmsk_ucsc",
          "type": "LinearBasicDisplay",
          "displayMode": "collapsed",
          "showLabels": "none",
          "color": "jexl:includes(get(feature,'name'),'#LINE') ? 'rgb(200,60,45)' : 'rgb(158,158,158)'",
          "heightMode": "grow",
          "height": 90
        },
        {
          "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 - 83010000) / 30000 * 300)) + ',70%,50%)'"
        }
      ]
    }
  ]
}
JSON

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

With two assemblies loaded the graph's own Launch menu offers Linear synteny view as well, one panel per contributor at the locus each contributes here, if the session holds a synteny track aligning them. UCSC's hg38-to-hs1 liftOver is one, rehosted as an indexed PAF:

{
  "type": "SyntenyTrack",
  "trackId": "hg38_hs1_synteny",
  "name": "hg38 vs T2T-CHM13 (UCSC liftOver)",
  "assemblyNames": ["hg38", "hs1"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz",
    "csi": true,
    "assemblyNames": ["hs1", "hg38"]
  }
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "hg38_hs1_synteny",
  "name": "hg38 vs T2T-CHM13 (UCSC liftOver)",
  "assemblyNames": ["hg38", "hs1"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz",
    "csi": true,
    "assemblyNames": ["hs1", "hg38"]
  }
}'

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": "SyntenyTrack",
  "trackId": "hg38_hs1_synteny",
  "name": "hg38 vs T2T-CHM13 (UCSC liftOver)",
  "assemblyNames": ["hg38", "hs1"],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "uri": "https://jbrowse.org/ucsc/hg38/liftOver/hg38ToHs1.over.pif.gz",
    "csi": true,
    "assemblyNames": ["hs1", "hg38"]
  }
}

Taken at the window above, it opens hg38 over hs1, each panel already at the interval the graph states for it. Without such a track the entry stays, greyed out, and its tooltip says what is missing.

The graph's own Launch menu at the CHM13 window, with hg38 and hs1 loaded and the liftOver between them in the session. Above, the hg38 window and the cut, the CHM13 node ringed. Below, the synteny view the Linear synteny view entry opened: hg38 over hs1, each panel framed on the locus the graph states for it, with the liftOver ribbons between. 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. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).Pane 1 — This figure uses “NCBI RefSeq genes (hg38)”.
  4. Track menu → Gene glyph → Representative transcriptPane 1 · “NCBI RefSeq genes (hg38)”.
  5. Track menu → Set feature height → CompactPane 1 · “NCBI RefSeq genes (hg38)”.
  6. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “NCBI RefSeq genes (hg38)”.
  7. 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 “HPRC release 2 graph (rGFA segments)”.
  8. Track menu → Show... → Labels → NonePane 1 · “HPRC release 2 graph (rGFA segments)”.
  9. Track menu → Set feature height → Track sizing → Fixed feature height + autogrow track heightPane 1 · “HPRC release 2 graph (rGFA segments)”.
  10. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a per-attribute palette, and the strand preset only, so an expression of any other shape is authored on the track config.Pane 1 · “HPRC release 2 graph (rGFA segments)”.
  11. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr17:83,010,000-83,040,000.
  12. 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.
  13. 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.
  14. Graph view toolbar → Layout → Force-directed layoutPane 2.
  15. 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=test_data%2Fgraphgenomeview%2Fhprc_hs1.json&session=spec-%7B%22views%22%3A%5B%7B%22id%22%3A%22hprc_synteny_lgv%22%2C%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr17%3A83%2C010%2C000-83%2C040%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+-+83010000%29+%2F+30000+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%7D%5D%7D%2C%7B%22id%22%3A%22hprc_synteny_graph%22%2C%22type%22%3A%22GraphGenomeView%22%2C%22loadedTrackId%22%3A%22hprc_minigraph_segments%22%2C%22loadedRegion%22%3A%7B%22refName%22%3A%22chr17%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A83010000%2C%22end%22%3A83040000%7D%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22paneHeight%22%3A320%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_synteny_launch

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

{
  "views": [
    {
      "id": "hprc_synteny_lgv",
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:83,010,000-83,040,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 - 83010000) / 30000 * 300)) + ',70%,50%)'"
        }
      ]
    },
    {
      "id": "hprc_synteny_graph",
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr17",
        "assemblyName": "hg38",
        "start": 83010000,
        "end": 83040000
      },
      "layoutMode": "force",
      "colorScheme": "reference-position",
      "paneHeight": 320
    }
  ]
}

Loaded against config: test_data/graphgenomeview/hprc_hs1.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr17:83,010,000-83,040,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "Gff3TabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "RgfaTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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": [
    {
      "id": "hprc_synteny_lgv",
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:83,010,000-83,040,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 - 83010000) / 30000 * 300)) + ',70%,50%)'"
        }
      ]
    },
    {
      "id": "hprc_synteny_graph",
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_minigraph_segments",
      "loadedRegion": {
        "refName": "chr17",
        "assemblyName": "hg38",
        "start": 83010000,
        "end": 83040000
      },
      "layoutMode": "force",
      "colorScheme": "reference-position",
      "paneHeight": 320
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc_hs1.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.

Reproduce it end to end

The haplotype-walk lanes need one file HPRC does not publish, the companion index that names the walks in its gbz-base database:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_hprc_gbz_index.sh
bash build_hprc_gbz_index.sh out

build_hprc_gbz_index.sh downloads the 5.5 GB .gbz, builds gbz-haplotype-index from source and runs the one command Preparing your own graph shows, which takes about a quarter of an hour on 24 cores. The database it accompanies is read straight from HPRC's bucket and never downloaded.

The panel and its CAT annotations have a script of their own:

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

build_hprc_cfhr_synteny.sh picks four carriers and four non-carriers of the deletion out of the callset (CARRIERS and NONCARRIERS), slices their alignments out of release 2's all-vs-GRCh38 PAF, and slices each haplotype's CAT annotation to the same window.

See also

References

  • HPRC release 2, the release this page opens: the multiple alignment, the gbz-base database and the CAT annotation of every assembly.
  • taffy, which writes the .tai index that makes the 5.9 GB alignment addressable by locus.