Synteny from a Cactus alignment (T2T apes)

We stack ape genomes under a human locus in the order of their family tree and compare each genome with the one above it, so a change of orientation shows up between the two lineages that differ. A stack built from chains against human alone joins every lane to human; comparing neighbours needs a chain between each pair of apes. The Cactus alignment of the telomere-to-telomere ape genomes has one, since its authors publish a chain for every pair of genomes in it. We:

• convert the chains between neighbouring genomes to PAF with PanSN names, and index them as one PIF file
• load the file as one multi-way synteny track over the apes, each lane drawing the RefSeq genes of that ape's hub on genomes.jbrowse.org
• open the track in a linear genome view at ERBB2, with the ribbons colored by strand

Prerequisites#

• chain2paf, built with cargo install --path . from its checkout
• The JBrowse CLI, for jbrowse make-pif
• htslib (bgzip, tabix), which jbrowse make-pif calls
• python3, for the build script
• A running JBrowse instance (the web quickstart or the desktop quickstart)

# Debian/Ubuntu
sudo apt install tabix
# or conda, which has every tool above
conda install -c bioconda -c conda-forge htslib
# any platform
npm install -g @jbrowse/cli@next

The data#

The Cactus alignment of hg38 and the T2T ape assemblies (Yoo et al. 2025), built with Progressive Cactus (Armstrong et al. 2020).

You don't need these files to follow the page: the track configs below read the hosted results. The build script fetches them to rebuild those results, and the chain steps below take your own chains.

Chains between neighbours, from one alignment#

Each lane reads two chains from the file. The chain between hg38 and that ape places the lane under the human window, and the chain between that ape and the one above it draws the ribbons between them. The pairs cover every ape in the stack:

• hg38 against each ape
• chimpanzee against bonobo, bonobo against gorilla, gorilla against the Sumatran orangutan, the Sumatran against the Bornean orangutan, and the Bornean orangutan against the siamang

The steps below start from pairwise chains. A Cactus alignment of your own is a HAL file, from which Cactus's cactus-hal2chains writes the same chains (Cactus documentation). chain2paf reads a chain uncompressed:

gzip -dc genomeA_vs_genomeB.chain.gz > pair.chain

chain2paf writes the chain's query (genomeB) as each PAF row's first sequence and its target (genomeA) as the second. JBrowse reads a PanSN prefix on each name (genome#haplotype#contig) as the genome the sequence belongs to, so every pair can go into one file:

# the prefix is the assembly name JBrowse knows each genome by
chain2paf -i pair.chain \
  | awk -F'\t' -v q=genomeB -v t=genomeA 'BEGIN { OFS = "\t" } { $1 = q "#0#" $1; $6 = t "#0#" $6; print }' \
  >> apes.paf

make-pif sorts and indexes the concatenated pairs, writing each row twice so a query from either genome is one tabix lookup:

jbrowse make-pif apes.paf --out apes.pif.gz

make-pif warns that the file states only some of its pairs. The missing ones are the pairs no two neighbouring lanes need, such as chimpanzee against the siamang.

One track over the apes#

A MultiGenomeIndexedPAFAdapter reads the file and finds each genome by its PanSN prefix. rows.sort stacks the lanes in tree order, so each lane's neighbour above it is the genome its ribbons were aligned to. The assemblies and gene tracks come from each genome's hub unchanged, as in the hosted config.

{
  "type": "SyntenyTrack",
  "trackId": "t2t_apes_cactus",
  "name": "T2T apes (Cactus alignment)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3"
  ],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "https://jbrowse.org/demos/t2t_apes_cactus/apes.pif.gz",
    "assemblyNames": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "t2t_apes_cactus-MultiWaySyntenyDisplay",
      "rows": {
        "sort": [
          "GCF_028858775.2",
          "GCF_029289425.2",
          "GCF_029281585.2",
          "GCF_028885655.2",
          "GCF_028885625.2",
          "GCF_028878055.3"
        ]
      }
    }
  ]
}

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "t2t_apes_cactus",
  "name": "T2T apes (Cactus alignment)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3"
  ],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "https://jbrowse.org/demos/t2t_apes_cactus/apes.pif.gz",
    "assemblyNames": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "t2t_apes_cactus-MultiWaySyntenyDisplay",
      "rows": {
        "sort": [
          "GCF_028858775.2",
          "GCF_029289425.2",
          "GCF_029281585.2",
          "GCF_028885655.2",
          "GCF_028885625.2",
          "GCF_028878055.3"
        ]
      }
    }
  ]
}'

{
  "type": "SyntenyTrack",
  "trackId": "t2t_apes_cactus",
  "name": "T2T apes (Cactus alignment)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3"
  ],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "https://jbrowse.org/demos/t2t_apes_cactus/apes.pif.gz",
    "assemblyNames": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "t2t_apes_cactus-MultiWaySyntenyDisplay",
      "rows": {
        "sort": [
          "GCF_028858775.2",
          "GCF_029289425.2",
          "GCF_029281585.2",
          "GCF_028885655.2",
          "GCF_028885625.2",
          "GCF_028878055.3"
        ]
      }
    }
  ]
}

Orientation at ERBB2 down the tree#

We'll open the track on hg38 around ERBB2 on 17q12. It draws a lane per ape under human, each in the coordinates of that ape's assembly, and each lane header names the chromosome and the span the lane shows, with [rev] where the lane runs against human. The ribbons color by strand (Color by → Strand, under Ribbons in the track menu), blue where a lane runs against the one above it:

{
  "defaultSession": {
    "name": "ERBB2 across seven apes",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "hg38",
        "loc": "chr17:39,400,000-40,200,000",
        "tracks": [
          "hg38-ncbiRefSeq",
          {
            "trackId": "t2t_apes_cactus",
            "type": "MultiWaySyntenyDisplay",
            "height": 600
          }
        ]
      }
    ]
  }
}

jbrowse set-default-session --session - << 'EOF'
{
  "name": "ERBB2 across seven apes",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:39,400,000-40,200,000",
      "tracks": [
        "hg38-ncbiRefSeq",
        {
          "trackId": "t2t_apes_cactus",
          "type": "MultiWaySyntenyDisplay",
          "height": 600
        }
      ]
    }
  ]
}
EOF

✕

Open in JBrowse Web ↗Open in JBrowse Desktop ↗

Open in JBrowse Desktop ↗

Needs JBrowse Desktop 5.0 or newer. If nothing opens, copy the link and paste it into Desktop's Open JBrowse Web link..., on the start screen or under File → Session.

Copy

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Ft2t_apes_cactus%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%22chr17%3A39%2C400%2C000-40%2C200%2C000%22%2C%22tracks%22%3A%5B%22hg38-ncbiRefSeq%22%2C%7B%22trackId%22%3A%22t2t_apes_cactus%22%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Ft2t_apes_cactus_17q

Large dataset: slow to open.

Or rebuild it from your own data:

Steps

Quickest: open the view, then File → Open track... for your files.

From scratch:

1. Open your genome: Open new genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All”.
3. Add the next track the same way. Needs one indexed PAF of several genomes, PanSN-named (.pif.gz + .tbi).This figure uses “T2T apes (Cactus alignment)”.
4. Go to your region in the location box.This figure is at chr17:39,400,000-40,200,000.

Agent

Paste into a coding agent, with your goal on the first line.

Copy

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/demos/t2t_apes_cactus/config.json
- Tracks:
  - NCBI RefSeq - RefSeq All (hg38-ncbiRefSeq), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - T2T apes (Cactus alignment) (t2t_apes_cactus), SyntenyTrack, one indexed PAF of several genomes, PanSN-named (.pif.gz + .tbi), drawn as MultiWaySyntenyDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:39,400,000-40,200,000",
      "tracks": [
        "hg38-ncbiRefSeq",
        {
          "trackId": "t2t_apes_cactus",
          "height": 600
        }
      ]
    }
  ]
}

Redraw the figure headlessly

Copy

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:39,400,000-40,200,000",
      "tracks": [
        "hg38-ncbiRefSeq",
        {
          "trackId": "t2t_apes_cactus",
          "height": 600
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/t2t_apes_cactus/config.json \
  --width 1500 --height 1000 \
  --timeout 240000 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

CLI

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

Copy

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "t2t_apes_cactus",
  "name": "T2T apes (Cactus alignment)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3"
  ],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 600
  }
}'

Run beside config.json, or add --out <dir>. Needs hg38, GCF_028858775.2, GCF_029289425.2, GCF_029281585.2, GCF_028885655.2, GCF_028885625.2, GCF_028878055.3 in the config (jbrowse add-assembly).

Notebook

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

Copy

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/t2t_apes_cactus/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:39,400,000-40,200,000",
            "tracks": [
                "hg38-ncbiRefSeq",
                {
                    "trackId": "t2t_apes_cactus",
                    "height": 600
                }
            ]
        }
    ],
)
app  # display the widget

Image

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

Copy

npx @jbrowse/img --config https://jbrowse.org/demos/t2t_apes_cactus/config.json \
  --assembly hg38 --loc chr17:39,400,000-40,200,000 \
  --track hg38-ncbiRefSeq \
  --track t2t_apes_cactus '{"height":600}' \
  --width 1500 --out figure.svg

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

Session

The session spec behind the figure, over this config.

Copy

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:39,400,000-40,200,000",
      "tracks": [
        "hg38-ncbiRefSeq",
        {
          "trackId": "t2t_apes_cactus",
          "height": 600
        }
      ]
    }
  ]
}

The ribbons turn blue between human and chimpanzee, and again between gorilla and the Sumatran orangutan: chimpanzee, bonobo and gorilla have ERBB2 in one orientation, and human, both orangutans and the siamang in the other.

Reproduce it end to end#

The script works in four steps:

1. Fetch each genome's hub config from genomes.jbrowse.org, which gives its lane the assembly and the NCBI RefSeq gene track.
2. Download the chains: hg38 against each ape, and each ape against the next one down the tree.
3. Convert each chain to PAF with PanSN names and index them all as one file.
4. Write the config, with the lanes stacked in tree order.

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_t2t_apes_cactus_multiway.sh
bash build_t2t_apes_cactus_multiway.sh   # writes ./t2t_apes_cactus_build/config.json

See also#

• Tutorial: Synteny from liftOver chains (hg38 and eight vertebrates)
• Tutorial: Synteny from gene symbols (primates and E. coli)
• Tutorial: Pangenome (Minigraph-Cactus)
• Tutorial: Synteny visualization (all-vs-all minimap2)

External links#

• Cactus T2T ape alignments: https://cglgenomics.ucsc.edu/february-2024-t2t-apes
• The T2T primates project: https://github.com/marbl/Primates
• chain2paf: https://github.com/AndreaGuarracino/chain2paf

Citations#

• Yoo et al. (2025). Complete sequencing of ape genomes
• Armstrong et al. (2020). Progressive Cactus is a multiple-genome aligner for the thousand-genome era

Feedback on this tutorial is welcome: contact us.