Skip to main content

Pangenome (HPRC) part 3: repeat lengths across haplotypes

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

A tandem repeat is one sequence copied head to tail, and the number of copies varies from person to person. An assembled haplotype spans the whole array, so the Human Pangenome Reference Consortium's release 2 graph holds each haplotype's repeat at its full length. We read three arrays off it, one bar per haplotype:

  • at LPA, count copies of the kringle IV type 2 repeat and tell its two repeat types apart
  • at ABCA7, measure an intronic VNTR and set PacBio's read-based TRGT genotypes on the same bars
  • find the samples where the assemblies and the reads disagree
  • at amylase, count AMY1 gene copies and check them against Yilmaz et al. (2024)
Experimental

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

Prerequisites

Where the data comes from

HPRC release 2 and PacBio's TRGT genotypes of 100 of its samples (Dolzhenko et al. 2024), 94 of which have a call at ABCA7.

The build script takes these files from their URLs, so there is nothing to download by hand.

Read by URL (no download needed)

Reading the LPA kringle repeat as a graph

LPA contains a tandem array of kringle IV type 2 (KIV-2) copies, tied to lipoprotein(a) levels, a heart-disease risk factor (Schmidt et al. 2016). We'll open it from the HPRC page:

  • Open the HPRC page, click the LPA example and press Graph. JBrowse opens on chr6:160,525,000-160,655,000.
  • Tick Show... → Show bubble halos in the graph track's menu.

The strip along the top of the track draws each reference segment at its position on the ruler, in the color of its node below.

The LPA window with the RefSeq genes, UniProt's kringle domains and the HPRC bubbles above the force-directed graph track, the KIV-2 array's bubble boxed. In the graph the array is the knot of loops on the right, haloed and labelled as a repeat array, and LPA is pinned under the backbone with its exons along it.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22trackId%22%3A%22hg38_uniprot_domains_lpa%22%2C%22name%22%3A%22UniProt+domains+%28Swiss-Prot%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fhprc%2Flpa_uniprot_domains.bed.gz%22%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr6%3A160%2C525%2C000-160%2C655%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%3A70%7D%2C%7B%22trackId%22%3A%22hg38_uniprot_domains_lpa%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A75%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A80%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22force%22%2C%22color%22%3A%7B%22field%22%3A%22position%22%7D%2C%22layers%22%3A%7B%22bubbles%22%3Atrue%7D%2C%22maxRegionBp%22%3A143000%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_lpa_kiv2

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38.
  2. Add a track: check one your config has in the track selector, or File → Open track... to 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. Add the next track the same way.This figure uses “UniProt domains (Swiss-Prot)”.
  4. Add the next track the same way.This figure uses “HPRC release 2 bubbles”.
  5. Add the next track the same way.This figure uses “HPRC v2.1 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed
  6. Type your region of interest into the location box and press Enter.This figure is at chr6:160,525,000-160,655,000.

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 https://jbrowse.org/demos/hprc/lpa_uniprot_domains.bed.gz \
  --trackId hg38_uniprot_domains_lpa \
  --name "UniProt domains (Swiss-Prot)" \
  --assemblyNames hg38

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. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "trackId": "hg38_uniprot_domains_lpa",
      "name": "UniProt domains (Swiss-Prot)",
      "assemblyNames": [
        "hg38"
      ],
      "uri": "https://jbrowse.org/demos/hprc/lpa_uniprot_domains.bed.gz"
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,525,000-160,655,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 70
        },
        {
          "trackId": "hg38_uniprot_domains_lpa",
          "type": "LinearBasicDisplay",
          "height": 75
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 80
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "color": {
            "field": "position"
          },
          "layers": {
            "bubbles": true
          },
          "maxRegionBp": 143000,
          "height": 600
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "trackId": "hg38_uniprot_domains_lpa",
      "name": "UniProt domains (Swiss-Prot)",
      "assemblyNames": [
        "hg38"
      ],
      "uri": "https://jbrowse.org/demos/hprc/lpa_uniprot_domains.bed.gz"
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,525,000-160,655,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 70
        },
        {
          "trackId": "hg38_uniprot_domains_lpa",
          "type": "LinearBasicDisplay",
          "height": 75
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 80
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "color": {
            "field": "position"
          },
          "layers": {
            "bubbles": true
          },
          "maxRegionBp": 143000,
          "height": 600
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "kringle copies on one haplotype, absent from GRCh38",
    "fontSize": 18,
    "maxWidth": 340,
    "leader": true,
    "anchor": {
      "graphNode": "s343607+"
    },
    "textAlign": "end",
    "dx": -137,
    "dy": -6
  },
  {
    "type": "box",
    "anchor": {
      "trackId": "hprc_minigraph_bubbles",
      "loc": "chr6:160,616,002-160,646,753"
    },
    "pad": 3
  }
]
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 1170 \
  --timeout 180000 \
  --spec session.json --annotations callouts.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.

Each loop in the knot is a different number of copies. Click the array's purple label to lay the bubble's segments out alone, with a button back to the window. The rGFA records segments and links, and the haplotypes track records each haplotype's route through them, its walk.

Eight haplotypes' routes through the KIV-2 array

A walk is one haplotype's route through the graph, and the haplotypes track reads one per haplotype from tabix-indexed files. In the same window:

  • Type chr6:160,616,002-160,646,753, the array.
  • Display types → Feature display puts the rGFA graph track back to a row of segments.
  • Turn the haplotypes track on in the track selector. Display types → Graph in its menu draws a force-directed graph of the walks.
  • Check Haplotypes → The track's 8 assemblies in the same menu. Every haplotype's walks through the array have more nodes than a force-directed drawing handles, so this keeps the eight HPRC assemblies the hosted config loads, and walk rows below draw them all.

A node draws thicker the more walks visit it (as in Bandage), so the shared backbone is the thick line and copies on one haplotype are thin loops. Pick HG00133 under Haplotypes: its route stays dark while everything else fades, and a readout gives its length against the reference walk.

The eight-haplotype KIV-2 cut under the same window's genes, bubbles and rGFA segments, with HG00133 picked under Haplotypes. 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 in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fpangenome%2Fhprc-grch38%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%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%2C%7B%22trackId%22%3A%22hprc_v2_1_walk_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22subgraphHaplotypes%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%22layoutMode%22%3A%22force%22%2C%22color%22%3A%7B%22field%22%3A%22position%22%2C%22domainMin%22%3A160616002%2C%22domainMax%22%3A160646753%7D%2C%22bubbleSpread%22%3A%22compress%22%2C%22layers%22%3A%7B%22bubbles%22%3Afalse%7D%2C%22height%22%3A400%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_kiv2_walks

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to 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. Add the next track the same way.This figure uses “HPRC release 2 bubbles”.
  4. Add the next track the same way.This figure uses “HPRC v2.1 graph (rGFA segments)”.
    1. Track menu → Show... → Labels → None
    2. 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.
  5. Add the next track the same way.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the haplotype walk files”.
    1. Track menu → Graph settings... → HaplotypesThe haplotypes a gbz-base cut is for, as lane names or PanSN prefixes; empty is every haplotype the graph holds.
    2. Track menu → Layout → Force-directed
    3. Track menu → Graph 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.
  6. Type your region of interest into the location box and press Enter.This figure is at chr6:160,616,002-160,646,753.

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

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/pangenome/hprc-grch38/config.json, which is what the Web button above opens.

{
  "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%)'"
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "layoutMode": "force",
          "color": {
            "field": "position",
            "domainMin": 160616002,
            "domainMax": 160646753
          },
          "bubbleSpread": "compress",
          "layers": {
            "bubbles": false
          },
          "height": 400
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, 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%)'"
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "layoutMode": "force",
          "color": {
            "field": "position",
            "domainMin": 160616002,
            "domainMax": 160646753
          },
          "bubbleSpread": "compress",
          "layers": {
            "bubbles": false
          },
          "height": 400
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "HG00133 walks this loop",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "graphNode": "165812967"
    },
    "dx": 120,
    "dy": 80
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/pangenome/hprc-grch38/config.json \
  --width 1400 --height 910 \
  --timeout 240000 \
  --spec session.json --annotations callouts.json -o figure.png

The figure's clicks lift HG00133's walk out of the graph, which this command does not do, so its picture differs there.

It leaves out the callout anchored to what the clicks bring up.

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.

Every haplotype's KIV-2 array as a bar

Walk rows draw each walk as a bar, so every haplotype in the release fits in the track. In the haplotypes track's menu:

  • Walk rows under the Layout row and Uniform under the Color row turn each walk into a bar, longest first, blue on GRCh38's path through the graph and purple off it
  • Haplotypes → Every haplotype in the graph cuts the window again for the whole release

At KIV-2 each copy a haplotype adds is a run of new nodes, so its added copies read as the purple stretch of its bar. The rows pack to fit the track, too thin to letter, so hover a bar for its haplotype, length and excess over GRCh38.

Every HPRC haplotype's walk across the KIV-2 array in walk rows, longest first under GRCh38's, beneath LPA with the KIV-2 bubble boxed in the bubbles track. The purple stretch of each bar is kringle copies off GRCh38's path, and the bar ends step down one copy at a time.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fpangenome%2Fhprc-grch38%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%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%3A50%7D%2C%7B%22trackId%22%3A%22hprc_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A80%7D%2C%7B%22trackId%22%3A%22hprc_v2_1_walk_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22subgraphHaplotypes%22%3A%5B%5D%2C%22layoutMode%22%3A%22walkrows%22%2C%22color%22%3A%22uniform%22%2C%22bubbleSpread%22%3A%22compress%22%2C%22layers%22%3A%7B%22bubbles%22%3Afalse%7D%2C%22size%22%3A12%2C%22height%22%3A300%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_kiv2_walk_rows

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to 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. Add the next track the same way.This figure uses “HPRC release 2 bubbles”.
  4. Add the next track the same way.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the haplotype walk files”.
    1. Track menu → Graph settings... → HaplotypesThe haplotypes a gbz-base cut is for, as lane names or PanSN prefixes; empty is every haplotype the graph holds.
    2. Track menu → Layout → Walk rows
    3. Track menu → Graph 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.
  5. Type your region of interest into the location box and press Enter.This figure is at chr6:160,616,002-160,646,753.

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

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/pangenome/hprc-grch38/config.json, which is what the Web button above opens.

{
  "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": 50
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 80
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [],
          "layoutMode": "walkrows",
          "color": "uniform",
          "bubbleSpread": "compress",
          "layers": {
            "bubbles": false
          },
          "size": 12,
          "height": 300
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, 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": 50
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 80
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [],
          "layoutMode": "walkrows",
          "color": "uniform",
          "bubbleSpread": "compress",
          "layers": {
            "bubbles": false
          },
          "size": 12,
          "height": 300
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "box",
    "anchor": {
      "trackId": "hprc_minigraph_bubbles",
      "loc": "chr6:160,616,002-160,646,753"
    },
    "pad": 3
  },
  {
    "type": "text",
    "text": "the KIV-2 array, which each bar below walks across",
    "fontSize": 18,
    "maxWidth": 520,
    "textAlign": "end",
    "anchor": {
      "trackId": "hprc_minigraph_bubbles",
      "loc": "chr6:160,616,002-160,646,753",
      "alignX": "right",
      "fracY": 0,
      "dx": -48,
      "dy": 44
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/pangenome/hprc-grch38/config.json \
  --width 1400 --height 740 \
  --timeout 240000 \
  --spec session.json --annotations callouts.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.

Click the KIV-2 bubble boxed in the bubbles track. Its details give shortestAlleleLength and longestAlleleLength, the shortest and longest routes the rGFA holds there, and the bars run from about the one to about the other.

Two controls change which bars show:

  • Right-click a bar and pick Show only with its name to read one sample at full size.
  • Samples → Choose samples... under the Layout row picks names, and Samples → Every sample brings the cohort back.

Telling KIV-2A from KIV-2B

Walk rows give each haplotype's copy count. KIV-2's copies are near-identical, and the aligner's choice of which GRCh38 copy an extra one matches is arbitrary, so the walks leave open which copy is which. A record that lists each haplotype's copies settles it.

We host one as a track: a single VCF 4.5 <CNV:TR> record at the array over every haplotype whose walk reaches both flanks. Each allele lists its runs of one copy type and every copy's length, a phased genotype puts each allele on its haplotype, and a samples table gives each sample's population:

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

{
  "type": "VariantTrack",
  "trackId": "hprc_kiv2_copies_all",
  "name": "LPA KIV-2 copies by unit, all HPRC haplotypes",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/hprc/hprc_kiv2_copies_all.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/demos/hprc/hprc_samples.tsv"
    }
  }
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "hprc_kiv2_copies_all",
  "name": "LPA KIV-2 copies by unit, all HPRC haplotypes",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/hprc/hprc_kiv2_copies_all.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/demos/hprc/hprc_samples.tsv"
    }
  }
}'

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": "hprc_kiv2_copies_all",
  "name": "LPA KIV-2 copies by unit, all HPRC haplotypes",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/hprc/hprc_kiv2_copies_all.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/demos/hprc/hprc_samples.tsv"
    }
  }
}

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

Turn the track on, right-click the record and choose Show repeat copies. The TandemRepeat plugin, which the hosted config loads beside the graph plugin, opens a view with one bar per haplotype, each with a bp axis and each copy colored by its type. Hover a copy for its haplotype.

Group by… → superpopulation in the view's menu splits the bars by that column of the samples table.

The KIV-2 record over every HPRC haplotype grouped by superpopulation, within each group those with the most KIV-2B copies first, then longest, each copy colored by its type. KIV-2B leads every array that holds it. Arrays opening with a block of KIV-2B copies gather in the AMR, EAS and SAS sections; in EUR, KIV-2B is mostly a single opening copy, and most AFR arrays hold none.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22chr6%3A160%2C596%2C000-160%2C666%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%2C%22height%22%3A40%7D%2C%7B%22trackId%22%3A%22hprc_kiv2_copies_all%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22height%22%3A40%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_kiv2_copies_by_superpopulation

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38.
  2. Add a track: check one your config has in the track selector, or File → Open track... to 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 → Show only genes (checked)
    2. Track menu → Feature height → Compact
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “LPA KIV-2 copies by unit, all HPRC haplotypes”.
  4. Type your region of interest into the location box and press Enter.This figure is at chr6:160,596,000-160,666,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/hprc/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,596,000-160,666,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "hprc_kiv2_copies_all",
          "type": "LinearVariantDisplay",
          "height": 40
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hprc/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr6:160,596,000-160,666,000",
            "tracks": [
                {
                    "trackId": "hg38_ncbiRefSeq_ucsc",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact",
                    "height": 40
                },
                {
                    "trackId": "hprc_kiv2_copies_all",
                    "type": "LinearVariantDisplay",
                    "height": 40
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/demos/hprc/config.json \
  --assembly hg38 --loc chr6:160,596,000-160,666,000 \
  --track hg38_ncbiRefSeq_ucsc display:LinearBasicDisplay '{"showOnlyGenes":true,"displayMode":"compact","height":40}' \
  --track hprc_kiv2_copies_all display:LinearVariantDisplay '{"height":40}' \
  --width 1400 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,596,000-160,666,000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "hprc_kiv2_copies_all",
          "type": "LinearVariantDisplay",
          "height": 40
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hprc/config.json \
  --width 1400 --height 1300 \
  --timeout 120000 \
  --spec session.json -o figure.png

The figure's clicks open the record's repeat copies view, which this command does not do, so its picture differs there.

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 track selector also holds LPA KIV-2 copies by unit, eight HPRC haplotypes, few enough bars to label each by name.

To write a record like it for your own array, we'll first cut the walks over it out of the gbz-base database as a GFA subgraph, with enough context that the cut reaches the reference nodes on either side:

# the reference walk is PanSN GRCh38#0#chr6; the interval is the array
npx --yes -p @gmod/gbz-base gbz-base-query \
  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 \
  --haplotype-index https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.haplotype-index.f3.db \
  --sample GRCh38 --contig chr6 --interval 160616002..160646753 \
  --context 1000 --snarls --haplotypes all --limit 100000 --resolve \
  --format gfa > cut.gfa

tandem-repeat-vcf.mjs splits each walk into copies wherever the reference array's first 24 bases recur, and groups copies within 1% of each other into a unit. It takes the cut and a BED row naming the array on the reference (chrom, start, end, name), and --unit-names names the units, the one with the most copies first:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-plugin-tandem-repeat/main/scripts/tandem-repeat-vcf.mjs
printf 'chr6\t160616002\t160646753\tKIV-2\n' > arrays.bed
node tandem-repeat-vcf.mjs cut.gfa --bed arrays.bed --name KIV-2 \
  --unit-names KIV-2A,KIV-2B > kiv2.vcf

Given one copy's exons as BED rows with their strand, --sites reports where the units differ inside each. At KIV-2 that is exon 1's positions 14, 41 and 86, the three synonymous sites LPA studies use to tell KIV-2B from KIV-2A, and nothing in exon 2:

printf 'chr6\t160617116\t160617276\texon 1\t0\t-\nchr6\t160618483\t160618665\texon 2\t0\t-\n' > kiv2_exons.bed
node tandem-repeat-vcf.mjs cut.gfa --bed arrays.bed --name KIV-2 \
  --sites kiv2_exons.bed > /dev/null

A repeat finder's output draws as these bars too once it is written as a <CNV:TR> record with each allele's runs and copy lengths.

Measuring the ABCA7 VNTR against TRGT's read-based genotypes

An intron of ABCA7 holds a VNTR (variable-number tandem repeat) tied to Alzheimer's disease risk (De Roeck et al. 2018). Each haplotype's walk length comes from its assembly, and PacBio's TRGT, a tandem repeat genotyper for HiFi reads, measured the same repeat in 94 HPRC samples. We host its ABCA7 call as this track:

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

{
  "trackId": "hprc_abca7_trgt",
  "name": "TRGT repeat genotypes at ABCA7, 94 HPRC samples",
  "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_trgt.vcf.gz",
  "assemblyNames": ["hg38"]
}
jbrowse add-track https://jbrowse.org/demos/hprc/hprc_abca7_trgt.vcf.gz \
  --trackId hprc_abca7_trgt \
  --name "TRGT repeat genotypes at ABCA7, 94 HPRC samples" \
  --assemblyNames 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:

{
  "trackId": "hprc_abca7_trgt",
  "name": "TRGT repeat genotypes at ABCA7, 94 HPRC samples",
  "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_trgt.vcf.gz",
  "assemblyNames": ["hg38"]
}

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

TRGT writes the same fields for your own samples, one VCF each, joined by trgt merge:

# one run per sample: HiFi reads aligned to GRCh38, and the repeat catalogue
trgt genotype --genome GRCh38.fa --reads sample.bam \
  --repeats adotto_repeats.hg38.bed --output-prefix sample
# genotype writes its VCF unsorted, and merge reads sorted, indexed input
bcftools sort -Oz -o sample.sorted.vcf.gz sample.vcf.gz
bcftools index -t sample.sorted.vcf.gz
trgt merge --vcf *.sorted.vcf.gz --genome GRCh38.fa --output-type z --output merged.vcf.gz

The session below lays the walks out as bars beside the genes, the catalogue's VNTR row and the TRGT genotypes:

Goes at the top level of config.json, replacing any defaultSession there. See Default session.

{
  "defaultSession": {
    "name": "ABCA7 VNTR, walk rows",
    "sessionTracks": [
      {
        "type": "FeatureTrack",
        "trackId": "abca7_vntr",
        "name": "Tandem repeat catalogue (adotto)",
        "assemblyNames": ["hg38"],
        "adapter": {
          "type": "FromConfigAdapter",
          "features": [
            {
              "uniqueId": "abca7_vntr",
              "refName": "chr19",
              "start": 1049407,
              "end": 1050096,
              "name": "ABCA7 VNTR"
            }
          ]
        }
      }
    ],
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "hg38",
        "loc": "chr19:1,049,000-1,050,500",
        "tracks": [
          {
            "trackId": "hg38_ncbiRefSeq_ucsc",
            "type": "LinearBasicDisplay",
            "showOnlyGenes": true,
            "displayMode": "compact",
            "height": 40
          },
          {
            "trackId": "abca7_vntr",
            "type": "LinearBasicDisplay",
            "height": 40
          },
          {
            "trackId": "hprc_abca7_trgt",
            "type": "LinearVariantDisplay",
            "height": 40
          },
          {
            "trackId": "hprc_v2_1_walk_lanes",
            "type": "LinearGraphDisplay",
            "layoutMode": "walkrows",
            "color": "uniform",
            "subgraphHaplotypes": [],
            "repeatTrackId": "hprc_abca7_trgt",
            "height": 600
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "ABCA7 VNTR, walk rows",
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "abca7_vntr",
      "name": "Tandem repeat catalogue (adotto)",
      "assemblyNames": ["hg38"],
      "adapter": {
        "type": "FromConfigAdapter",
        "features": [
          {
            "uniqueId": "abca7_vntr",
            "refName": "chr19",
            "start": 1049407,
            "end": 1050096,
            "name": "ABCA7 VNTR"
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "abca7_vntr",
          "type": "LinearBasicDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "type": "LinearVariantDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [],
          "repeatTrackId": "hprc_abca7_trgt",
          "height": 600
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse Web ↗

Each row is one haplotype's walk between the flanking reference nodes. Hover a row for its haplotype and length.

The session names the TRGT track as its repeatTrackId, so the Layout row of the track menu gains a Repeat entry. Pick the ABCA7 record: each walk gets a black tick at the allele TRGT called for it (paired by length), red where the two lie more than 10% apart. At full size, as in the next section, the bars also divide into motif-length units.

The ABCA7 VNTR in walk rows, one bar per HPRC haplotype, longest first and packed to fit, with the TRGT record picked under Repeat and the catalogue track marking the VNTR on GRCh38. The black ticks tracing the bar ends are TRGT's calls agreeing with the walks; each red tick is a call more than 10% from its walk.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22abca7_vntr%22%2C%22name%22%3A%22Tandem+repeat+catalogue+%28adotto%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22FromConfigAdapter%22%2C%22features%22%3A%5B%7B%22uniqueId%22%3A%22abca7_vntr%22%2C%22refName%22%3A%22chr19%22%2C%22start%22%3A1049407%2C%22end%22%3A1050096%2C%22name%22%3A%22ABCA7+VNTR%22%7D%5D%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr19%3A1%2C049%2C000-1%2C050%2C500%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%2C%22height%22%3A40%7D%2C%7B%22trackId%22%3A%22abca7_vntr%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A40%7D%2C%7B%22trackId%22%3A%22hprc_abca7_trgt%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22height%22%3A40%7D%2C%7B%22trackId%22%3A%22hprc_v2_1_walk_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22walkrows%22%2C%22color%22%3A%22uniform%22%2C%22subgraphHaplotypes%22%3A%5B%5D%2C%22repeatTrackId%22%3A%22hprc_abca7_trgt%22%2C%22repeatKey%22%3A%22chr19%3A1049406-1050096%22%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_abca7_repeat_units

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38.
  2. Add a track: check one your config has in the track selector, or File → Open track... to 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 → Show only genes (checked)
    2. Track menu → Feature height → Compact
  3. Add the next track the same way. This one needs features defined inline in the config.This figure uses “Tandem repeat catalogue (adotto)”.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT repeat genotypes at ABCA7, 94 HPRC samples”.
  5. Add the next track the same way.This figure uses “HPRC v2.1 haplotypes vs GRCh38, read from the walk files”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Graph settings... → HaplotypesThe haplotypes a gbz-base cut is for, as lane names or PanSN prefixes; empty is every haplotype the graph holds.
  6. Type your region of interest into the location box and press Enter.This figure is at chr19:1,049,000-1,050,500.

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": "abca7_vntr",
  "name": "Tandem repeat catalogue (adotto)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "FromConfigAdapter",
    "features": [
      {
        "uniqueId": "abca7_vntr",
        "refName": "chr19",
        "start": 1049407,
        "end": 1050096,
        "name": "ABCA7 VNTR"
      }
    ]
  }
}'

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. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/hprc/config.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "abca7_vntr",
      "name": "Tandem repeat catalogue (adotto)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "FromConfigAdapter",
        "features": [
          {
            "uniqueId": "abca7_vntr",
            "refName": "chr19",
            "start": 1049407,
            "end": 1050096,
            "name": "ABCA7 VNTR"
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "abca7_vntr",
          "type": "LinearBasicDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "type": "LinearVariantDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [],
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "height": 600
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "abca7_vntr",
      "name": "Tandem repeat catalogue (adotto)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "FromConfigAdapter",
        "features": [
          {
            "uniqueId": "abca7_vntr",
            "refName": "chr19",
            "start": 1049407,
            "end": 1050096,
            "name": "ABCA7 VNTR"
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "abca7_vntr",
          "type": "LinearBasicDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "type": "LinearVariantDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [],
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "height": 600
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hprc/config.json \
  --width 1400 --height 1065 \
  --timeout 240000 \
  --spec 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.

Samples where reads and assemblies disagree

To compare seven samples, keep the ABCA7 record picked under Repeat. Samples → Choose samples..., under the Layout row of the graph track's menu, takes HG00099, HG03688, HG00741, HG02647, HG01943, HG02559 and HG04199 in that order. Their walks show in pairs in that order and fall into three groups:

  • HG00099, HG03688 and HG00741 tick at each bar's end: reads and assemblies agree.
  • HG02647 and HG01943 turn red: TRGT calls each near-homozygous, but a walk sits far from both calls (both walks, in HG01943).
  • HG02559 and HG04199 each have a walk with no verdict. No read spans one of HG02559's alleles, so the tick on HG02559#1 is grey, and HG04199's assembly does not span the repeat: its second walk's readout says the contig ends before it.

Click the TRGT record to see why. Its sample table gives AL, the allele lengths behind each tick, and SD, the number of reads spanning each allele; one of HG02559's alleles has an SD of 0.

Seven samples' walks through the ABCA7 VNTR in pairs, each bar marked with the allele TRGT called for it as a tick. A tick at the end of its bar is agreement, a red readout is a walk far from its allele, and a grey tick is an allele no read spanned.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22abca7_vntr%22%2C%22name%22%3A%22Tandem+repeat+catalogue+%28adotto%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22FromConfigAdapter%22%2C%22features%22%3A%5B%7B%22uniqueId%22%3A%22abca7_vntr%22%2C%22refName%22%3A%22chr19%22%2C%22start%22%3A1049407%2C%22end%22%3A1050096%2C%22name%22%3A%22ABCA7+VNTR%22%7D%5D%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr19%3A1%2C049%2C000-1%2C050%2C500%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22abca7_vntr%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A40%7D%2C%7B%22trackId%22%3A%22hprc_abca7_trgt%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22height%22%3A40%7D%2C%7B%22trackId%22%3A%22hprc_v2_1_walk_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22walkrows%22%2C%22color%22%3A%22uniform%22%2C%22subgraphHaplotypes%22%3A%5B%5D%2C%22repeatTrackId%22%3A%22hprc_abca7_trgt%22%2C%22repeatKey%22%3A%22chr19%3A1049406-1050096%22%2C%22rows%22%3A%7B%22kept%22%3A%5B%22HG00099%22%2C%22HG03688%22%2C%22HG00741%22%2C%22HG02647%22%2C%22HG01943%22%2C%22HG02559%22%2C%22HG04199%22%5D%7D%2C%22height%22%3A360%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_abca7_disagreements

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs features defined inline in the config.This figure uses “Tandem repeat catalogue (adotto)”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT repeat genotypes at ABCA7, 94 HPRC samples”.
  4. Add the next track the same way.This figure uses “HPRC v2.1 haplotypes vs GRCh38, read from the walk files”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Graph settings... → HaplotypesThe haplotypes a gbz-base cut is for, as lane names or PanSN prefixes; empty is every haplotype the graph holds.
  5. Type your region of interest into the location box and press Enter.This figure is at chr19:1,049,000-1,050,500.

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": "abca7_vntr",
  "name": "Tandem repeat catalogue (adotto)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "FromConfigAdapter",
    "features": [
      {
        "uniqueId": "abca7_vntr",
        "refName": "chr19",
        "start": 1049407,
        "end": 1050096,
        "name": "ABCA7 VNTR"
      }
    ]
  }
}'

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. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/hprc/config.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "abca7_vntr",
      "name": "Tandem repeat catalogue (adotto)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "FromConfigAdapter",
        "features": [
          {
            "uniqueId": "abca7_vntr",
            "refName": "chr19",
            "start": 1049407,
            "end": 1050096,
            "name": "ABCA7 VNTR"
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "abca7_vntr",
          "type": "LinearBasicDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "type": "LinearVariantDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [],
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "rows": {
            "kept": [
              "HG00099",
              "HG03688",
              "HG00741",
              "HG02647",
              "HG01943",
              "HG02559",
              "HG04199"
            ]
          },
          "height": 360
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "abca7_vntr",
      "name": "Tandem repeat catalogue (adotto)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "FromConfigAdapter",
        "features": [
          {
            "uniqueId": "abca7_vntr",
            "refName": "chr19",
            "start": 1049407,
            "end": 1050096,
            "name": "ABCA7 VNTR"
          }
        ]
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "abca7_vntr",
          "type": "LinearBasicDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "type": "LinearVariantDisplay",
          "height": 40
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [],
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "rows": {
            "kept": [
              "HG00099",
              "HG03688",
              "HG00741",
              "HG02647",
              "HG01943",
              "HG02559",
              "HG04199"
            ]
          },
          "height": 360
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hprc/config.json \
  --width 1400 --height 745 \
  --timeout 240000 \
  --spec 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 ABCA7 alleles across 94 samples

TRGT writes each allele as its full sequence, so the details are a wall of CCCCGTGAGC. The TandemRepeat plugin's script rewrites the record as <CNV:TR> alleles, each a run of the locus's 51 bp motif:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-plugin-tandem-repeat/main/scripts/trgt-to-cnv-tr.mjs
# the hosted record has no MS field, TRGT's per-run spans, so each allele
# becomes one run of the motif, its copies the allele's length over 51 bp
node trgt-to-cnv-tr.mjs hprc_abca7_trgt.vcf.gz > hprc_abca7_cnvtr.vcf

Sort, bgzip and index the output, then add it as a track:

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

{
  "trackId": "hprc_abca7_cnvtr",
  "name": "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples",
  "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz",
  "assemblyNames": ["hg38"]
}
jbrowse add-track https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz \
  --trackId hprc_abca7_cnvtr \
  --name "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples" \
  --assemblyNames hg38

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: TRGT alleles at ABCA7 as repeat records, 94 HPRC samples
  • Assembly: hg38

Click Add.

Open this track in JBrowse Web ↗

Open this track in JBrowse Desktop ↗ (JBrowse Desktop 5.0+)

Open chr19:1,049,000-1,050,500 and click the record. A Tandem repeat card opens above the details. With 94 samples the card starts on By allele: one bar per allele, longest first. Hover a copy for its allele, that allele's share and its length.

The ABCA7 VNTR record's Tandem repeat card, by allele: one bar per TRGT allele as copies of the motif, longest first. The dotted line is GRCh38's allele, and all but a handful of the bars run past it.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22sessionTracks%22%3A%5B%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22hprc_abca7_cnvtr%22%2C%22name%22%3A%22TRGT+alleles+at+ABCA7+as+repeat+records%2C+94+HPRC+samples%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fhprc%2Fhprc_abca7_cnvtr.vcf.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%22chr19%3A1%2C049%2C000-1%2C050%2C500%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hprc_abca7_cnvtr%22%2C%22type%22%3A%22LinearVariantDisplay%22%2C%22height%22%3A40%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_abca7_tandem_repeat_alleles

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT alleles at ABCA7 as repeat records, 94 HPRC samples”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr19:1,049,000-1,050,500.

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 https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz \
  --trackId hprc_abca7_cnvtr \
  --name "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples" \
  --assemblyNames hg38

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. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/hprc/config.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "hprc_abca7_cnvtr",
      "name": "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "hprc_abca7_cnvtr",
          "type": "LinearVariantDisplay",
          "height": 40
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hprc/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "type": "VariantTrack",
            "trackId": "hprc_abca7_cnvtr",
            "name": "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples",
            "assemblyNames": [
                "hg38"
            ],
            "adapter": {
                "type": "VcfTabixAdapter",
                "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz"
            }
        }
    ],
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr19:1,049,000-1,050,500",
            "tracks": [
                {
                    "trackId": "hprc_abca7_cnvtr",
                    "type": "LinearVariantDisplay",
                    "height": 40
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > tracks.json <<'JSON'
[
  {
    "type": "VariantTrack",
    "trackId": "hprc_abca7_cnvtr",
    "name": "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples",
    "assemblyNames": [
      "hg38"
    ],
    "adapter": {
      "type": "VcfTabixAdapter",
      "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz"
    }
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/demos/hprc/config.json \
  --tracks tracks.json \
  --assembly hg38 --loc chr19:1,049,000-1,050,500 \
  --track hprc_abca7_cnvtr display:LinearVariantDisplay '{"height":40}' \
  --width 1400 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "hprc_abca7_cnvtr",
      "name": "TRGT alleles at ABCA7 as repeat records, 94 HPRC samples",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/hprc/hprc_abca7_cnvtr.vcf.gz"
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr19:1,049,000-1,050,500",
      "tracks": [
        {
          "trackId": "hprc_abca7_cnvtr",
          "type": "LinearVariantDisplay",
          "height": 40
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hprc/config.json \
  --width 1400 --height 1010 \
  --timeout 120000 \
  --spec session.json -o figure.png

The figure's clicks open the record's repeat copies view, which this command does not do, so its picture differs there.

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.

Click a bar: the other bars fade and the Samples card narrows to the samples with that allele. By haplotype swaps in one bar per called allele, and hovering a copy names its sample.

HG00099's genotype in the sample table is 1/2 with AL 387,3161. In the card, hovering ALT 1's bar gives 387 bp and ALT 2's 3.2 kb, matching what TRGT measured.

Amylase: counting AMY1 copies per haplotype

A gene array varies the same way a tandem repeat does, in whole gene copies. We draw five haplotypes' routes through the salivary amylase array as walk rows, one per structure:

  • On the HPRC page, click the AMY1 example and press Haplotypes.
  • Display types → Graph in the track menu.
  • Enter HG01361.1, HG00133.2, HG00133.1, NA18608.2 and HG00232.1 in Settings → Haplotypes.
  • Walk rows under the Layout row and Uniform under the Color row draw each haplotype's route as a bar.
The five haplotypes' walks across the amylase array in walk rows, longest first, under GRCh38's bar, each boxed with its own CAT genes so its AMY1 copies can be counted on the bar. Blue is on GRCh38's path through the graph and purple off it. Each readout gives the walk's length and its excess over GRCh38.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fpangenome%2Fhprc-grch38%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%3A103610001-103760000%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_v2_1_walk_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22walkrows%22%2C%22color%22%3A%22uniform%22%2C%22subgraphHaplotypes%22%3A%5B%22HG01361%231%22%2C%22HG00133%232%22%2C%22HG00133%231%22%2C%22NA18608%232%22%2C%22HG00232%231%22%5D%2C%22maxRegionBp%22%3A165000%2C%22height%22%3A220%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_amylase_walk_rows

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to 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. Add the next track the same way.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the haplotype walk files”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Graph settings... → HaplotypesThe haplotypes a gbz-base cut is for, as lane names or PanSN prefixes; empty is every haplotype the graph holds.
  4. Type your region of interest into the location box and press Enter.This figure is at chr1:103610001-103760000.

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

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/pangenome/hprc-grch38/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:103610001-103760000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 60
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [
            "HG01361#1",
            "HG00133#2",
            "HG00133#1",
            "NA18608#2",
            "HG00232#1"
          ],
          "maxRegionBp": 165000,
          "height": 220
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:103610001-103760000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 60
        },
        {
          "trackId": "hprc_v2_1_walk_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "color": "uniform",
          "subgraphHaplotypes": [
            "HG01361#1",
            "HG00133#2",
            "HG00133#1",
            "NA18608#2",
            "HG00232#1"
          ],
          "maxRegionBp": 165000,
          "height": 220
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/pangenome/hprc-grch38/config.json \
  --width 1400 --height 540 \
  --timeout 240000 \
  --spec 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.

HG00133.1 has GRCh38's three AMY1 copies and its length, and its bar still shows a long purple stretch, because the graph routes copies of a duplication through nodes off GRCh38's path. Count the AMY1 boxes on each bar to read copy number.

Yilmaz et al. (2024) name each structure by its AMY1 count:

Span against GRCh38'sAMY1 copiesStructure
94 kb shorter1H1a
72 kb shorter2, no AMY2AH2A0
the same3H3r
94 kb longer5H5
188 kb longer7H7

Reproduce it end to end

PacBio publishes TRGT's calls for 100 HPRC samples as a TRGTdb, 94 of which have a call at ABCA7, and the build turns that locus into the VCF this page loads, without re-genotyping anything. It:

  1. downloads the TRGTdb and the repeat catalogue
  2. reads the locus's alleles and every sample's calls out of the database
  3. writes one VCF record: each allele's sequence as an ALT, and per sample the genotype, each allele's length (AL) and the reads spanning it (SD)
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_hprc_abca7_trgt.sh
bash build_hprc_abca7_trgt.sh

The TRGTdb is a directory of Parquet tables, and DuckDB reads a locus's calls straight out of it:

# every sample's allele numbers and spanning-read counts at one locus
duckdb -json -c "
  select regexp_extract(filename, 'sample\.(.*)\.pq', 1) as sample,
    allele_number, spanning_reads
  from read_parquet('hprc_100.tdb/sample.*.pq', filename = true)
  where LocusID = (select LocusID from read_parquet('hprc_100.tdb/locus.pq')
    where chrom = 'chr19' and start = 1049407)"

The amylase build draws five haplotypes as a synteny stack, each aligned to the row under it. It works in four steps, and the commands below run each one on any gbz-base database and any bgzipped, indexed assembly:

  1. Ask the graph where each haplotype crosses two single-copy windows, one either side of the array. The distance between the two is that haplotype's span across the locus, and the spans fall into the published structures.
  2. Pick one haplotype per structure and fetch only the locus from its assembly.
  3. Count each haplotype's gene copies, and align it to its neighbour in the stack, so a band can match copies GRCh38 lacks.
  4. Shift each alignment back onto the whole contig's coordinates.

Get every haplotype's path through a window:

npx --yes -p @gmod/gbz-base gbz-base-query graph.gbz.db \
  --haplotype-index haplotypes.db \
  --sample GRCh38 --contig chr1 --interval 103540000..103541000 \
  --context 0 --alignments > window.json

Fetch one haplotype's copy of the locus:

samtools faidx HG00232_hap1.fa.gz 'HG00232#1#CM089991.1:103491008-103991760' > HG00232.1.fa

Count gene copies, keeping hits over 90% of the gene at 97% identity:

minimap2 -c -x asm20 -N 50 -p 0.5 HG00232.1.fa genes.fa |
  awk '($4-$3)/$2>=0.9 && $10/$11>=0.97 { c[$1]++ } END { for (g in c) print g, c[g] }'

Align two haplotypes to draw them as synteny:

# --secondary=no keeps the primary chain; the secondary ones are paralogous
# copies aligning to each other
minimap2 -c --eqx -x asm20 --secondary=no HG00232.1.fa NA18608.2.fa > adjacent.paf

The whole build, for four of the amylase haplotypes above and hg38:

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

This session opens the script's config.json; point config= at your copy:

Goes at the top level of config.json, replacing any defaultSession there. See Default session.

{
  "defaultSession": {
    "name": "Amylase haplotypes from one AMY1 copy to seven, each aligned to the next",
    "views": [
      {
        "type": "LinearSyntenyView",
        "views": [
          {
            "assembly": "HG01361.1",
            "loc": "CM089019.1:103,831,655-104,050,048",
            "tracks": ["hprc_genes_HG01361_1"]
          },
          {
            "assembly": "hg38",
            "loc": "chr1:103,520,894-103,832,637",
            "tracks": ["hg38_ncbiRefSeq_ucsc"]
          },
          {
            "assembly": "HG00133.1",
            "loc": "CM090045.1:103,669,666-103,981,330",
            "tracks": ["hprc_genes_HG00133_1"]
          },
          {
            "assembly": "NA18608.2",
            "loc": "CM089849.1:103,796,766-104,203,421",
            "tracks": ["hprc_genes_NA18608_2"]
          },
          {
            "assembly": "HG00232.1",
            "loc": "CM089991.1:103,491,008-103,991,760",
            "tracks": ["hprc_genes_HG00232_1"]
          }
        ],
        "tracks": ["amylase_adjacent"],
        "color": { "field": "strand" },
        "drawCurves": true,
        "levelHeights": [110, 110, 110, 110]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "Amylase haplotypes from one AMY1 copy to seven, each aligned to the next",
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "HG01361.1",
          "loc": "CM089019.1:103,831,655-104,050,048",
          "tracks": ["hprc_genes_HG01361_1"]
        },
        {
          "assembly": "hg38",
          "loc": "chr1:103,520,894-103,832,637",
          "tracks": ["hg38_ncbiRefSeq_ucsc"]
        },
        {
          "assembly": "HG00133.1",
          "loc": "CM090045.1:103,669,666-103,981,330",
          "tracks": ["hprc_genes_HG00133_1"]
        },
        {
          "assembly": "NA18608.2",
          "loc": "CM089849.1:103,796,766-104,203,421",
          "tracks": ["hprc_genes_NA18608_2"]
        },
        {
          "assembly": "HG00232.1",
          "loc": "CM089991.1:103,491,008-103,991,760",
          "tracks": ["hprc_genes_HG00232_1"]
        }
      ],
      "tracks": ["amylase_adjacent"],
      "color": { "field": "strand" },
      "drawCurves": true,
      "levelHeights": [110, 110, 110, 110]
    }
  ]
}
EOF

Open this session in JBrowse Web ↗

HG01361.1, hg38, HG00133.1, NA18608.2 and HG00232.1, one AMY1 copy at the top to seven at the bottom, each aligned to the row under it by minimap2 and colored by strand. Each step up in copies opens a wedge over the genes only the longer row has.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Famylase%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22HG01361.1%22%2C%22loc%22%3A%22CM089019.1%3A103%2C831%2C655-104%2C050%2C048%22%2C%22tracks%22%3A%5B%22hprc_genes_HG01361_1%22%5D%7D%2C%7B%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr1%3A103%2C520%2C894-103%2C832%2C637%22%2C%22tracks%22%3A%5B%22hg38_ncbiRefSeq_ucsc%22%5D%7D%2C%7B%22assembly%22%3A%22HG00133.1%22%2C%22loc%22%3A%22CM090045.1%3A103%2C669%2C666-103%2C981%2C330%22%2C%22tracks%22%3A%5B%22hprc_genes_HG00133_1%22%5D%7D%2C%7B%22assembly%22%3A%22NA18608.2%22%2C%22loc%22%3A%22CM089849.1%3A103%2C796%2C766-104%2C203%2C421%22%2C%22tracks%22%3A%5B%22hprc_genes_NA18608_2%22%5D%7D%2C%7B%22assembly%22%3A%22HG00232.1%22%2C%22loc%22%3A%22CM089991.1%3A103%2C491%2C008-103%2C991%2C760%22%2C%22tracks%22%3A%5B%22hprc_genes_HG00232_1%22%5D%7D%5D%2C%22tracks%22%3A%5B%22amylase_adjacent%22%5D%2C%22color%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22drawCurves%22%3Atrue%2C%22levelHeights%22%3A%5B110%2C110%2C110%2C110%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fhprc_amylase_stack

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch 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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: HG01361.1, hg38, HG00133.1, NA18608.2, HG00232.1.
  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.A synteny track the session already has is quicker: pick it under Quick start, which fills in the rows itself.This figure uses “Amylase locus, each haplotype against the next (minimap2)”.
  4. Click Launch.
  5. Synteny view header → palette button → StrandThe palette button's tooltip reads "Color by: ...".
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Drag the bar below a synteny level to resize it.This figure's 4 levels are 110, 110, 110, 110px tall.
  8. Row 1 (HG01361.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “HG01361.1 genes (HPRC release 2 CAT annotation)”.
    2. Type your region of interest into the location box and press Enter.This figure is at CM089019.1:103,831,655-104,050,048.
  9. Row 2 (hg38)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to 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)”.
    2. Type your region of interest into the location box and press Enter.This figure is at chr1:103,520,894-103,832,637.
  10. Row 3 (HG00133.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “HG00133.1 genes (HPRC release 2 CAT annotation)”.
    2. Type your region of interest into the location box and press Enter.This figure is at CM090045.1:103,669,666-103,981,330.
  11. Row 4 (NA18608.2)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “NA18608.2 genes (HPRC release 2 CAT annotation)”.
    2. Type your region of interest into the location box and press Enter.This figure is at CM089849.1:103,796,766-104,203,421.
  12. Row 5 (HG00232.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “HG00232.1 genes (HPRC release 2 CAT annotation)”.
    2. Type your region of interest into the location box and press Enter.This figure is at CM089991.1:103,491,008-103,991,760.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/amylase/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "HG01361.1",
          "loc": "CM089019.1:103,831,655-104,050,048",
          "tracks": [
            "hprc_genes_HG01361_1"
          ]
        },
        {
          "assembly": "hg38",
          "loc": "chr1:103,520,894-103,832,637",
          "tracks": [
            "hg38_ncbiRefSeq_ucsc"
          ]
        },
        {
          "assembly": "HG00133.1",
          "loc": "CM090045.1:103,669,666-103,981,330",
          "tracks": [
            "hprc_genes_HG00133_1"
          ]
        },
        {
          "assembly": "NA18608.2",
          "loc": "CM089849.1:103,796,766-104,203,421",
          "tracks": [
            "hprc_genes_NA18608_2"
          ]
        },
        {
          "assembly": "HG00232.1",
          "loc": "CM089991.1:103,491,008-103,991,760",
          "tracks": [
            "hprc_genes_HG00232_1"
          ]
        }
      ],
      "tracks": [
        "amylase_adjacent"
      ],
      "color": {
        "field": "strand"
      },
      "drawCurves": true,
      "levelHeights": [
        110,
        110,
        110,
        110
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/amylase/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "HG01361.1",
                    "loc": "CM089019.1:103,831,655-104,050,048",
                    "tracks": [
                        "hprc_genes_HG01361_1"
                    ]
                },
                {
                    "assembly": "hg38",
                    "loc": "chr1:103,520,894-103,832,637",
                    "tracks": [
                        "hg38_ncbiRefSeq_ucsc"
                    ]
                },
                {
                    "assembly": "HG00133.1",
                    "loc": "CM090045.1:103,669,666-103,981,330",
                    "tracks": [
                        "hprc_genes_HG00133_1"
                    ]
                },
                {
                    "assembly": "NA18608.2",
                    "loc": "CM089849.1:103,796,766-104,203,421",
                    "tracks": [
                        "hprc_genes_NA18608_2"
                    ]
                },
                {
                    "assembly": "HG00232.1",
                    "loc": "CM089991.1:103,491,008-103,991,760",
                    "tracks": [
                        "hprc_genes_HG00232_1"
                    ]
                }
            ],
            "tracks": [
                "amylase_adjacent"
            ],
            "color": {
                "field": "strand"
            },
            "drawCurves": True,
            "levelHeights": [
                110,
                110,
                110,
                110
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "HG01361.1",
          "loc": "CM089019.1:103,831,655-104,050,048",
          "tracks": [
            "hprc_genes_HG01361_1"
          ]
        },
        {
          "assembly": "hg38",
          "loc": "chr1:103,520,894-103,832,637",
          "tracks": [
            "hg38_ncbiRefSeq_ucsc"
          ]
        },
        {
          "assembly": "HG00133.1",
          "loc": "CM090045.1:103,669,666-103,981,330",
          "tracks": [
            "hprc_genes_HG00133_1"
          ]
        },
        {
          "assembly": "NA18608.2",
          "loc": "CM089849.1:103,796,766-104,203,421",
          "tracks": [
            "hprc_genes_NA18608_2"
          ]
        },
        {
          "assembly": "HG00232.1",
          "loc": "CM089991.1:103,491,008-103,991,760",
          "tracks": [
            "hprc_genes_HG00232_1"
          ]
        }
      ],
      "tracks": [
        "amylase_adjacent"
      ],
      "color": {
        "field": "strand"
      },
      "drawCurves": true,
      "levelHeights": [
        110,
        110,
        110,
        110
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/code/jb2/main/test_data/amylase/config.json \
  --spec session.json \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "HG01361.1",
          "loc": "CM089019.1:103,831,655-104,050,048",
          "tracks": [
            "hprc_genes_HG01361_1"
          ]
        },
        {
          "assembly": "hg38",
          "loc": "chr1:103,520,894-103,832,637",
          "tracks": [
            "hg38_ncbiRefSeq_ucsc"
          ]
        },
        {
          "assembly": "HG00133.1",
          "loc": "CM090045.1:103,669,666-103,981,330",
          "tracks": [
            "hprc_genes_HG00133_1"
          ]
        },
        {
          "assembly": "NA18608.2",
          "loc": "CM089849.1:103,796,766-104,203,421",
          "tracks": [
            "hprc_genes_NA18608_2"
          ]
        },
        {
          "assembly": "HG00232.1",
          "loc": "CM089991.1:103,491,008-103,991,760",
          "tracks": [
            "hprc_genes_HG00232_1"
          ]
        }
      ],
      "tracks": [
        "amylase_adjacent"
      ],
      "color": {
        "field": "strand"
      },
      "drawCurves": true,
      "levelHeights": [
        110,
        110,
        110,
        110
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/amylase/config.json \
  --width 1500 --height 1400 \
  --timeout 240000 \
  --spec 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.

See also

Citations