Skip to main content

Multi-way synteny display

The multi-way synteny display stacks several genomes under a linear genome view, one lane per genome, each drawn in that genome's own coordinates. The view's genome is the anchor on top. Each lane fits itself to wherever the alignment places the anchor's window, and ribbons join the matching stretches or genes between lanes.

A synteny track over several genomes draws this way from its track menu: Display types → Multi-way synteny display.

What a ribbon joins

The track's source decides which two lanes a ribbon connects:

SourceA ribbon joinsWorked through in
Pairwise chains against one genome (MultiPairwiseSyntenyAdapter)a lane to the anchor, whichever lane sits above itSynteny from liftOver chains (hg38 and eight vertebrates), Synteny on genomes.jbrowse.org
One PAF holding many pairs (MultiGenomePAFAdapter, indexed or not)a lane to the lane above itSynteny from a Cactus alignment (T2T apes), Synteny visualization (all-vs-all minimap2), Rearrangements between genomes by type (SyRI)
An ortholog table (MCScanBlocksAdapter)one ortholog group, down adjacent lanesSynteny from an ortholog table (grape, peach, cacao), Synteny from gene symbols (eight primates), Synteny from gene symbols (E. coli genomes), Synteny visualization (OrthoFinder orthogroups)
Haplotype walks through a pangenome graph (WalkTabixSyntenyAdapter)the nodes two neighbouring haplotypes sharePangenome (HPRC) part 2: haplotypes against each other

So a blue ribbon means "inverted against the anchor" on a chain track and "inverted against the lane above" on a neighbour-pair track. Stacking the genomes in tree order makes the second kind read as a walk down the tree.

Reading a lane header

Each lane has its own scale, printed in its header:

  • the left end shows where the lane starts, with [rev] where the lane runs against the anchor
  • the right end shows the span the lane draws, and that span as a multiple of the anchor's window, rounded to one of a few fixed steps
  • the ticks fall at one interval shared by every lane
  • also at names a second stretch the window aligns to, a window or more away from the one the lane draws

A lane with no readable gene track (GFF3, GTF, BigBed or BED) on its assembly outlines gene spans from the table where it has them, labeled no annotation. The view's gridlines stop at the anchor, the one lane they fit.

Ribbons

  • Color by... → Strand, under Ribbons in the track menu, is the default: red where the two lanes a ribbon joins run the same way, blue where one is reversed. A lane drawn reversed has its ribbons run straight on screen while the color still marks them as inverted.
  • Hover a ribbon to light the same alignment or ortholog group in every lane it reaches.
  • Click a ribbon to open its details; click empty canvas to clear the outline.
  • A ribbon joins a gene to the next lane that places it when the lane between places nothing, so a sparse lane mid-stack cuts no chain. A track whose ribbons all join the anchor draws each gutter against the anchor instead.

Choosing and ordering lanes

The Lanes submenu in the track menu holds the stack's controls:

  • Choose lanes... picks which genomes draw, with a filter box for long lists.
  • Order lanes by structure stacks each lane beside the one whose insertions and deletions against the anchor are most alike.
  • Freeze lanes keeps every lane where it is as you pan and zoom. While frozen, drag a lane to slide it.

Drag a lane label to move that lane. In the display config, rows.sort pins the lanes it names to the top, in that order, and the rest follow densest-first, so the order holds across a pan; grouping and ordering has the rows config.

Where a lane draws

A lane draws one stretch of one chromosome at a time, the stretch holding most of the window. Where the window aligns somewhere else too, the lane header menu offers it:

  • Show ⟨chromosome⟩ in this lane moves the lane onto another chromosome the window aligns to.
  • Show ⟨region⟩ in this lane moves it onto the other stretch its header names after also at.
  • Flip lane turns the lane the other way on the same chromosome, for a lane whose blocks split about evenly between the two orientations.
  • Let the lane choose where it draws (pinned to ⟨chromosome⟩) undoes either Show item.
  • Let the lane choose its orientation (pinned on ⟨chromosome⟩) undoes a flip.

The lane header menu

The ⋮ on a lane header, or a right-click on its name, opens the lane menu. The Lanes submenu in the track menu also lists every lane by name, each with the same items.

  • Open ⟨genome⟩ at the matching region opens that genome in a separate linear genome view, with its gene track.
  • Re-anchor on ⟨genome⟩ turns the track around so that genome is the anchor.
The lane header menu.
Open in JBrowse Web ↗

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 GCF_030704535.1, 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 “Grape vs peach, cacao, arabidopsis, poplar, tomato, citrus (MCScan blocks)”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr11:778,000-866,000.

Some settings have no written step yet — see the Spec tab.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "GCF_030704535.1",
      "loc": "chr11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "rows": {
            "sort": [
              "GCF_000346465.2",
              "GCF_000208745.1",
              "poplar"
            ]
          },
          "height": 260
        }
      ]
    }
  ]
}

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/grape_peach_cacao/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "GCF_030704535.1",
            "loc": "chr11:778,000-866,000",
            "tracks": [
                {
                    "trackId": "grape_peach_cacao_blocks",
                    "type": "MultiWaySyntenyDisplay",
                    "rows": {
                        "sort": [
                            "GCF_000346465.2",
                            "GCF_000208745.1",
                            "poplar"
                        ]
                    },
                    "height": 260
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

npx @jbrowse/img --config https://jbrowse.org/demos/grape_peach_cacao/config.json \
  --assembly GCF_030704535.1 --loc chr11:778,000-866,000 \
  --track grape_peach_cacao_blocks display:MultiWaySyntenyDisplay '{"rows":{"sort":["GCF_000346465.2","GCF_000208745.1","poplar"]},"height":260}' \
  --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": "GCF_030704535.1",
      "loc": "chr11:778,000-866,000",
      "tracks": [
        {
          "trackId": "grape_peach_cacao_blocks",
          "type": "MultiWaySyntenyDisplay",
          "rows": {
            "sort": [
              "GCF_000346465.2",
              "GCF_000208745.1",
              "poplar"
            ]
          },
          "height": 260
        }
      ]
    }
  ]
}
JSON

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

The figure's clicks open a lane's context menu; this command draws the view under it.

It leaves out 2 callouts anchored to what the clicks bring up.

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.

Opening a stacked synteny view

Two routes open a linear synteny view with a row per genome:

  • Launch → Linear synteny view (visible region) in the track menu offers a row to every genome that aligns to the window.
  • Launch → Linear synteny view appears once you drag-select a region on the scale bar. The dialog lists a row per genome, with arrows to reorder them.

See also