Skip to main content

Synteny from gene symbols (eight primates)

We look at one human locus across seven other primates at once. NCBI gives an orthologous gene the same symbol in every species it annotates, so an ortholog table is a join on the gene name, built from eight GFF3 files in seconds. Each primate then becomes a lane under the human view, laid out in that genome's own coordinates with its own gene models annotated on it. The join reaches exactly as far as the naming does, and a gene family whose copies carry placeholder names is where it stops.

Prerequisites

Where the data comes from

Eight RefSeq assemblies, each fetched by accession with the datasets CLI: the current human reference, the six NHGRI telomere-to-telomere ape assemblies (Yoo et al. 2025) and the telomere-to-telomere rhesus macaque. Only the annotation and the sequence report are downloaded, a few hundred megabytes for the eight. Human is GRCh38 rather than T2T-CHM13 so the window's coordinates are the ones the rest of the ecosystem quotes.

An ortholog table joined on gene names

The grape, peach and cacao page builds its ortholog table by aligning coding sequence, and the OrthoFinder page by clustering proteins. Both produce the same .blocks shape: one row per orthologous group, one column per genome, a gene id in each cell. Genomes annotated by one pipeline fill that table a third way. NCBI's eukaryotic annotation pipeline names a gene after its ortholog, so human TP53 is chimpanzee TP53 and gorilla TP53, and the table is a join on the Name attribute of each GFF3.

The join needs only the annotations, so the download is a GFF3 and a sequence report per genome:

# one RefSeq accession per line; the first is the genome the rows are anchored on
datasets download genome accession --inputfile accessions.txt \
  --include gff3,seq-report --filename genomes.zip
unzip genomes.zip

symbols_to_blocks.py reads each GFF3 once, writes a BED of its protein-coding genes and the table, and prints the column order it used:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/symbols_to_blocks.py
# --anchor names the genome whose genes are the rows; every other column is
# that gene's ortholog, or a dot
python3 symbols_to_blocks.py --anchor human -o primates.blocks \
  human=human.gff.gz chimp=chimp.gff.gz bonobo=bonobo.gff.gz gorilla=gorilla.gff.gz \
  sumatran=sumatran.gff.gz bornean=bornean.gff.gz siamang=siamang.gff.gz macaque=macaque.gff.gz

Symbols are compared case-folded, so a mouse Atp5f1a would meet the human ATP5F1A, and a gene whose name is an NCBI LOC placeholder joins nothing. A link joins one gene to one gene, so a symbol several genes in one genome carry gets a row per copy, which the OrthoFinder page draws as a ribbon per copy over maize's whole-genome duplication. Little of that reaches these eight: RefSeq gives a duplicated primate gene either its own lettered symbol, AMY1A against AMY1B, or a LOC placeholder. The pseudoautosomal genes are the exception: annotated on both X and Y, each Y copy gets a separate row. The helper prints how much of each column it filled; for these eight the lanes come back nearly full, because the annotations share one naming pipeline.

Setting up the assemblies

The lanes never read sequence, so each assembly is the chromosome lengths from the sequence report, with the same report as its alias table so chr17 resolves to NC_000017.11:

# the four columns NcbiSequenceReportAliasAdapter reads
dataformat tsv genome-seq --package genomes.zip \
  --inputfile GCF_000001405.40/sequence_report.jsonl \
  --fields genbank-seq-acc,refseq-seq-acc,sequence-name,ucsc-style-name \
  > human.sequence_report.tsv
{
  "name": "human",
  "displayName": "Human (GRCh38.p14)",
  "sequence": {
    "type": "ReferenceSequenceTrack",
    "trackId": "human-ReferenceSequenceTrack",
    "adapter": {
      "type": "ChromSizesAdapter",
      "chromSizesLocation": { "uri": "human.chrom.sizes" }
    }
  },
  "refNameAliases": {
    "adapter": {
      "type": "NcbiSequenceReportAliasAdapter",
      "location": { "uri": "human.sequence_report.tsv" }
    }
  }
}

Each GFF3, filtered to the assembled chromosomes, sorted, bgzipped and tabix-indexed as in the web quickstart, is that genome's gene track, one FeatureTrack per genome. A lane finds its gene models through the session, so the track only has to exist under the lane's assembly name.

The ortholog track

One SyntenyTrack names all eight assemblies. blockAssemblies and bedLocations are positional against the table's columns, in the order the helper printed. The display colors a gene by its symbol, so a conserved gene is one color down the whole stack and a lane missing it breaks the column. The color is a hash of the symbol, so it identifies a gene and carries nothing else. A key naming the symbols appears in the top right once the window holds few enough genes to list, and stays out of the way at the windows below:

{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "human",
    "chimp",
    "bonobo",
    "gorilla",
    "sumatran",
    "bornean",
    "siamang",
    "macaque"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "mcscanBlocksLocation": { "uri": "primates.blocks.gz" },
    "blockAssemblies": [
      "human",
      "chimp",
      "bonobo",
      "gorilla",
      "sumatran",
      "bornean",
      "siamang",
      "macaque"
    ],
    "bedLocations": [
      { "uri": "human.bed.gz" },
      { "uri": "chimp.bed.gz" },
      { "uri": "bonobo.bed.gz" },
      { "uri": "gorilla.bed.gz" },
      { "uri": "sumatran.bed.gz" },
      { "uri": "bornean.bed.gz" },
      { "uri": "siamang.bed.gz" },
      { "uri": "macaque.bed.gz" }
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "primate_orthologs-MultiWaySyntenyDisplay",
      "color": "jexl:feature.name ? randomColor(feature.name) : '#b0b0b0'"
    }
  ]
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "human",
    "chimp",
    "bonobo",
    "gorilla",
    "sumatran",
    "bornean",
    "siamang",
    "macaque"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "mcscanBlocksLocation": { "uri": "primates.blocks.gz" },
    "blockAssemblies": [
      "human",
      "chimp",
      "bonobo",
      "gorilla",
      "sumatran",
      "bornean",
      "siamang",
      "macaque"
    ],
    "bedLocations": [
      { "uri": "human.bed.gz" },
      { "uri": "chimp.bed.gz" },
      { "uri": "bonobo.bed.gz" },
      { "uri": "gorilla.bed.gz" },
      { "uri": "sumatran.bed.gz" },
      { "uri": "bornean.bed.gz" },
      { "uri": "siamang.bed.gz" },
      { "uri": "macaque.bed.gz" }
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "primate_orthologs-MultiWaySyntenyDisplay",
      "color": "jexl:feature.name ? randomColor(feature.name) : '\''#b0b0b0'\''"
    }
  ]
}'

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": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "human",
    "chimp",
    "bonobo",
    "gorilla",
    "sumatran",
    "bornean",
    "siamang",
    "macaque"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "mcscanBlocksLocation": { "uri": "primates.blocks.gz" },
    "blockAssemblies": [
      "human",
      "chimp",
      "bonobo",
      "gorilla",
      "sumatran",
      "bornean",
      "siamang",
      "macaque"
    ],
    "bedLocations": [
      { "uri": "human.bed.gz" },
      { "uri": "chimp.bed.gz" },
      { "uri": "bonobo.bed.gz" },
      { "uri": "gorilla.bed.gz" },
      { "uri": "sumatran.bed.gz" },
      { "uri": "bornean.bed.gz" },
      { "uri": "siamang.bed.gz" },
      { "uri": "macaque.bed.gz" }
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "displayId": "primate_orthologs-MultiWaySyntenyDisplay",
      "color": "jexl:feature.name ? randomColor(feature.name) : '#b0b0b0'"
    }
  ]
}

One locus, eight genomes

Opened in a linear genome view on human, the track draws a lane per genome under the human axis, each fitted to wherever that genome keeps the window's genes. A lane's header names its chromosome, the span it shows and [rev] where it reads the other way, and the ribbons between adjacent lanes join each gene to its ortholog. Color ribbons by → Strand on the track menu colors each ribbon by the strand of the pair it joins, the two lanes' orientations against the human axis multiplied out, rather than by whether the ribbon is drawn crossed. A lane reading the block backwards is drawn mirrored, so its ribbons come out straight while the strand color still marks every one of them as an inversion.

The stack sorts densest-first, so the genome sharing the most of the window's genes sits directly under the anchor: a ribbon joins adjacent lanes only, and a sparse lane in the middle would cut every chain running through it. That makes lane order a property of the window rather than of the phylogeny, and it differs between the pictures below. Move up and Move down on a lane's header menu pin an order, Lanes → Reset lane order on the track menu gives it back, and a session or a config authors the same thing as rowOrder.

{
  "defaultSession": {
    "name": "TP53 neighbourhood across eight primates",
    "views": [
      {
        "type": "LinearGenomeView",
        "assembly": "human",
        "loc": "chr17:7,400,000-7,700,000",
        "tracks": [
          {
            "trackId": "primate_orthologs",
            "type": "MultiWaySyntenyDisplay",
            "ribbonColorBy": "strand",
            "height": 620
          }
        ]
      }
    ]
  }
}
jbrowse set-default-session --session - << 'EOF'
{
  "name": "TP53 neighbourhood across eight primates",
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "human",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColorBy": "strand",
          "height": 620
        }
      ]
    }
  ]
}
EOF

Open this session in JBrowse

The TP53 neighbourhood on human chr17 over seven primate lanes from one gene-symbol ortholog track, each lane drawing the RefSeq gene models annotated on its chromosome. Every lane keeps the block in order; the siamang lane reads it backwards, so its header reads [rev] and its ribbons are the reversed-strand ones, drawn straight because the lane is mirrored. 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 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 human.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “primate_orthologs” track.
  3. Track menu → Color ribbons by → Strand
  4. Drag the bar at the bottom edge of the track to resize it.
  5. Type your region of interest into the location box and press Enter.This figure is at chr17:7,400,000-7,700,000.

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%2Fprimate_orthologs%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22human%22%2C%22loc%22%3A%22chr17%3A7%2C400%2C000-7%2C700%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22primate_orthologs%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22ribbonColorBy%22%3A%22strand%22%2C%22height%22%3A620%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fprimate_tp53_lanes

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "human",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColorBy": "strand",
          "height": 620
        }
      ]
    }
  ]
}

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

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("human", "https://your-server/your-genome.fa.gz"),
    location="chr17:7,400,000-7,700,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["human"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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": "human",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColorBy": "strand",
          "height": 620
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/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.

Zoomed out to four megabases the same track reads as a synteny painting, and color separates the two things it draws. A bundle painted as reversed is a block that lane reads backwards from the lane above it, whether the mirroring left it drawn straight or crossed: one block runs down the middle of the frame with same-orientation flanks on either side of it, and one pair of lanes crosses near the right-hand edge. The headers give the other fact: every lane sits at its own offset and its own scale, and a lane whose header names a multiple is holding the same genes over more sequence.

Four megabases of human chr17 over the seven primate lanes, ribbons colored by strand. Blue is a block read backwards from the lane above: one runs down the middle of the frame between same-orientation flanks, and the two bottom lanes cross where a block flips between them. 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 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 human.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “primate_orthologs” track.
  3. Track menu → Color ribbons by → Strand
  4. Drag the bar at the bottom edge of the track to resize it.
  5. Type your region of interest into the location box and press Enter.This figure is at chr17:34,000,000-38,000,000.

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%2Fprimate_orthologs%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22human%22%2C%22loc%22%3A%22chr17%3A34%2C000%2C000-38%2C000%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22primate_orthologs%22%2C%22type%22%3A%22MultiWaySyntenyDisplay%22%2C%22ribbonColorBy%22%3A%22strand%22%2C%22height%22%3A620%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fprimate_chr17_inversions

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "human",
      "loc": "chr17:34,000,000-38,000,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColorBy": "strand",
          "height": 620
        }
      ]
    }
  ]
}

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

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("human", "https://your-server/your-genome.fa.gz"),
    location="chr17:34,000,000-38,000,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["human"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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": "human",
      "loc": "chr17:34,000,000-38,000,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColorBy": "strand",
          "height": 620
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/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.

A chromosome fusion

Human chromosome 2 is two ape chromosomes joined end to end. The same track in a linear synteny view shows it, with human chr2 on one row and the two chimpanzee chromosomes that carry its halves on the other. The palette button's Target paints each ribbon by the chimpanzee chromosome it lands on.

Human chr2 over chimpanzee hsa2a and hsa2b from the gene-symbol ortholog track, ribbons colored by the chimpanzee chromosome. The orthologs of one chimpanzee chromosome fill human chr2 up to 2q13 and those of the other fill it past there. 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 your genomes: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one), then File → Open genome... for each of the rest.This figure's rows, top to bottom: human, chimp.
  2. Open the view: Add → Linear synteny view, and set the rows to those assemblies in the import form.
  3. Point the import form at your own file: click the arrow between two rows, choose New track, and paste a URL or pick a local file.A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses the “primate_orthologs” track.
  4. Click Launch.
  5. Synteny view header → palette button → TargetThe palette button's tooltip reads "Color by: ...".
  6. Synteny view header → View options → Rows → Re-order chromosomesReorders and flips each row so the best-hit blocks line up on a diagonal. The spec runs it once as the view opens; the menu item is the same thing on demand.
  7. Drag the bar below a synteny level to resize it.This figure's level is 300px tall.
  8. Synteny display settings (the sliders button in the view header) → Opacity → drag to 1Lower values let dense overlapping ribbons show through each other.
  9. Type your region of interest into the location box and press Enter.Row 1 (human) — This figure is at chr2.
  10. View menu → Show... → Show no tracks active button (unchecked)Row 1 (human).
  11. View menu → Show... → Show no tracks active button (unchecked)Row 2 (chimp).

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%2Fprimate_orthologs%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22human%22%2C%22loc%22%3A%22chr2%22%2C%22hideNoTracksActive%22%3Atrue%7D%2C%7B%22assembly%22%3A%22chimp%22%2C%22displayedRegionNames%22%3A%5B%22chr12_hap1_hsa2a%22%2C%22chr13_hap1_hsa2b%22%5D%2C%22hideNoTracksActive%22%3Atrue%7D%5D%2C%22tracks%22%3A%5B%5B%22primate_orthologs%22%5D%5D%2C%22colorBy%22%3A%22target%22%2C%22autoDiagonalize%22%3Atrue%2C%22levelHeights%22%3A%5B300%5D%2C%22alpha%22%3A1%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fprimate_chr2_fusion

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "human",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "chimp",
          "displayedRegionNames": [
            "chr12_hap1_hsa2a",
            "chr13_hap1_hsa2b"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "colorBy": "target",
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ],
      "alpha": 1
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/primate_orthologs/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'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "human",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "chimp",
          "displayedRegionNames": [
            "chr12_hap1_hsa2a",
            "chr13_hap1_hsa2b"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "colorBy": "target",
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ],
      "alpha": 1
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/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.

In the lanes, a window across the fusion point has orthologs on both chimpanzee chromosomes, and a lane follows one contig at a time. Each ape lane picks the one holding more of the window's genes and names the other in its header, and Show ⟨contig⟩ in this lane on the header menu swaps the lane onto it.

Placeholder names

The join is exactly as good as the naming. The salivary amylase cluster on human chr1 is a run of near-identical copies whose human names are lettered (AMY1A, AMY1B, AMY1C), while the other primates' copies were left as placeholder LOC ids, so most of them have no row in the table. Every lane still draws the gene copies annotated in that genome, and the ribbons stop where the naming does. A locus like this needs a real homology call, such as the one the OrthoFinder page builds, or an alignment.

Reproduce it end to end

The script fetches the eight annotations, builds the table and writes the config; see Prerequisites.

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

See also

References