Skip to main content

Pangenome (HPRC): 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.9. Desktop beta builds are coming soon.

A tandem repeat is one sequence copied head to tail, and how many copies a person carries varies. 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 two repeats off it, one bar per haplotype:

  • at LPA, count copies of the kringle IV type 2 repeat
  • 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
Experimental

The graph view is a beta plugin, and walk rows is its newest layout. We welcome your feedback.

Prerequisites

  • the GraphGenomeView plugin, which the HPRC page's launches and the hosted HPRC config the sessions below open already load; hosting your own graph loads it into your own JBrowse

Where the data comes from

HPRC release 2 and PacBio's TRGT genotypes of 100 of its samples (Dolzhenko et al. 2024):

The LPA kringle repeat

LPA carries 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). Open the HPRC page and press graph on the LPA row. JBrowse opens on chr6:160,525,000-160,655,000. Pick Layout → Force-directed layout from the graph track's menu.

The LPA window with the RefSeq genes, UniProt's kringle domains and the HPRC bubbles above the force-directed graph track. The kringle array is the knot of loops in the middle, haloed and labelled as a repeat array, and LPA is pinned under the backbone with its exons along it. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

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

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fhprc.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%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%22colorScheme%22%3A%22reference-position%22%2C%22showDeletionEdges%22%3Atrue%2C%22maxRegionBp%22%3A143000%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_lpa_kiv2

With your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (70px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “UniProt domains (Swiss-Prot)”.
    1. Drag the bar at the bottom edge of the track to resize it (75px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (80px here).
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Show deletion edges (checked)
    4. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr6:160,525,000-160,655,000.

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

Open this view in JBrowse Web ↗

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

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (70px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “UniProt domains (Swiss-Prot)”.
    1. Drag the bar at the bottom edge of the track to resize it (75px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (80px here).
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Show deletion edges (checked)
    4. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr6: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-json '{
  "trackId": "hg38_uniprot_domains_lpa",
  "name": "UniProt domains (Swiss-Prot)",
  "assemblyNames": [
    "hg38"
  ],
  "uri": "https://jbrowse.org/demos/hprc/lpa_uniprot_domains.bed.gz"
}'

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

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

{
  "sessionTracks": [
    {
      "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",
          "colorScheme": "reference-position",
          "showDeletionEdges": 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 — swap an adapter uri for your own file 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",
          "colorScheme": "reference-position",
          "showDeletionEdges": true,
          "maxRegionBp": 143000,
          "height": 600
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.json \
  --width 1000 --height 1170 \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Every 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. This rGFA cut records only segments and links, so which haplotype takes which loop stays unanswered here.

One haplotype's copies

A walk is one haplotype's route through the graph, and the release publishes one per haplotype as a gbz-base database. Type the array's own window, chr6:160,616,002-160,646,753, put the rGFA graph track back to a segments lane with Display types → Feature display, and turn the gbz-base track on from the track selector. Display types → Graph in its track menu then cuts that same track as a graph of the walks. Enter the eight lanes the track drew in the Haplotypes field of Settings, HG00097.1, HG00099.1, HG00128.1, HG00133.1, HG01109.1, HG01123.1, HG01960.1, HG02055.1, and pick Layout → Force-directed layout.

A node draws thicker the more walks carry it (Bandage's depth as width), so the shared backbone is the thick line and one haplotype's own copies are the thin loops. Untick Mark bubbles so the per-route chips stop stacking, then pick HG00133 under Walk: its route keeps its ink 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 Walk. The labelled loop is copies HG00133 walks and GRCh38 does not, its links drawn dark, and the readout states the walk's excess over GRCh38. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

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

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=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_gbz_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%22colorScheme%22%3A%22reference-position%22%2C%22colorDomain%22%3A%7B%22refName%22%3A%22chr6%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A160616002%2C%22end%22%3A160646753%7D%2C%22bubbleSpread%22%3A%22compress%22%2C%22showBubbles%22%3Afalse%2C%22height%22%3A400%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_kiv2_walks

With your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (40px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (50px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Show... → Labels → None
    2. Drag the bar at the bottom edge of the track to resize it (70px here).
    3. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → 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 layout
    3. Track menu → Color → Reference position
    4. Track menu → Settings → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
    5. Track menu → Mark bubbles (unchecked)
    6. Drag the bar at the bottom edge of the track to resize it (400px here).
  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.

Open this view in JBrowse Web ↗

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

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (40px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (50px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 graph (rGFA segments)”.
    1. Track menu → Show... → Labels → None
    2. Drag the bar at the bottom edge of the track to resize it (70px here).
    3. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → 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 layout
    3. Track menu → Color → Reference position
    4. Track menu → Settings → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
    5. Track menu → Mark bubbles (unchecked)
    6. Drag the bar at the bottom edge of the track to resize it (400px here).
  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 from https://jbrowse.org/pangenome/hprc-grch38/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "colorDomain": {
            "refName": "chr6",
            "assemblyName": "hg38",
            "start": 160616002,
            "end": 160646753
          },
          "bubbleSpread": "compress",
          "showBubbles": 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 — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,616,002-160,646,753",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 50
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 70,
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 160616002) / 30751 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "hprc_v2_1_gbz_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "colorDomain": {
            "refName": "chr6",
            "assemblyName": "hg38",
            "start": 160616002,
            "end": 160646753
          },
          "bubbleSpread": "compress",
          "showBubbles": false,
          "height": 400
        }
      ]
    }
  ]
}
JSON

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

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Pick Layout → Walk rows and Color → Uniform: each walk becomes a bar, longest first, blue where GRCh38 carries the same sequence and purple where it does not, so the copies a haplotype adds read as its purple stretch.

The eight-haplotype KIV-2 cut in walk rows, one bar per haplotype under GRCh38's, longest first, under LPA with the KIV-2 bubble boxed in the bubbles lane. The purple stretch of each bar is kringle copies GRCh38 does not carry, and each readout gives the walk's length and its excess over GRCh38. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

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

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=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_gbz_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%22walkrows%22%2C%22colorScheme%22%3A%22uniform%22%2C%22colorDomain%22%3A%7B%22refName%22%3A%22chr6%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A160616002%2C%22end%22%3A160646753%7D%2C%22bubbleSpread%22%3A%22compress%22%2C%22showBubbles%22%3Afalse%2C%22nodeWidth%22%3A%22uniform%22%2C%22contigThickness%22%3A12%2C%22height%22%3A300%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_kiv2_walk_rows

With your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (50px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (80px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → 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 → Color → Uniform
    4. Track menu → Settings → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
    5. Track menu → Mark bubbles (unchecked)
    6. Drag the bar at the bottom edge of the track to resize it (300px here).
  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.

Open this view in JBrowse Web ↗

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

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Gene glyph → Representative transcript
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (50px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (80px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → 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 → Color → Uniform
    4. Track menu → Settings → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
    5. Track menu → Mark bubbles (unchecked)
    6. Drag the bar at the bottom edge of the track to resize it (300px here).
  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 from https://jbrowse.org/pangenome/hprc-grch38/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "colorDomain": {
            "refName": "chr6",
            "assemblyName": "hg38",
            "start": 160616002,
            "end": 160646753
          },
          "bubbleSpread": "compress",
          "showBubbles": false,
          "nodeWidth": "uniform",
          "contigThickness": 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 — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,616,002-160,646,753",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "geneGlyphMode": "longestCoding",
          "displayMode": "compact",
          "height": 50
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 80
        },
        {
          "trackId": "hprc_v2_1_gbz_lanes",
          "type": "LinearGraphDisplay",
          "subgraphHaplotypes": [
            "HG00097.1",
            "HG00099.1",
            "HG00128.1",
            "HG00133.1",
            "HG01109.1",
            "HG01123.1",
            "HG01960.1",
            "HG02055.1"
          ],
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "colorDomain": {
            "refName": "chr6",
            "assemblyName": "hg38",
            "start": 160616002,
            "end": 160646753
          },
          "bubbleSpread": "compress",
          "showBubbles": false,
          "nodeWidth": "uniform",
          "contigThickness": 12,
          "height": 300
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/pangenome/hprc-grch38/config.json \
  --width 1400 --height 740 \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Click the KIV-2 bubble boxed in the bubbles lane. Its details give shortestAlleleLength and longestAlleleLength, the shortest and longest routes the rGFA holds there. Every bar in walk rows falls between them, and GRCh38's, with no purple, is the shortest of the nine.

The ABCA7 VNTR

Each walk's length comes from an assembly, and HiFi reads measure the same repeat independently. An intron of ABCA7 holds a VNTR tied to Alzheimer's disease risk (De Roeck et al. 2018), which PacBio genotyped from HiFi reads in 100 HPRC samples. Open the session below: the genes, the catalogue's VNTR row and the TRGT genotypes, over the gbz-base graph track in Walk rows layout with Uniform color:

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_gbz_lanes",
            "type": "LinearGraphDisplay",
            "layoutMode": "walkrows",
            "colorScheme": "uniform",
            "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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "height": 600
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse Web ↗

Each row is one haplotype's walk between the flanking reference nodes, blue where it matches GRCh38 and purple where it does not; GRCh38's own walk is the short bar at the top.

TRGT's calls on the same bars

TRGT genotypes tandem repeats from HiFi reads. We host its ABCA7 call as this track:

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

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

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

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
# one multi-sample VCF, which the steps below read unchanged
trgt merge --vcf *.vcf.gz --genome GRCh38.fa --output-type z --output merged.vcf.gz

With the TRGT track in the session, a Repeat dropdown appears beside Walk. Pick the ABCA7 record: the bars divide into motif-length units, each walk gets a black tick at the allele TRGT called for it (paired by length), and a readout turns red past 10% apart.

The ABCA7 VNTR in walk rows, one bar per HPRC haplotype, longest first, with the TRGT record picked in the Repeat dropdown, boxed. The catalogue lane marks the VNTR on GRCh38, whose walk is the short blue bar at the top. Each bar is tiled by the motif, and a black tick marks the allele TRGT called for that walk. A red readout is a walk far from its allele. Open this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

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

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=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_gbz_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22walkrows%22%2C%22colorScheme%22%3A%22uniform%22%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

With your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Show only genes (checked)
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (40px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs features defined inline in the config.This figure uses “Tandem repeat catalogue (adotto)”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT repeat genotypes at ABCA7, 100 HPRC samples”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Color → Uniform
    3. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr19:1,049,000-1,050,500.

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

Open this view in JBrowse Web ↗

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

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (hg38)”.
    1. Track menu → Show only genes (checked)
    2. Track menu → Feature height → Compact
    3. Drag the bar at the bottom edge of the track to resize it (40px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs features defined inline in the config.This figure uses “Tandem repeat catalogue (adotto)”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT repeat genotypes at ABCA7, 100 HPRC samples”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Color → Uniform
    3. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at 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 from https://jbrowse.org/demos/hprc/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "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 — swap an adapter uri for your own file 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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "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 \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

The samples where they disagree

The session below shows seven samples' walks in pairs, longest first, named in walkRowSamples:

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

{
  "defaultSession": {
    "name": "ABCA7 VNTR, where reads and assemblies disagree",
    "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_gbz_lanes",
            "type": "LinearGraphDisplay",
            "layoutMode": "walkrows",
            "colorScheme": "uniform",
            "repeatTrackId": "hprc_abca7_trgt",
            "repeatKey": "chr19:1049406-1050096",
            "walkRowSamples": [
              "HG00099",
              "HG03688",
              "HG00741",
              "HG02647",
              "HG01943",
              "HG02559",
              "HG04199"
            ],
            "height": 360
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "ABCA7 VNTR, where reads and assemblies disagree",
  "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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "walkRowSamples": [
            "HG00099",
            "HG03688",
            "HG00741",
            "HG02647",
            "HG01943",
            "HG02559",
            "HG04199"
          ],
          "height": 360
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse Web ↗

HG00099, HG03688 and HG00741 tick at the end of each bar: reads and assemblies agree. HG02647 and HG01943 turn red: TRGT calls each near-homozygous while the graph carries a haplotype neither call reaches (two, in HG01943). HG02559 and HG04199 carry a grey tick: no read spans HG02559's second allele, and HG04199's assembly does not span the repeat, so neither walk gets a verdict.

Seven samples' walks through the ABCA7 VNTR in pairs, each bar carrying 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 this view in JBrowse ↗ (large dataset — this session takes a while to load)

Open this view in JBrowse Desktop ↗

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

Nothing happens?

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

https://jbrowse.org/code/jb2/main/?config=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_gbz_lanes%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22walkrows%22%2C%22colorScheme%22%3A%22uniform%22%2C%22repeatTrackId%22%3A%22hprc_abca7_trgt%22%2C%22repeatKey%22%3A%22chr19%3A1049406-1050096%22%2C%22walkRowSamples%22%3A%5B%22HG00099%22%2C%22HG03688%22%2C%22HG00741%22%2C%22HG02647%22%2C%22HG01943%22%2C%22HG02559%22%2C%22HG04199%22%5D%2C%22height%22%3A360%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_abca7_disagreements

With your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs features defined inline in the config.This figure uses “Tandem repeat catalogue (adotto)”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT repeat genotypes at ABCA7, 100 HPRC samples”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Color → Uniform
    3. Drag the bar at the bottom edge of the track to resize it (360px here).
  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.

Open this view in JBrowse Web ↗

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

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs features defined inline in the config.This figure uses “Tandem repeat catalogue (adotto)”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “TRGT repeat genotypes at ABCA7, 100 HPRC samples”.
    1. Drag the bar at the bottom edge of the track to resize it (40px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “HPRC release 2.1 haplotypes vs GRCh38, read from the graph (gbz-base)”.
    1. Track menu → Layout → Walk rows
    2. Track menu → Color → Uniform
    3. Drag the bar at the bottom edge of the track to resize it (360px here).
  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 from https://jbrowse.org/demos/hprc/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "walkRowSamples": [
            "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 — swap an adapter uri for your own file 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_gbz_lanes",
          "type": "LinearGraphDisplay",
          "layoutMode": "walkrows",
          "colorScheme": "uniform",
          "repeatTrackId": "hprc_abca7_trgt",
          "repeatKey": "chr19:1049406-1050096",
          "walkRowSamples": [
            "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 \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Check it against TRGT's genotypes

Click the TRGT record: its sample table gives AL, the allele lengths behind each tick, and SD, the reads spanning each allele. HG02559's second allele has none, which is why its tick is grey.

Reproduce it end to end

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

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)"

build_hprc_abca7_trgt.sh downloads PacBio's TRGT database and the repeat catalogue, and writes the ABCA7 record with every sample's genotype.

See also

References