Synteny visualization (pairwise minimap2)

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.20. Desktop beta builds for Linux and macOS are on the releases page; the Windows build waits on code signing.

Two assemblies of one species share most of their sequence, and an alignment between them shows where the order breaks: an inversion, a moved block, a gene only one strain has. We align three Helicobacter pylori strains (26695, CHC155 and J99) with minimap2, one pair at a time, and the steps work the same on any pair of assemblies of your own. The other route to a stack of genomes aligns every genome against every other in one run, which Synteny visualization (all-vs-all minimap2) follows through five E. coli strains. We:

load the assemblies, and the minimap2 PAF as a synteny track
open the whole-genome alignment in a dotplot view
stack the strains in a linear synteny view, with a gene track on each row
color the gene tracks by gene symbol, so an ortholog is one color down the stack
index a large alignment as PIF

Prerequisites

a JBrowse instance (web or desktop quickstart); the steps are identical on both, and Desktop reads the alignments as local files
minimap2
python3, which the build script uses to copy the hub configs
node, for the JBrowse CLI

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

The data

Three H. pylori RefSeq assemblies and their genome hubs on genomes.jbrowse.org (26695, CHC155, J99). Each hub serves the sequence minimap2 aligns and a config holding the assembly and its NCBI RefSeq genes.

The tracks below read local files that the build script writes from these, so run it first, or run Aligning the assemblies on any pair of assemblies of your own. The script fetches everything itself.

What it is	File
26695 GCF_000307795.1 sequence	GCF_000307795.1.fa.gz
CHC155 GCF_025998455.1 sequence	GCF_025998455.1.fa.gz
J99 GCF_000982695.1 sequence	GCF_000982695.1.fa.gz

Aligning the assemblies

minimap2 takes the target genome first and the query second, and writes one PAF row per aligned block:

# -x asm20: the assembly preset for strains this diverged
# -c: emit the base-level CIGAR the linear synteny view draws from
# --eqx: split CIGAR matches (=) from mismatches (X)
minimap2 -c -x asm20 --eqx hpylori_j99.fa.gz hpylori_26695.fa.gz > 26695_vs_j99.paf

Color by value → Identity reads the PAF's divergence tag or match counts.

JBrowse also loads MUMmer .delta and UCSC .chain files directly. To convert them to PAF instead, paftools.js delta2paf reads a .delta, and chain2paf reads a .chain.

Loading the assemblies and the alignment

We'll load each strain's assembly from its hub. Each strain's hub config.json holds a whole JBrowse assembly: the 2bit sequence, an alias table and the NCBI RefSeq gene track. The build adds the old short name as an alias, so a session can still say hpylori_26695:

{
  "name": "GCF_000307795.1",
  "displayName": "H. pylori 26695",
  "aliases": ["hpylori_26695"],
  "sequence": {
    "type": "ReferenceSequenceTrack",
    "trackId": "GCF_000307795.1-ReferenceSequenceTrack",
    "adapter": {
      "type": "TwoBitAdapter",
      "uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1.2bit",
      "chromSizes": "https://hgdownload.soe.ucsc.edu/hubs/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1.chrom.sizes.txt"
    }
  },
  "refNameAliases": {
    "adapter": {
      "type": "RefNameAliasAdapter",
      "refNameColumnHeaderName": "ucsc",
      "uri": "https://hgdownload.soe.ucsc.edu/hubs/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1.chromAlias.txt"
    }
  }
}

refNameColumnHeaderName makes the UCSC name canonical, so the views read NC_018939v1 where the FASTA and the PAF say NC_018939.1; the alias table maps one to the other. CHC155 (GCF_025998455.1) and J99 (GCF_000982695.1) load the same way from their hubs.

For your own genomes, the FASTA is the assembly. The .fai and .gzi sit beside a bgzipped FASTA, and its sequence names are the ones your PAF uses, so no alias table is needed:

Config file

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

{
  "name": "strainA",
  "uri": "strainA.fa.gz"
}

CLI (add-assembly)

jbrowse add-assembly strainA.fa.gz \
  --name strainA \
  --load copy

JBrowse Desktop

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:

strainA.fa.gz
strainA.fa.gz.fai
strainA.fa.gz.gzi

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

Genome name: strainA

strainA.fa.gz is relative to a config.json. Replace it with its URL or its path on this computer.

The alignment then goes on under the assembly names. assemblyNames runs query,target, the reverse of the minimap2 argument order: minimap2 target.fa query.fa becomes ["query", "target"]. A PAF that is not indexed needs only its uri; swap in your own file.

Config file

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

{
  "type": "SyntenyTrack",
  "trackId": "26695_vs_j99",
  "name": "26695 vs J99",
  "assemblyNames": ["GCF_000307795.1", "GCF_000982695.1"],
  "adapter": {
    "type": "PAFAdapter",
    "uri": "26695_vs_j99.paf"
  }
}

CLI (add-track)

jbrowse add-track 26695_vs_j99.paf \
  --trackId 26695_vs_j99 \
  --name "26695 vs J99" \
  --assemblyNames GCF_000307795.1,GCF_000982695.1 \
  --load copy

In the app

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": "26695_vs_j99",
  "name": "26695 vs J99",
  "assemblyNames": ["GCF_000307795.1", "GCF_000982695.1"],
  "adapter": {
    "type": "PAFAdapter",
    "uri": "26695_vs_j99.paf"
  }
}

26695_vs_j99.paf is relative to a config.json. Replace it 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.

A track whose assemblyNames are in the wrong order draws an empty band and shows a warning in the view header:

A synteny track whose assemblyNames are reversed draws an empty band, and the warning icon in its header opens a dialog reporting the reversal.

Reading the whole genome in a dotplot

Add → Dotplot view opens the import form in Quick start: pick the track just added and click Launch. Swap transposes the axes. Manual picks each axis and a synteny file by hand.

26695 (x) against J99 (y). The backbone runs anti-diagonal.

To open any of those pieces at base resolution, drag a box across it, then right-click inside the box and choose Linear synteny view.

Stacking the strains

A synteny band joins matching regions of two adjacent rows only, so a 26695 / CHC155 / J99 stack needs the two adjacent alignments:

minimap2 -c -x asm20 --eqx hpylori_chc155.fa.gz hpylori_26695.fa.gz > 26695_vs_chc155.paf
minimap2 -c -x asm20 --eqx hpylori_j99.fa.gz hpylori_chc155.fa.gz > chc155_vs_j99.paf

With one file per pair, the pairs you aligned fix the row order. A single all-vs-all PAF lets every band read the same file in any row order, after renaming each genome's sequences to PanSN names (Synteny visualization (all-vs-all minimap2)).

Take the third assembly from its hub and add both alignments the same way as above, then:

Add → Linear synteny view, then switch to Manual.
Pick an assembly per row, with Add row for the third.
Click the arrow between each adjacent pair to choose that band's synteny track: 26695 against CHC155, then CHC155 against J99.
Click Launch, and all the strains stack in one view.

Zoom each row in once with its magnifier, then open each strain's gene track, NCBI RefSeq - RefSeq All (GFF), from the track selector for that row.

J99 has a short inversion that 26695 and CHC155 lack. To frame it, type one window into each row's search box, top to bottom; [rev] flips the 26695 row, which runs opposite to the other two strains here:

NC_018939v1:1,489,400-1,509,400[rev]
NZ_AP026446v1:99,000-119,000
NZ_CP011330v1:1,238,100-1,258,100

The four steps above and the gene tracks after them: Manual, a genome per row with Add row for the third, each connector showing the alignment it resolved for that pair, Launch, a zoom in on each row, and each strain's gene track from the track selector for that row.

Video

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

Choose Manual, then set a genome for each row
Add a third row for the third strain
Each arrow between rows has already found its alignment
It opens empty; add each strain's genes from its own row
Three strains stacked with their genes, alignments drawn between

Steps

Open this view in JBrowse Web ↗ ·

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.

https://jbrowse.org/code/jb2/main/?config=https%3A%2F%2Fjbrowse.org%2Fdemos%2Fhpylori%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%7D%2C%7B%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+synteny%2Fthree_strain_import

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

From scratch:

Open the view: Add → Linear synteny view, and choose the rows in the import form.

Agent

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

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/hpylori/config.json

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": "LinearSyntenyView",
      "views": [
        {},
        {}
      ]
    }
  ]
}

Redraw the figure headlessly

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {},
        {}
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hpylori/config.json \
  --width 1920 --height 960 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Notebook

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

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hpylori/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {},
                {}
            ]
        }
    ],
)
app  # display the widget

Image

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {},
        {}
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/hpylori/config.json \
  --spec session.json \
  --width 1920 --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.

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {},
        {}
      ]
    }
  ]
}

Three H. pylori strains stacked with a gene track on each. The ribbons into J99 cross over its inverted block.

Coloring genes by ortholog

NCBI reuses standardized gene symbols across bacterial strains, so the gene attribute works as an ortholog id. In grammar-of-graphics terms, a track's encoding.color is a color scale, a field mapped to colors. On each gene track's menu:

pick Color by → Attribute... and enter gene as the field
open Advanced → Edit plot... to see the setting as text, where an edit applies live

An ortholog is then one color down all the rows, and a gene with no gene value (most genes here have only a locus tag) stays grey. Inside the inversion, rsmA and rlmN trade places in J99.

Left, the Color by attribute dialog on the first gene track. Right, the strains after applying it, a shared symbol one color down all of them.

The config below is the same setting on the hub's gene track:

Config file

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

{
  "type": "FeatureTrack",
  "trackId": "GCF_000307795.1-ncbiGff",
  "name": "NCBI RefSeq - RefSeq All (GFF)",
  "assemblyNames": ["GCF_000307795.1"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/hubs/genark/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1_ASM30779v1_genomic.gff.gz",
    "index": {
      "location": {
        "uri": "https://jbrowse.org/hubs/genark/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1_ASM30779v1_genomic.gff.gz.csi"
      },
      "indexType": "CSI"
    }
  },
  "displayDefaults": {
    "filter": ["geneLike"],
    "encoding": { "color": "gene" }
  }
}

CLI (add-track-json)

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "GCF_000307795.1-ncbiGff",
  "name": "NCBI RefSeq - RefSeq All (GFF)",
  "assemblyNames": ["GCF_000307795.1"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/hubs/genark/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1_ASM30779v1_genomic.gff.gz",
    "index": {
      "location": {
        "uri": "https://jbrowse.org/hubs/genark/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1_ASM30779v1_genomic.gff.gz.csi"
      },
      "indexType": "CSI"
    }
  },
  "displayDefaults": {
    "filter": ["geneLike"],
    "encoding": { "color": "gene" }
  }
}'

In the app

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": "FeatureTrack",
  "trackId": "GCF_000307795.1-ncbiGff",
  "name": "NCBI RefSeq - RefSeq All (GFF)",
  "assemblyNames": ["GCF_000307795.1"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/hubs/genark/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1_ASM30779v1_genomic.gff.gz",
    "index": {
      "location": {
        "uri": "https://jbrowse.org/hubs/genark/GCF/000/307/795/GCF_000307795.1/GCF_000307795.1_ASM30779v1_genomic.gff.gz.csi"
      },
      "indexType": "CSI"
    }
  },
  "displayDefaults": {
    "filter": ["geneLike"],
    "encoding": { "color": "gene" }
  }
}

Indexing large alignments as PIF

A bacterial PAF is small enough to load whole. For a large whole-genome alignment, convert the PAF to PIF (Pairwise Indexed Format) so JBrowse fetches only the alignments in the current viewport:

jbrowse make-pif alignment.paf
jbrowse add-track alignment.pif.gz -a query,target --load copy

Reproduce it end to end

One script builds everything above, build_hpylori_synteny.sh, in three steps:

Download each strain's sequence and config from its genome hub, so the alignments and the assemblies come from the same files.
Align 26695 to CHC155, CHC155 to J99 and 26695 to J99 with minimap2 -x asm20 --eqx.
Write the config with the hub assemblies and gene tracks, the pairwise synteny tracks, and a default session stacking all the strains.

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_hpylori_synteny.sh
bash build_hpylori_synteny.sh          # builds ./hpylori_synteny_build/jbrowse2
npx --yes serve hpylori_synteny_build/jbrowse2 # then open the printed URL

Citations

Diesh et al. (2024). Setting Up the JBrowse 2 Genome Browser
Diesh et al. (2023). JBrowse 2: A Modular Genome Browser with Views of Synteny and Structural Variation

Feedback on this tutorial is welcome: contact us.

Synteny visualization (pairwise minimap2)

Prerequisites#

The data#

Aligning the assemblies#

Loading the assemblies and the alignment#

Reading the whole genome in a dotplot#

Stacking the strains#

Coloring genes by ortholog#

Indexing large alignments as PIF#

Reproduce it end to end#

See also#

Citations#

Prerequisites

The data

Aligning the assemblies

Loading the assemblies and the alignment

Reading the whole genome in a dotplot

Stacking the strains

Coloring genes by ortholog

Indexing large alignments as PIF

Reproduce it end to end

See also

Citations