Synteny on genomes.jbrowse.org

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.

genomes.jbrowse.org already has UCSC's pairwise liftOver alignments for every genome, so you can turn one on in a linear genome view and launch a two-panel linear synteny view from any chain block. We compare hg38 against T2T-CHM13 (hs1) at TNNT3, a locus the two lay out differently, then against chimp at an FTO intron. A multi-way track then stacks many genomes under hg38 at TNNT3, mouse strains at Nnt and one person's haplotypes at 17q21.31.

Opening a liftOver track

Open hg38 on genomes.jbrowse.org, find Pairwise alignments → liftOver in the track selector and turn on hg38 to Human (hs1) liftOver. Type TNNT3 into the location box; the hosted config ships a name index. The liftOver track draws one feature per chain block.

The hg38 config declares one assembly, and the site loads another genome's config when a track names it.

Launching a synteny view

Right-click any chain block and choose Launch → Linear synteny view with <assembly>. The dialog frames the second panel:

Use CIGAR to map the current visible region to the target finds, from the alignment, the interval in the other genome that matches what is in view. The chain through TNNT3 spans the chromosome, so with the box unticked both panels frame all of chromosome 11.
Horizontally flip inverted targets (ticked by default) appears for a reverse-strand block.
Open in new view appends the result below the linear view, and Replace current view puts it in that view's place.
Copy this view's tracks into its panel sets whether the panel you launched from keeps the tracks that view had on.

Launching from a chain block on the hg38 to Human (hs1) liftOver track at TNNT3: the block's right-click menu, the dialog that frames the second panel, and Replace current view putting the two-panel synteny view in the linear view's place. The hg38 panel opens with the gene track that was open above; the hs1 panel opens empty.

Video

Open the session the video starts in ↗, then take the steps it shows:

The liftOver chain at TNNT3, one feature per aligned block
Right-click a block and launch a synteny view with hs1
Both options on: map this exact window, and keep its tracks
hg38 above hs1 at TNNT3, the ribbons tracing the rearrangement

Steps

Open this view in JBrowse Web ↗ · Open this view 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%2Fucsc%2Fhg38%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%22chr11%3A1%2C881%2C000-1%2C955%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hg38-ncbiRefSeqCurated%22%2C%22geneGlyphMode%22%3A%22longestCoding%22%2C%22height%22%3A90%7D%2C%7B%22trackId%22%3A%22hg38_to_hs1_liftOver%22%2C%22type%22%3A%22LGVSyntenyDisplay%22%2C%22collapseGroupRows%22%3Afalse%2C%22featureHeight%22%3A14%2C%22height%22%3A70%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+synteny%2Fliftover_launch

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:

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.
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 one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
1. Track menu → Gene glyph → Representative transcript
Add the next track the same way. This one needs a bgzip-indexed PAF (.pif.gz + .tbi).This figure uses “hg38 to Human (hs1) liftOver”.
1. Track menu → Show... → Collapse groups to one row (unchecked)Offered only once the reads are grouped, since it is what the groups collapse into.
2. Track menu → Feature height → Custom... → 14px
Type your region of interest into the location box and press Enter.This figure is at chr11:1,881,000-1,955,000.

Spec

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr11:1,881,000-1,955,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 90
        },
        {
          "trackId": "hg38_to_hs1_liftOver",
          "type": "LGVSyntenyDisplay",
          "collapseGroupRows": false,
          "featureHeight": 14,
          "height": 70
        }
      ]
    }
  ]
}

Notebook

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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr11:1,881,000-1,955,000",
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "geneGlyphMode": "longestCoding",
                    "height": 90
                },
                {
                    "trackId": "hg38_to_hs1_liftOver",
                    "type": "LGVSyntenyDisplay",
                    "collapseGroupRows": False,
                    "featureHeight": 14,
                    "height": 70
                }
            ]
        }
    ],
)
app  # display the widget

Image

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/ucsc/hg38/config.json \
  --assembly hg38 --loc chr11:1,881,000-1,955,000 \
  --track hg38-ncbiRefSeqCurated '{"geneGlyphMode":"longestCoding","height":90}' \
  --track hg38_to_hs1_liftOver display:LGVSyntenyDisplay '{"collapseGroupRows":false,"featureHeight":14,"height":70}' \
  --width 1920 --out figure.svg

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

Agent

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": "chr11:1,881,000-1,955,000",
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "geneGlyphMode": "longestCoding",
          "height": 90
        },
        {
          "trackId": "hg38_to_hs1_liftOver",
          "type": "LGVSyntenyDisplay",
          "collapseGroupRows": false,
          "featureHeight": 14,
          "height": 70
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1920 --height 600 \
  --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.

For a locus no single chain block covers, drag-select it on the scale bar and pick Launch → Linear synteny view, whose dialog offers every assembly the session's synteny datasets align to it. See the linear synteny view guide.

Ribbon display settings

The synteny view's settings menu, the sliders button in its header, holds two ribbon settings:

Curved lines draws each ribbon as a curve, easier to follow across a gap
CIGAR indels → Transparent indels leaves insertions and deletions inside each block as see-through gaps

The palette button in the same header sets the ribbons' color, a color scale that maps a field to colors. Strand paints each block by its orientation; the figures below use it.

The same TNNT3 comparison before and after both settings, with the menu that holds them open on top. Top: straight ribbons with colored indels. Bottom: curved ribbons with transparent indels.

The TNNT3 rearrangement

TNNT3 is the locus of Fig 5C in Aganezov et al. (2022). Against GRCh38 the region reads as an inversion plus a deletion that removes the long noncoding RNA LINC01150 in every individual. Pick Strand from the header's palette button, and the segment that moved is the one off-color ribbon.

hg38 (top) vs T2T-CHM13/hs1 (bottom) at TNNT3, colored by strand, with LINC01150 shaded in each. LINC01150 sits upstream of TNNT3 in hg38 and downstream of it in T2T-CHM13, and the blue ribbon joining the two shaded spans is the segment that moved.

Launching hg38 against chimp at an FTO intron

The steps above work for any track under Pairwise alignments → liftOver, one per chain file UCSC publishes against the genome you are in, and for a chain or PAF of your own once it is added as a synteny track (HG002 haplotypes loads a chain, Synteny (pairwise minimap2) a PAF).

Turn on hg38 to Chimp (panTro6) liftOver under Pairwise alignments → liftOver, type chr16:54,036,000-54,054,000, an intron of FTO, into the location box, and launch a synteny view from a chain block:

The four steps on the hg38-to-panTro6 liftOver track across an FTO intron: right-click a chain block, confirm the framing, launch, then add the chimp panel's genes and repeats.

The figure's last step switches to curves and Transparent indels (above), turning the one gap into a hole that lines up with a RepeatMasker element. The chimp panel lacks that element and holds every other repeat in the window.

The chimp panel's track selector offers NCBI RefSeq - RefSeq All and RepeatMasker, brought in with the panTro6 hub. The rest of that hub loads from File → Open connection... as a JBrowse 2 hub at https://jbrowse.org/ucsc/panTro6/config.json.

To start from a gene, the site's ortholog search lists a symbol's NCBI orthologs among the hosted genomes, with a synteny view per row where an alignment exists.

Stacking many genomes under hg38 in one multi-way track

A liftOver track pairs hg38 with one other genome. hg38's staging config also has hg38 vs 240 genomes (liftOver, multi-way), one track over all of hg38's liftOver chains. The track draws hg38 on top and a lane per genome below, each lane with the gene models annotated on that genome, and lives on staging.genomes.jbrowse.org until JBrowse 5 ships.

Open the TNNT3 gene page and scroll to Conserved gene order, which draws the genes around TNNT3 in the 80 species nearest human. ☰ Multi-way synteny lanes at the top of that figure opens the track over the same hg38 window, with a lane for each of those species the track holds.

The TNNT3 gene page on staging.genomes.jbrowse.org at its Conserved gene order section, with the Multi-way synteny lanes link boxed. Open the TNNT3 gene page ↗

The track holds only genomes UCSC publishes a liftOver chain to. Where the gene page's assembly for a species has no chain, its lane is the newest build of that species that does. The link opens a lane for every species it found, too many to read at once, so in the track menu:

Pick Lanes → Choose lanes... and tick chimp, orangutan, rhesus, gray mouse lemur, Chinese tree shrew, naked mole-rat, elephant and platypus, a span from the apes to the monotremes
Pick Color by... → Strand, under Ribbons, to paint a ribbon red where the two lanes it joins run the same way and blue where one is inverted against the other

hg38 at TNNT3 over eight genomes from chimp to platypus, ribbons colored by strand. Down to elephant the ribbons run nearly all red and the genes that lanes name keep hg38's order, while the gaps between ribbons widen down the stack. The platypus lane spreads over many sequences, and its ribbons are blue.

Reading the stack covers the lane labels, [rev], the ribbons and the lane menus.

Choosing which mouse strains become lanes at Nnt

mm39's multi-way liftOver track holds the Mouse Genomes Project strains, and mm39 is C57BL/6J, the strain that lost Nnt exons 7 to 11 (Freeman et al. 2006). We'll open the strain lanes at that gene:

open mm39 on staging.genomes.jbrowse.org and turn on mm39 vs 76 genomes (liftOver, multi-way) under Pairwise alignments
type Nnt into the location box
in the track menu, Lanes → Choose lanes..., type house mouse into the filter and tick the strains, the C57BL/6J T2T assembly among them

mm39 at Nnt over the Mus assemblies the track holds, the C57BL/6J T2T assembly first. The T2T assembly of that strain runs straight under mm39, and every other strain's ribbon fans open in the middle of the gene, over the exons the reference strain lost.

Comparing one person's two haplotypes at the 17q21.31 inversion

hg38's multi-way track holds both haplotypes of the H9 T2T assembly, so a stack can put one person's two chromosomes under the reference. At 17q21.31 the H2 haplotype is a 900 kb inversion (Stefansson et al. 2005), and H9 has one of each. On hg38 at staging.genomes.jbrowse.org, turn on hg38 vs 240 genomes (liftOver, multi-way), type chr17:45,300,000-46,800,000 into the location box, then in the track menu:

Pick Lanes → Choose lanes... and tick the two H9 haplotypes, the HG002 maternal assembly, the NA24631 maternal assembly and T2T-CHM13 (hs1)
Drag the H9 hap2 lane's label to the top of the stack, beside hg38
Pick Color by... → Strand, under Ribbons
Turn off Show... → Show gene labels, since the RefSeq track above names the genes

hg38 from MAPT to NSF over five T2T haplotypes, ribbons colored by strand. The H9 hap2 lane, beside hg38, is the inverted H2 haplotype: its ribbons turn blue across MAPT and KANSL1. Its partner hap1 and the other three haplotypes run red throughout.

Citations

Aganezov S, et al. A complete reference genome improves analysis of human genetic variation. Science (2022). https://doi.org/10.1126/science.abl3533
Freeman HC, Hugill A, Dear NT, Ashcroft FM, Cox RD. Deletion of nicotinamide nucleotide transhydrogenase: a new quantitive trait locus accounting for glucose intolerance in C57BL/6J mice. Diabetes (2006). https://doi.org/10.2337/db06-0358
Stefansson H, et al. A common inversion under selection in Europeans. Nat Genet (2005). https://doi.org/10.1038/ng1508

Feedback on this tutorial is welcome: contact us.

Synteny on genomes.jbrowse.org

Opening a liftOver track#

Launching a synteny view#

Ribbon display settings#

The TNNT3 rearrangement#

Launching hg38 against chimp at an FTO intron#

Stacking many genomes under hg38 in one multi-way track#

Choosing which mouse strains become lanes at Nnt#

Comparing one person's two haplotypes at the 17q21.31 inversion#

See also#

Citations#