Skip to main content

Pangenome (HPRC) part 5, 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.8. Desktop beta builds are coming soon.

A tandem repeat can be many times longer in one person than in the reference, and the long alleles are the ones association studies care about. An intron of ABCA7 holds a variable number tandem repeat whose expansions were tied to Alzheimer's disease risk (De Roeck et al. 2018). Genotyping it from reads needs reads that span the whole allele, which gets harder the longer the allele is. We draw the repeat once per haplotype from the Human Pangenome Reference Consortium's release 2 graph, where each haplotype is an assembled sequence, set the TRGT genotypes PacBio called from HiFi reads of the same samples on the same bars, and look at the samples where the two disagree. Part 3 set up the graph track this page cuts from.

Experimental

The graph view is a beta plugin, and walk rows is its newest layout. 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):

The TRGT genotypes

TRGT genotypes tandem repeats from HiFi reads against a catalogue of repeat loci, and writes a VCF whose MOTIFS field gives each locus its repeat unit and whose AL field gives each sample's two allele lengths. PacBio published TRGT's calls for 100 HPRC samples over the Genome in a Bottle repeat catalogue. We host the record for the ABCA7 locus as a VCF in TRGT's own format. Add it:

{
  "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"
  }
}

Its one record spans chr19:1,049,408-1,050,096 and names a 51 bp motif. TRGT writes the same fields for your own samples, one VCF each, which trgt merge joins:

# 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

Every haplotype's walk through the repeat

The session below opens ABCA7 with the TRGT track and the catalogue's own row for the VNTR, carried inline as a session track, and under them a graph view cut from hprc_v2_1_gbz_lanes over the same window for every haplotype the graph holds, drawn in Walk rows from the Layout dropdown with Uniform from the Color dropdown:

{
  "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
          }
        ]
      },
      {
        "type": "GraphGenomeView",
        "loadedTrackId": "hprc_v2_1_gbz_lanes",
        "loadedRegion": {
          "refName": "chr19",
          "assemblyName": "hg38",
          "start": 1049407,
          "end": 1050096
        },
        "layoutMode": "walkrows",
        "colorScheme": "uniform",
        "paneHeight": 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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_v2_1_gbz_lanes",
      "loadedRegion": {
        "refName": "chr19",
        "assemblyName": "hg38",
        "start": 1049407,
        "end": 1050096
      },
      "layoutMode": "walkrows",
      "colorScheme": "uniform",
      "paneHeight": 600
    }
  ]
}
EOF

Open this session in JBrowse

Each row is one haplotype's walk between the reference nodes flanking the window, drawn on its own bp axis: blue where GRCh38 carries the same sequence, purple where it does not. GRCh38's own walk is the short bar at the top, the span the catalogue lane marks.

TRGT's calls on the same bars

With the TRGT track in the session, a Repeat dropdown appears beside Walk. Pick the ABCA7 record. The bars now start and end at the record's flanks and are divided into motif-length units, and each readout gives its copy count. The record also carries each sample's genotype, so each walk gets a black tick at the allele TRGT called for it. A VCF lists a sample's alleles in the genotype's order, which is the genotyper's own and says nothing about which assembled haplotype is which, so the walks and the alleles are paired by length. A readout turns red where its walk and its allele are more than 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)

The steps behind the figure above, run against your own data.

  1. Open pane 1: Add → Linear genome view.
  2. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).Pane 1 — This figure uses hg38.
  3. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hg38_ncbiRefSeq_ucsc” track.
  4. Track menu → Show only genes (checked)Pane 1 · “hg38_ncbiRefSeq_ucsc”.
  5. Track menu → Set feature height → CompactPane 1 · “hg38_ncbiRefSeq_ucsc”.
  6. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “hg38_ncbiRefSeq_ucsc”.
  7. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs features defined inline in the config.Pane 1 — This figure uses “Tandem repeat catalogue (adotto)”.
  8. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “Tandem repeat catalogue (adotto)”.
  9. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hprc_abca7_trgt” track.
  10. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “hprc_abca7_trgt”.
  11. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr19:1,049,000-1,050,500.
  12. Track menu (on the graph segments track) → Launch → Graph genome view (this region)Launching from the track is what ties the two panels together: the graph is cut from the same file the lane above it draws.Pane 2.
  13. Set the location box before launching the graph view.The cut is the window the linear view was showing, so the graph covers what you were looking at.Pane 2.
  14. Graph view toolbar → Color → UniformPane 2.

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

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

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

https://jbrowse.org/code/jb2/main/?config=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%5D%7D%2C%7B%22type%22%3A%22GraphGenomeView%22%2C%22loadedTrackId%22%3A%22hprc_v2_1_gbz_lanes%22%2C%22loadedRegion%22%3A%7B%22refName%22%3A%22chr19%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A1049407%2C%22end%22%3A1050096%7D%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%22paneHeight%22%3A600%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_abca7_repeat_units

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 Session spec tab, or jbrowse set-default-session.

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

{
  "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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_v2_1_gbz_lanes",
      "loadedRegion": {
        "refName": "chr19",
        "assemblyName": "hg38",
        "start": 1049407,
        "end": 1050096
      },
      "layoutMode": "walkrows",
      "colorScheme": "uniform",
      "repeatTrackId": "hprc_abca7_trgt",
      "repeatKey": "chr19:1049406-1050096",
      "paneHeight": 600
    }
  ]
}

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

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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_v2_1_gbz_lanes",
      "loadedRegion": {
        "refName": "chr19",
        "assemblyName": "hg38",
        "start": 1049407,
        "end": 1050096
      },
      "layoutMode": "walkrows",
      "colorScheme": "uniform",
      "repeatTrackId": "hprc_abca7_trgt",
      "repeatKey": "chr19:1049406-1050096",
      "paneHeight": 600
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hprc/config.json \
  --session session.json -o figure.png

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

The samples where they disagree

The rows run longest first, so a sample's two haplotypes land far apart. The session below keeps the whole cut and shows seven samples' walks in pairs, named in walkRowSamples: three where the calls land on both walks, two where reads and assemblies part, and two carrying a walk the view declines to score.

{
  "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
          }
        ]
      },
      {
        "type": "GraphGenomeView",
        "loadedTrackId": "hprc_v2_1_gbz_lanes",
        "loadedRegion": {
          "refName": "chr19",
          "assemblyName": "hg38",
          "start": 1049407,
          "end": 1050096
        },
        "layoutMode": "walkrows",
        "colorScheme": "uniform",
        "repeatTrackId": "hprc_abca7_trgt",
        "repeatKey": "chr19:1049406-1050096",
        "walkRowSamples": [
          "HG00099",
          "HG03688",
          "HG00741",
          "HG02647",
          "HG01943",
          "HG02559",
          "HG04199"
        ],
        "paneHeight": 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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_v2_1_gbz_lanes",
      "loadedRegion": {
        "refName": "chr19",
        "assemblyName": "hg38",
        "start": 1049407,
        "end": 1050096
      },
      "layoutMode": "walkrows",
      "colorScheme": "uniform",
      "repeatTrackId": "hprc_abca7_trgt",
      "repeatKey": "chr19:1049406-1050096",
      "walkRowSamples": [
        "HG00099",
        "HG03688",
        "HG00741",
        "HG02647",
        "HG01943",
        "HG02559",
        "HG04199"
      ],
      "paneHeight": 360
    }
  ]
}
EOF

Open this session in JBrowse

HG00099, HG03688 and HG00741 carry a tick at the end of each bar. Reads and assemblies agree on both haplotypes there, across a sample whose two alleles lie far apart, one whose two are both long, and one whose two are both short.

HG02647 and HG01943 are where reads and assemblies part. TRGT called each of them close to homozygous, with reads spanning both alleles, and the graph carries a haplotype neither call reaches — in HG01943 it carries two — so those readouts turn red.

The last two samples each carry a walk the view leaves unscored, because one side of that comparison is not a measurement. No read spanned HG02559's second allele, so TRGT reported the first one twice; the copy lands on the sample's long walk as a grey tick and says nothing about it. HG04199's second walk is partial — that assembly does not span the repeat — and TRGT's long allele sits far past where the bar stops, so here it is the graph that may be missing an allele.

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)

The steps behind the figure above, run against your own data.

  1. Open pane 1: Add → Linear genome view.
  2. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).Pane 1 — This figure uses hg38.
  3. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file. This one needs features defined inline in the config.Pane 1 — This figure uses “Tandem repeat catalogue (adotto)”.
  4. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “Tandem repeat catalogue (adotto)”.
  5. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Pane 1 — This figure uses the “hprc_abca7_trgt” track.
  6. Drag the bar at the bottom edge of the track to resize it.Pane 1 · “hprc_abca7_trgt”.
  7. Type your region of interest into the location box and press Enter.Pane 1 — This figure is at chr19:1,049,000-1,050,500.
  8. Track menu (on the graph segments track) → Launch → Graph genome view (this region)Launching from the track is what ties the two panels together: the graph is cut from the same file the lane above it draws.Pane 2.
  9. Set the location box before launching the graph view.The cut is the window the linear view was showing, so the graph covers what you were looking at.Pane 2.
  10. Graph view toolbar → Color → UniformPane 2.

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

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

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

https://jbrowse.org/code/jb2/main/?config=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%5D%7D%2C%7B%22type%22%3A%22GraphGenomeView%22%2C%22loadedTrackId%22%3A%22hprc_v2_1_gbz_lanes%22%2C%22loadedRegion%22%3A%7B%22refName%22%3A%22chr19%22%2C%22assemblyName%22%3A%22hg38%22%2C%22start%22%3A1049407%2C%22end%22%3A1050096%7D%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%22paneHeight%22%3A360%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%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fhprc_abca7_disagreements

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 Session spec tab, or jbrowse set-default-session.

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

{
  "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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_v2_1_gbz_lanes",
      "loadedRegion": {
        "refName": "chr19",
        "assemblyName": "hg38",
        "start": 1049407,
        "end": 1050096
      },
      "layoutMode": "walkrows",
      "colorScheme": "uniform",
      "repeatTrackId": "hprc_abca7_trgt",
      "repeatKey": "chr19:1049406-1050096",
      "paneHeight": 360,
      "walkRowSamples": [
        "HG00099",
        "HG03688",
        "HG00741",
        "HG02647",
        "HG01943",
        "HG02559",
        "HG04199"
      ]
    }
  ]
}

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

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
        }
      ]
    },
    {
      "type": "GraphGenomeView",
      "loadedTrackId": "hprc_v2_1_gbz_lanes",
      "loadedRegion": {
        "refName": "chr19",
        "assemblyName": "hg38",
        "start": 1049407,
        "end": 1050096
      },
      "layoutMode": "walkrows",
      "colorScheme": "uniform",
      "repeatTrackId": "hprc_abca7_trgt",
      "repeatKey": "chr19:1049406-1050096",
      "paneHeight": 360,
      "walkRowSamples": [
        "HG00099",
        "HG03688",
        "HG00741",
        "HG02647",
        "HG01943",
        "HG02559",
        "HG04199"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hprc/config.json \
  --session session.json -o figure.png

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

Check it against TRGT's genotypes

Click the TRGT record in the linear view. Its sample table gives each sample's AL, the allele lengths the ticks are drawn from, and SD, the reads spanning each allele. HG02559's second allele has no spanning read at all, so its tick is grey: TRGT's second call copies the first, and the walk it landed on takes no verdict.

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, one per sample beside a table of loci and one of alleles, so 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 (1.1 GB) and the repeat catalogue, and writes the ABCA7 record with every sample's genotype.

See also

References