# Pangenome (HPRC) part 3: repeat lengths across haplotypes

:::caution JBrowse v5 beta

The tutorials target the JBrowse v5 beta, and the v4.3.0 release
on the [download page](https://jbrowse.org/jb2/download/) 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.21`. Desktop beta builds for Linux and
macOS are on the [releases page](https://github.com/GMOD/jbrowse-components/releases);
the Windows build waits on code signing.

:::

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: the kringle
IV type 2 copies in _LPA_ and their two repeat types, a VNTR in an intron of
_ABCA7_ that PacBio's TRGT also measured from reads, and the _AMY1_ gene copies
in the amylase array. We:

- at _LPA_, draw every haplotype's walk through the array as a bar with the walk
  rows layout, and open a tandem-repeat record's copies by type
- at _ABCA7_, set TRGT's genotypes on the walk rows with the **Repeat** layout
  entry
- choose the samples whose TRGT ticks turn red, and draw TRGT's alleles as a
  tandem-repeat record
- at amylase, read _AMY1_ copies off walk rows, and stack one haplotype per
  structure in a linear synteny view

:::caution Experimental

The graph view is a beta plugin, and walk rows is its newest layout. The
[HPRC page](https://genomes.jbrowse.org/pangenomes/) launches it on the JBrowse
5 development build until JBrowse 5 ships. We welcome your [feedback](https://jbrowse.org/jb2/contact).

:::

## Prerequisites

- the GraphGenomeView plugin. In your own JBrowse,
  [install it from the plugin store](https://jbrowse.org/jb2/docs/user_guides/plugin_store); the HPRC
  page's launches and the hosted HPRC config the sessions below open already
  load it
- for your own samples: [TRGT](https://github.com/PacificBiosciences/trgt) and
  `bcftools`
- for [Which copy is which](#which-copy-is-which) and
  [The ABCA7 alleles across the samples](#the-abca7-alleles-across-the-samples):
  Node, to run our scripts
- for [Reproduce it end to end](#reproduce-it-end-to-end):
  [DuckDB](https://duckdb.org), and for its amylase build `samtools` built with
  libcurl, [`minimap2`](https://github.com/lh3/minimap2), `python3` and Node.js
  with `npm`

<!-- BEGIN GENERATED TUTORIAL_INSTALL samtools,bcftools,minimap2,duckdb,node,trgt,htslib -->

```bash
# Debian/Ubuntu
sudo apt install samtools bcftools minimap2 nodejs tabix
# or conda, which has every tool above
conda install -c bioconda -c conda-forge samtools bcftools minimap2 \
  duckdb-cli nodejs trgt htslib
```

<!-- END GENERATED TUTORIAL_INSTALL samtools,bcftools,minimap2,duckdb,node,trgt,htslib -->

## The data

[HPRC release 2](https://doi.org/10.64898/2026.07.21.739710) and PacBio's TRGT
genotypes of a subset of its samples (Dolzhenko et al. 2024), most of which have
a call at _ABCA7_.

You don't need these files to follow the page: the track configs below read the
hosted results. The [build script](#reproduce-it-end-to-end) fetches them to
rebuild those results. The tandem-repeat VCF step takes a cut of your own graph
over your own array, and the TRGT step your own aligned HiFi reads and repeat
catalogue.

| What it is                                                                   | File                                                                                                                                                                     |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| TRGT's genotypes over the Genome in a Bottle repeat catalogue, a TRGTdb      | [adotto_hprc.tdb.tar](https://zenodo.org/records/8329210/files/adotto_hprc.tdb.tar)                                                                                      |
| The catalogue itself                                                         | [adotto_repeats.hg38.bed.gz](https://zenodo.org/records/8329210/files/adotto_repeats.hg38.bed.gz)                                                                        |
| The assemblies, for the amylase build                                        | [assemblies_release2_v1.0.index.csv](https://raw.githubusercontent.com/human-pangenomics/hprc_intermediate_assembly/main/data_tables/assemblies_release2_v1.0.index.csv) |
| The graph cut over the KIV-2 array, eight haplotypes' walks with their bases | [hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa](https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa)                                            |

<details>
<summary>Read by URL (no download needed)</summary>

| What it is                                                                                                                | File                                                    |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Our tabix index files cut from the release's rGFA graph and from its haplotype walks, with the build recorded beside them | [README.txt](https://jbrowse.org/demos/hprc/README.txt) |

</details>

## 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](https://genomes.jbrowse.org/pangenomes/hprc), click the
  **LPA** example, and click **Graph** under **More about this window**. JBrowse
  opens on `chr6:160,525,000-160,655,000`.
- Tick **Show → Show bubble halos** in the graph track's menu.

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

<Figure caption="LPA over the force-directed graph track. The KIV-2 array is the haloed knot of loops on the right." src="/img/pangenome/hprc_lpa_kiv2.png" />

Session spec, on config <https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/hprc.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",
          "geneGlyphMode": "representative",
          "displayMode": "compact",
          "height": 70
        },
        {
          "trackId": "hg38_uniprot_domains_lpa",
          "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
        }
      ]
    }
  ]
}
```

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.

## Haplotypes' routes through the KIV-2 array {#one-haplotypes-copies}

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** <!-- menu-path-ok --> 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.

The track draws a node thicker the more walks pass through 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.

<Figure caption="The KIV-2 cut with HG00133 picked under Haplotypes. The dark links are copies on HG00133's walk and absent from GRCh38." src="/img/pangenome/graph_kiv2_walks.png" />

Session spec, on config <https://jbrowse.org/pangenome/hprc-grch38/config.json>:

```json
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,616,002-160,646,753",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "geneGlyphMode": "representative",
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "hprc_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 50
        },
        {
          "trackId": "hprc_minigraph_segments",
          "type": "LinearBasicDisplay",
          "labels": {
            "name": {
              "show": false
            },
            "description": {
              "show": false
            }
          },
          "height": 70,
          "encoding": {
            "color": {
              "value": "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
        }
      ]
    }
  ]
}
```

## Every haplotype's KIV-2 array as a bar {#every-haplotypes-copies}

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

Read the bars this way:

- **Length counts copies.** Each copy a haplotype adds lengthens its bar.
- **Purple marks sequence off GRCh38's path.** The graph routes most copies
  through nodes off GRCh38's path.
- **Gold is steps the file did not load.** The walk file abridges the costliest
  walks through the array, and a bar marks its length ≈ where the walk runs on
  past the window. Right-click one and take the **Load the … abridged steps**
  row, which counts them, to read it in full.
- **Hover a bar** for its haplotype, length and excess over GRCh38, since the
  rows pack too thin to letter.

<Figure caption="Every HPRC haplotype's walk across the KIV-2 array in walk rows. Purple is sequence off GRCh38's path; gold is an abridged walk's steps the file did not load." src="/img/pangenome/graph_kiv2_walk_rows.png" />

Session spec, on config <https://jbrowse.org/pangenome/hprc-grch38/config.json>:

```json
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,616,002-160,646,753",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "geneGlyphMode": "representative",
          "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
        }
      ]
    }
  ]
}
```

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 bar lengths range from about the shortest
to about the longest.

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 {#which-copy-is-which}

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 do not identify which copy is which. A record that lists each
haplotype's copies identifies them.

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, and a phased genotype puts each allele on
its haplotype:

```json
{
  "trackId": "hprc_kiv2_copies_all",
  "name": "LPA KIV-2 copies by unit, all HPRC haplotypes",
  "uri": "https://jbrowse.org/demos/hprc/hprc_kiv2_copies_all.vcf.gz",
  "assemblyNames": ["hg38"]
}
```

CLI:

```bash
jbrowse add-track https://jbrowse.org/demos/hprc/hprc_kiv2_copies_all.vcf.gz \
  --trackId hprc_kiv2_copies_all \
  --name "LPA KIV-2 copies by unit, all HPRC haplotypes" \
  --assemblyNames hg38
```

Opens on config <https://jbrowse.org/ucsc/hg38/config.json> at `chr6:160,616,002-160,646,753`

Turn the track on and click the record. A **Tandem repeat** card opens above the
details, each copy colored by its type. With this many haplotypes it starts on
**By allele**: one bar per allele, longest first, and hovering a copy gives that
allele's share of the haplotypes. **By haplotype** draws one bar per haplotype,
and hovering a copy names its haplotype. Click a bar: the other bars fade and
the **Samples** card narrows to the samples with that allele.

<Figure caption="The KIV-2 record's Tandem repeat card, by haplotype. Each bar is one haplotype's array, each copy colored by its type." src="/img/pangenome/hprc_kiv2_copies.png" />

Session spec, on config <https://jbrowse.org/demos/hprc/config.json>:

```json
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr6:160,596,000-160,666,000",
      "tracks": [
        {
          "trackId": "hprc_kiv2_copies_all",
          "height": 40
        }
      ]
    }
  ]
}
```

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, start from a cut of the graph over
the array: a GFA whose W lines are the walks across it, from the reference nodes
on either side, and whose S lines hold those nodes' bases. We host the cut for
the eight haplotypes:[^kiv2-cut]

```bash
curl -fO https://jbrowse.org/demos/hprc/hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa
```

[`tandem-repeat-vcf.mjs`](https://github.com/GMOD/jbrowse-components/blob/main/scripts/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:

```bash
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/tandem-repeat-vcf.mjs
```

```bash
printf 'chr6\t160616002\t160646753\tKIV-2\n' > arrays.bed
node tandem-repeat-vcf.mjs hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.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:

```bash
printf 'chr6\t160617116\t160617276\texon 1\t0\t-\nchr6\t160618483\t160618665\texon 2\t0\t-\n' > kiv2_exons.bed
node tandem-repeat-vcf.mjs hprc-v2.1-mc-grch38.kiv2.eight-haplotypes.gfa \
  --bed arrays.bed --name KIV-2 \
  --sites kiv2_exons.bed > /dev/null
```

JBrowse draws a repeat finder's output 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](https://github.com/PacificBiosciences/trgt), a tandem repeat genotyper
for HiFi reads, measured the same repeat in HPRC samples. We host its _ABCA7_
call as this track:

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

CLI:

```bash
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 \
  --indexFile https://jbrowse.org/demos/hprc/hprc_abca7_trgt.vcf.gz.csi
```

Opens on config <https://jbrowse.org/ucsc/hg38/config.json> at `chr19:1,049,000-1,050,500`

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

```bash
# 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:

```json
{
  "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",
            "filter": ["geneLike"],
            "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",
            "encoding": { "color": { "value": "uniform" } },
            "subgraphHaplotypes": [],
            "repeatTrackId": "hprc_abca7_trgt",
            "height": 600
          }
        ]
      }
    ]
  }
}
```

CLI:

```bash
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",
          "filter": ["geneLike"],
          "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",
          "encoding": { "color": { "value": "uniform" } },
          "subgraphHaplotypes": [],
          "repeatTrackId": "hprc_abca7_trgt",
          "height": 600
        }
      ]
    }
  ]
}
EOF
```

Opens on config <https://jbrowse.org/demos/hprc/config.json>

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.

<Figure caption="The ABCA7 VNTR in walk rows with the TRGT record picked under Repeat. Ticks are TRGT's calls, red where a call is far from its walk." src="/img/pangenome/hprc_abca7_repeat_units.png" />

Session spec, on config <https://jbrowse.org/demos/hprc/config.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",
          "filter": [
            "geneLike"
          ],
          "displayMode": "compact",
          "height": 40
        },
        {
          "trackId": "abca7_vntr",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "genotypes": {
            "show": false
          },
          "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
        }
      ]
    }
  ]
}
```

## Samples where reads and assemblies disagree

To compare 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 groups:

- The ticks of HG00099, HG03688 and HG00741 sit at each bar's end: reads and
  assemblies agree.
- The ticks of HG02647 and HG01943 are 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 that cannot be compared with TRGT's call.
  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 shows
  that 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.

<Figure caption="Samples' walks through the ABCA7 VNTR, each marked with TRGT's allele as a tick." src="/img/pangenome/hprc_abca7_disagreements.png" />

Session spec, on config <https://jbrowse.org/demos/hprc/config.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",
          "height": 40
        },
        {
          "trackId": "hprc_abca7_trgt",
          "genotypes": {
            "show": false
          },
          "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
        }
      ]
    }
  ]
}
```

## The ABCA7 alleles across the samples

TRGT writes each allele as its full sequence, so the details panel shows long
runs of `CCCCGTGAGC`. Our script rewrites the record as `<CNV:TR>` alleles, each
a run of the locus's 51 bp motif:

```bash
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/trgt-to-cnv-tr.mjs
```

```bash
# 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](https://jbrowse.org/jb2/docs/quickstart_web#vcf) the output, then add it as a
track:

```json
{
  "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"]
}
```

CLI:

```bash
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
```

Opens on config <https://jbrowse.org/ucsc/hg38/config.json> at `chr19:1,049,000-1,050,500`

Open `chr19:1,049,000-1,050,500` and click the record. The **Tandem repeat**
card starts on **By allele** here too. Hover a copy for its allele, that
allele's share and its length.

<Figure caption="The ABCA7 VNTR record's Tandem repeat card, by allele. The dotted line is GRCh38's allele." src="/img/pangenome/hprc_abca7_tandem_repeat_alleles.png" />

Session spec, on config <https://jbrowse.org/demos/hprc/config.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",
          "height": 40
        }
      ]
    }
  ]
}
```

## Amylase: counting AMY1 copies per haplotype {#amylase}

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

- On the [HPRC page](https://genomes.jbrowse.org/pangenomes/hprc), click the
  **AMY1** example, then **Haplotypes** under **More about this window**.
- **Display types → Graph** in the track menu.
- Enter `HG01361.1`, `HG00133.2`, `HG00133.1`, `NA18608.2` and `HG00232.1` in
  **Graph settings... → Haplotypes**.
- **Walk rows** under the **Layout** row and **Uniform** under the **Color** row
  draw each haplotype's route as a bar.

<Figure caption="Haplotypes' walks across the amylase array, each over the CAT genes of that haplotype's assembly. Purple is sequence off GRCh38's path." src="/img/pangenome/hprc_amylase_walk_rows.png" />

Session spec, on config <https://jbrowse.org/pangenome/hprc-grch38/config.json>:

```json
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr1:103610001-103760000",
      "tracks": [
        {
          "trackId": "hg38_ncbiRefSeq_ucsc",
          "geneGlyphMode": "representative",
          "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
        }
      ]
    }
  ]
}
```

Count the _AMY1_ boxes on each bar to read copy number. As at KIV-2, purple does
not count copies: HG00133.1 has GRCh38's three _AMY1_ copies and its length, and
its bar still shows a long purple stretch. Each bar boxes the CAT genes of that
haplotype's assembly, and GRCh38's row the view's GRCh38 genes. CAT names each
copy after the GRCh38 copy it projected, so one name can label several boxes.

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

| Span against GRCh38's | _AMY1_ copies | Structure |
| --------------------- | ------------- | --------- |
| 94 kb shorter         | 1             | H1a       |
| 72 kb shorter         | 2, no _AMY2A_ | H2A0      |
| the same              | 3             | H3r       |
| 94 kb longer          | 5             | H5        |
| 188 kb longer         | 7             | H7        |

### Each haplotype aligned to the next {#amylase-stack}

Walk rows count copies; a synteny stack shows which copy of one haplotype
matches which copy of its neighbour. The commands below run on any
`gfa-to-tabix --walks` file and any bgzipped, indexed assembly.

Fetch the script that reads a window's walks, then the walk reader it imports:

```bash
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/walk_spans.mjs
```

```bash
# the majors walk_spans.mjs is written against; a new major can change the API
npm install @jbrowse/graph-walks@6 generic-filehandle2@2
```

Where a haplotype's walk crosses a single-copy window on either side of the
array gives its span across the locus, and the span places it in one of the
structures above. Get where every walk crosses one window, one line per walk
with its contig coordinates:

```bash
# the walk file is a path or a URL, with its .walks.gz.idx beside it
node walk_spans.mjs graph.GRCh38.walks.gz 'GRCh38#0#chr1' 103540000 103541000 > left.tsv
```

Fetch one haplotype's copy of the locus:

<!-- from: scripts/build_amylase_haplotypes.sh -->

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

Cut the three genes out of GRCh38 as `genes.fa`, one record per gene:

```bash
# AMY2B, AMY2A and AMY1A as GRCh38 holds them, each record renamed to its gene
samtools faidx GRCh38.fa chr1:103554644-103579534 | sed '1s/.*/>AMY2B/' > genes.fa
samtools faidx GRCh38.fa chr1:103616651-103625780 | sed '1s/.*/>AMY2A/' >> genes.fa
samtools faidx GRCh38.fa chr1:103655519-103664554 | sed '1s/.*/>AMY1/' >> genes.fa
```

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

<!-- from: scripts/build_amylase_haplotypes.sh -->

```bash
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:

<!-- from: scripts/build_amylase_haplotypes.sh -->

```bash
# --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 session below opens the script's `config.json`; point `config=` at your
copy:

```json
{
  "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"],
        "encoding": { "color": "strand" },
        "mark": { "interpolate": "bump" },
        "levelHeights": [110, 110, 110, 110]
      }
    ]
  }
}
```

CLI:

```bash
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"],
      "encoding": { "color": "strand" },
      "mark": { "interpolate": "bump" },
      "levelHeights": [110, 110, 110, 110]
    }
  ]
}
EOF
```

Opens on config <https://jbrowse.org/code/jb2/main/test_data/amylase/config.json>

<Figure caption="Haplotypes from the fewest AMY1 copies at the top to the most at the bottom, each aligned to the row below by minimap2." src="/img/multiway_synteny/hprc_amylase_stack.png" />

Session spec, on config <https://jbrowse.org/code/jb2/main/test_data/amylase/config.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"
      ],
      "encoding": {
        "color": "strand"
      },
      "mark": {
        "interpolate": "bump"
      },
      "levelHeights": [
        110,
        110,
        110,
        110
      ]
    }
  ]
}
```

## Reproduce it end to end

PacBio publishes TRGT's calls for a subset of HPRC samples as a TRGTdb, most 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`)

```bash
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:

<!-- from: scripts/build_hprc_abca7_trgt.sh -->

```bash
# 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 runs the commands under
[Each haplotype aligned to the next](#amylase-stack) for the haplotypes in that
session and hg38. It:

1. reads where each haplotype's walk crosses a single-copy window on either side
   of the array, which gives its span and so its structure
2. picks one haplotype per structure and fetches only the locus from its
   assembly
3. counts each haplotype's gene copies, and aligns it to its neighbour in the
   stack
4. shifts each alignment back onto the whole contig's coordinates

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

## See also

- **Tutorial:** [](https://jbrowse.org/jb2/docs/tutorials/pangenome_hprc)
- **Tutorial:** [Pangenome (HPRC) part 2: haplotypes against each other](https://jbrowse.org/jb2/docs/tutorials/pangenome_hprc_haplotypes)
- [BandageJS](https://jbrowse.org/demos/bandagejs/)

## External links

- [ggbandage](https://github.com/GMOD/ggbandage), which draws
  [KIV-2](https://github.com/GMOD/ggbandage/blob/main/docs/gallery.md#kiv-2-copy-number-as-walk-rows)
  and
  [amylase](https://github.com/GMOD/ggbandage/blob/main/docs/gallery.md#amylase-copy-number-in-twelve-haplotypes)
  copy number as walk rows in ggplot2.
- [ggtubemap](https://github.com/GMOD/ggtubemap), which draws
  [a tandem repeat near LPA](https://github.com/GMOD/ggtubemap#from-a-walk-file)
  as a tube map in ggplot2.

## Citations

- Schmidt et al. (2016).
  [Structure, function, and genetics of lipoprotein(a)](https://doi.org/10.1194/jlr.R067314)
- Wick et al. (2015).
  [Bandage: interactive visualization of de novo genome assemblies](https://doi.org/10.1093/bioinformatics/btv383)
- De Roeck et al. (2018).
  [An intronic VNTR affects splicing of ABCA7 and increases risk of Alzheimer's disease](https://doi.org/10.1007/s00401-018-1841-z)
- Dolzhenko et al. (2024).
  [Characterization and visualization of tandem repeats at genome scale](https://doi.org/10.1038/s41587-023-02057-3)
- [TRGT repeat catalogues and HPRC genotypes](https://doi.org/10.5281/zenodo.8329210)
- [HPRC release 2](https://doi.org/10.64898/2026.07.21.739710)
- Yilmaz et al. (2024).
  [Reconstruction of the human amylase locus reveals ancient duplications seeding modern-day variation](https://doi.org/10.1126/science.adn0609)
- Li (2018).
  [Minimap2: pairwise alignment for nucleotide sequences](https://doi.org/10.1093/bioinformatics/bty191)

[^kiv2-cut]:
    `gbz-base-query --keep` cut it from HPRC's gbz-base database, and
    [README.txt](https://jbrowse.org/demos/hprc/README.txt) gives the command. A
    walk file holds node bases only when `gfa-to-tabix --walks --sequences`
    writes it.

