Skip to main content

Synteny from gene symbols (eight primates)

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.13. Desktop beta builds are coming soon.

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 the coordinates of its genome, with the gene models annotated there. We read the TP53 neighbourhood and a 17q window across the eight primates, then human chromosome 2 as two fused ape chromosomes.

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. The build downloads the annotation and sequence report for each genome.

The build script takes these files from their URLs, so there is nothing to download by hand.

An ortholog table joined on gene names

An ortholog table in the .blocks shape has one row per orthologous group, one column per genome and a gene id in each cell. NCBI's eukaryotic annotation pipeline names a gene after its ortholog, so human TP53 is chimpanzee TP53 and gorilla TP53, and for genomes it annotated 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
# the ortholog of that gene, 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_to_blocks.py joins on the case-folded symbol and handles these cases:

  • A gene named with an NCBI LOC placeholder joins nothing. RefSeq names the salivary amylase copies that way in the other primates.
  • A symbol shared by several genes in one genome gets a row per copy, because a link joins one gene to one gene. The main case is the pseudoautosomal genes, annotated on both X and Y.
  • Open reading frame genes spell differently in the apes (human C1orf35 is chimp C1H1orf35), and the helper reads that back.

The helper prints how much of each column it filled.

Setting up each lane's assembly from its hub

Each genome is also a hub on genomes.jbrowse.org. A hub's config.json holds a whole JBrowse assembly: the 2bit sequence, an alias table that resolves the NC_ names in the BEDs, and the NCBI RefSeq genes. Each lane takes its assembly entry and gene track from its hub, so the ortholog table is the one file built here:

# a GenArk hub path is the accession cut into threes
curl -fO https://jbrowse.org/hubs/genark/GCF/028/858/775/GCF_028858775.2/config.json

The build relabels the lane and adds the short name as an alias, so a session can still say chimp:

{
  "name": "GCF_028858775.2",
  "displayName": "Chimpanzee (NHGRI_mPanTro3-v2.1)",
  "aliases": ["chimp"],
  "sequence": {
    "type": "ReferenceSequenceTrack",
    "trackId": "GCF_028858775.2-ReferenceSequenceTrack",
    "adapter": {
      "type": "TwoBitAdapter",
      "uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/028/858/775/GCF_028858775.2/GCF_028858775.2.2bit",
      "chromSizes": "https://hgdownload.soe.ucsc.edu/hubs/GCF/028/858/775/GCF_028858775.2/GCF_028858775.2.chrom.sizes.txt"
    }
  },
  "refNameAliases": {
    "adapter": {
      "type": "RefNameAliasAdapter",
      "refNameColumnHeaderName": "ucsc",
      "uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/028/858/775/GCF_028858775.2/GCF_028858775.2.chromAlias.txt"
    }
  }
}

refNameColumnHeaderName makes the UCSC names canonical, so the lane headers read chr19. Human is the exception: UCSC serves GRCh38 as hg38 with no GenArk hub, so the human lane is hg38:

Goes in the assemblies array of config.json. See Assemblies.

{
  "name": "hg38",
  "uri": "https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz",
  "refNameAliases": {
    "uri": "https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt"
  },
  "cytobands": "https://jbrowse.org/genomes/GRCh38/cytoBand.txt"
}
jbrowse add-assembly https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz \
  --name hg38 \
  --refNameAliases https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt \
  --config '{"cytobands":"https://jbrowse.org/genomes/GRCh38/cytoBand.txt"}'

hg38 is one of the genomes JBrowse Desktop hosts, with gene tracks already set up: on the start screen click Show all available genomes and pick it. To load the files of this config instead:

In JBrowse Desktop, Open new genome on the start screen (or File → Open genome... in a session), then Open from a URL and paste, one per line:

https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.fai
https://jbrowse.org/genomes/GRCh38/fasta/hg38.prefix.fa.gz.gzi

JBrowse reads the format off the file name. Then fill in:

  • Genome name: hg38
  • refName aliases (under More options): https://s3.amazonaws.com/jbrowse.org/genomes/GRCh38/hg38_aliases.txt
  • cytobands (under More options): https://jbrowse.org/genomes/GRCh38/cytoBand.txt

Each lane draws gene models from a gene track on its assembly. For your own annotation, add one per genome from a bgzipped, tabix-indexed GFF3 (prep) that uses the assembly's refNames:

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

{
  "type": "FeatureTrack",
  "trackId": "chimp_genes",
  "name": "chimp genes",
  "assemblyNames": ["GCF_028858775.2"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "chimp.sorted.gff3.gz"
  }
}
jbrowse add-track chimp.sorted.gff3.gz \
  --trackId chimp_genes \
  --name "chimp genes" \
  --assemblyNames GCF_028858775.2 \
  --load copy

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: chimp.sorted.gff3.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: chimp genes
  • Assembly: GCF_028858775.2

Click Add.

chimp.sorted.gff3.gz is relative to a config.json. Replace it with its URL or its path on this computer.

Loading the eight-genome ortholog track

One SyntenyTrack names all eight assemblies, and blockAssemblies and bedLocations hold one entry per table column, in the order the helper printed. In grammar-of-graphics terms, the display's color is a color scale, and { "field": "cluster" } maps each gene's ortholog group, named by its gene symbol, to a color:

  • A conserved gene is one color down the whole stack, and a lane missing it breaks the column.
  • A gene no group claims is grey.
  • A key naming the groups appears in the top right once the window holds few enough to list. Untick Show... → Show legend in the track menu to hide it.

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

{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "mcscanBlocksLocation": { "uri": "primates.blocks.gz" },
    "blockAssemblies": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3",
      "GCF_049350105.2"
    ],
    "bedLocations": [
      "human.bed.gz",
      "chimp.bed.gz",
      "bonobo.bed.gz",
      "gorilla.bed.gz",
      "sumatran.bed.gz",
      "bornean.bed.gz",
      "siamang.bed.gz",
      "macaque.bed.gz"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "color": { "field": "cluster" }
    }
  ]
}
jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "primate_orthologs",
  "name": "Primate orthologs by gene symbol (8 genomes, RefSeq)",
  "assemblyNames": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "mcscanBlocksLocation": { "uri": "primates.blocks.gz" },
    "blockAssemblies": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3",
      "GCF_049350105.2"
    ],
    "bedLocations": [
      "human.bed.gz",
      "chimp.bed.gz",
      "bonobo.bed.gz",
      "gorilla.bed.gz",
      "sumatran.bed.gz",
      "bornean.bed.gz",
      "siamang.bed.gz",
      "macaque.bed.gz"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "color": { "field": "cluster" }
    }
  ]
}'

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": [
    "hg38",
    "GCF_028858775.2",
    "GCF_029289425.2",
    "GCF_029281585.2",
    "GCF_028885655.2",
    "GCF_028885625.2",
    "GCF_028878055.3",
    "GCF_049350105.2"
  ],
  "adapter": {
    "type": "MCScanBlocksAdapter",
    "mcscanBlocksLocation": { "uri": "primates.blocks.gz" },
    "blockAssemblies": [
      "hg38",
      "GCF_028858775.2",
      "GCF_029289425.2",
      "GCF_029281585.2",
      "GCF_028885655.2",
      "GCF_028885625.2",
      "GCF_028878055.3",
      "GCF_049350105.2"
    ],
    "bedLocations": [
      "human.bed.gz",
      "chimp.bed.gz",
      "bonobo.bed.gz",
      "gorilla.bed.gz",
      "sumatran.bed.gz",
      "bornean.bed.gz",
      "siamang.bed.gz",
      "macaque.bed.gz"
    ]
  },
  "displays": [
    {
      "type": "MultiWaySyntenyDisplay",
      "color": { "field": "cluster" }
    }
  ]
}

primates.blocks.gz, human.bed.gz, chimp.bed.gz, bonobo.bed.gz, gorilla.bed.gz, sumatran.bed.gz, bornean.bed.gz, siamang.bed.gz, macaque.bed.gz are relative to a config.json. Replace each with its URL or its path on this computer.

That shows it in the linear view. For the synteny view, open Add → Linear synteny view, pick the track under Quick start, and click Launch.

Reading the TP53 neighbourhood across eight primates

In a linear genome view on human, the track draws a lane per primate under the human axis, each in that genome's coordinates. Each lane's header names the chromosome and span, with [rev] where the lane runs against human (lane headers). Color by... → Strand, under Ribbons on the track menu, colors each ribbon by whether its two lanes agree in orientation. The session below opens the TP53 neighbourhood with it:

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

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

Open this session in JBrowse Web ↗

The TP53 neighbourhood on human chr17 over seven primate lanes, each drawing its own RefSeq gene models. Every lane has the block in order. The siamang lane is reversed, so its header shows [rev] and its ribbons, drawn straight because the lane is mirrored, are in the reverse-strand color.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22hg38%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%22ribbonColor%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22height%22%3A620%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fprimate_tp53_lanes

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file.This figure uses “Primate orthologs by gene symbol (8 genomes, RefSeq)”.
    1. Track menu → Color by... → Ribbons → Strand
  3. Type your region of interest into the location box and press Enter.This figure is at chr17:7,400,000-7,700,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/primate_orthologs/config.json, which is what the Web button above opens.

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/primate_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:7,400,000-7,700,000",
            "tracks": [
                {
                    "trackId": "primate_orthologs",
                    "type": "MultiWaySyntenyDisplay",
                    "ribbonColor": {
                        "field": "strand"
                    },
                    "height": 620
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --assembly hg38 --loc chr17:7,400,000-7,700,000 \
  --track primate_orthologs display:MultiWaySyntenyDisplay '{"ribbonColor":{"field":"strand"},"height":620}' \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:7,400,000-7,700,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColor": {
            "field": "strand"
          },
          "height": 620
        }
      ]
    }
  ]
}
JSON

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

The figure's clicks close the legend's gene cluster section, which this command does not do, so its picture differs there.

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.

Navigate to chr17:34,000,000-38,000,000 on 17q, where the strand color separates forward blocks from reversed ones.

Human chr17 on 17q over the seven primate lanes, ribbons colored by strand. Blue marks 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 in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22hg38%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%22ribbonColor%22%3A%7B%22field%22%3A%22strand%22%7D%2C%22height%22%3A620%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fprimate_chr17_inversions

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses hg38, loaded from a .2bit genome.
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file.This figure uses “Primate orthologs by gene symbol (8 genomes, RefSeq)”.
    1. Track menu → Color by... → Ribbons → Strand
  3. Type your region of interest into the location box and press Enter.This figure is at chr17:34,000,000-38,000,000.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/primate_orthologs/config.json, which is what the Web button above opens.

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/primate_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr17:34,000,000-38,000,000",
            "tracks": [
                {
                    "trackId": "primate_orthologs",
                    "type": "MultiWaySyntenyDisplay",
                    "ribbonColor": {
                        "field": "strand"
                    },
                    "height": 620
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

npx @jbrowse/img --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --assembly hg38 --loc chr17:34,000,000-38,000,000 \
  --track primate_orthologs display:MultiWaySyntenyDisplay '{"ribbonColor":{"field":"strand"},"height":620}' \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr17:34,000,000-38,000,000",
      "tracks": [
        {
          "trackId": "primate_orthologs",
          "type": "MultiWaySyntenyDisplay",
          "ribbonColor": {
            "field": "strand"
          },
          "height": 620
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --width 1500 --height 860 \
  --timeout 180000 \
  --spec 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.

Human chromosome 2 as two fused ape chromosomes

Human chromosome 2 is two ape chromosomes joined end to end. To see the join:

  • Open human over chimpanzee from Add → Linear synteny view, with primate_orthologs between them
  • Navigate the human row to chr2 and the chimpanzee row to chr12 and chr13, the two chromosomes that hold its halves
  • Pick Target in the palette button menu, which paints each ribbon by the chimpanzee chromosome it lands on
Human chr2 over chimpanzee chr12 and chr13, the hsa2a and hsa2b chromosomes, 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 in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22hg38%22%2C%22loc%22%3A%22chr2%22%2C%22hideNoTracksActive%22%3Atrue%7D%2C%7B%22assembly%22%3A%22GCF_028858775.2%22%2C%22displayedRegionNames%22%3A%5B%22chr12%22%2C%22chr13%22%5D%2C%22hideNoTracksActive%22%3Atrue%7D%5D%2C%22tracks%22%3A%5B%5B%22primate_orthologs%22%5D%5D%2C%22color%22%3A%7B%22field%22%3A%22target%22%7D%2C%22autoDiagonalize%22%3Atrue%2C%22levelHeights%22%3A%5B300%5D%2C%22opacity%22%3A1%7D%5D%7D&sessionName=JBrowse+docs%3A+multiway_synteny%2Fprimate_chr2_fusion

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: hg38, GCF_028858775.2.
  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 “Primate orthologs by gene symbol (8 genomes, RefSeq)”.
  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. Row 1 (hg38)
    1. Type your region of interest into the location box and press Enter.This figure is at chr2.
    2. View menu → Show... → Show no tracks active button (unchecked)
  10. Row 2 (GCF_028858775.2)
    1. View menu → Show... → Show no tracks active button (unchecked)

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/demos/primate_orthologs/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "color": {
        "field": "target"
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ],
      "opacity": 1
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/primate_orthologs/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "hg38",
                    "loc": "chr2",
                    "hideNoTracksActive": True
                },
                {
                    "assembly": "GCF_028858775.2",
                    "displayedRegionNames": [
                        "chr12",
                        "chr13"
                    ],
                    "hideNoTracksActive": True
                }
            ],
            "tracks": [
                [
                    "primate_orthologs"
                ]
            ],
            "color": {
                "field": "target"
            },
            "autoDiagonalize": True,
            "levelHeights": [
                300
            ],
            "opacity": 1
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "color": {
        "field": "target"
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ],
      "opacity": 1
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --spec session.json \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "hg38",
          "loc": "chr2",
          "hideNoTracksActive": true
        },
        {
          "assembly": "GCF_028858775.2",
          "displayedRegionNames": [
            "chr12",
            "chr13"
          ],
          "hideNoTracksActive": true
        }
      ],
      "tracks": [
        [
          "primate_orthologs"
        ]
      ],
      "color": {
        "field": "target"
      },
      "autoDiagonalize": true,
      "levelHeights": [
        300
      ],
      "opacity": 1
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "fusion site",
    "leader": true,
    "anchor": {
      "view": [
        0,
        0
      ],
      "loc": "chr2:113,600,000",
      "fracY": 1
    },
    "dx": 0,
    "dy": 110
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/primate_orthologs/config.json \
  --width 1500 --height 600 \
  --timeout 120000 \
  --spec session.json --annotations callouts.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 multi-lane view, each ape lane picks the contig with more genes in the window and names the other in its header. Show ⟨contig⟩ in this lane on the header menu swaps the lane onto it.

Reproduce it end to end

The script needs the tools under Prerequisites and works in three steps:

  1. Download the eight annotations and sequence reports, and keep the genes on the assembled chromosomes each report names, so no lane lands on an unplaced scaffold.
  2. Join the annotations on gene symbol into one table anchored on human.
  3. Write the config from each genome's hub entry and gene track, plus the ortholog track.
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_primate_orthologs.sh
bash build_primate_orthologs.sh

See also

Citations