Skip to main content

Synteny visualization (pairwise minimap2)

TL;DR: align two assemblies with minimap2 -c --eqx, load the PAF as a synteny track, and read it whole-genome in a dotplot and base-level in the linear synteny view. add-track -a takes query,target, the reverse of the minimap2 argument order.

Prerequisites

  • a JBrowse 2 instance (see the web quickstart, or the desktop quickstart; the steps below are identical on both, and on Desktop the FASTAs and alignments are local files)
  • minimap2
  • samtools
  • htslib (bgzip, tabix)
  • unzip
  • the NCBI datasets CLI, which fetches the three assemblies and their gene annotations
  • node, for the JBrowse CLI

On Debian/Ubuntu, apt install minimap2 samtools tabix unzip covers most of these. The NCBI datasets CLI is a single-binary download, and node comes from nodejs.org.

Where the data comes from

Three H. pylori RefSeq assemblies, each fetched by accession with the datasets CLI.

Three strains, stacked

Three Helicobacter pylori strains (26695, CHC155, and J99) go from raw assemblies to a stacked three-genome synteny view. The steps work the same on any pair of assemblies.

Aligning the assemblies

minimap2 -c -x asm20 --eqx hpylori_j99.fa hpylori_26695.fa > 26695_vs_j99.paf
  • -x asm20 is the assembly preset for the divergence between the genomes. asm5 covers up to about 5%; these strains diverge well past that.
  • -c emits the base-level CIGAR the linear synteny view draws from.
  • --eqx splits CIGAR matches (=) from mismatches (X), so the same track opened in a plain linear genome view draws per-base mismatches. Color by → Identity reads the PAF's divergence tag or match counts.

JBrowse also loads MUMmer .delta and UCSC .chain files directly, and paftools.js has delta2paf and chain2paf for converting them.

Loading the assemblies and the alignment

Both genomes are added as assemblies before the alignment that references them:

jbrowse add-assembly hpylori_26695.fa --load copy
jbrowse add-assembly hpylori_j99.fa --load copy
jbrowse add-track 26695_vs_j99.paf -a hpylori_26695,hpylori_j99 --load copy

The -a order is query,target, the reverse of the minimap2 argument order: minimap2 target.fa query.fa becomes add-track -a query,target.

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.

The dotplot import form in Manual mode, where you pick the X-axis and Y-axis assembly by hand, then optionally add a synteny file (.paf, .out, .delta, .chain, .anchors, or .anchors.simple). Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open the view: Add → Dotplot view, and choose both axes in the import form.

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%2Fhpylori%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22views%22%3A%5B%7B%7D%2C%7B%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_synteny%2Fdotplot_import

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

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

Loaded against config: https://jbrowse.org/demos/hpylori/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": "DotplotView",
      "views": [
        {},
        {}
      ]
    }
  ]
}
JSON

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

The 26695 vs J99 alignment, 26695 on the X-axis and J99 on the Y-axis. The backbone runs anti-diagonal because the two assemblies were deposited in opposite orientations, and the pieces sitting off it are the rearrangements between the strains. Open this view in JBrowse ↗

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 has hpylori_26695 on X and hpylori_j99 on Y.
  2. Open the view: Add → Dotplot view, and set both axes to those assemblies in the import form.
  3. Point the import form at your own file: use the track panel under the two axis selectors, 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 both axes itself.This figure uses the “26695_vs_j99.pif” track.
  4. Click Launch.

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%2Fhpylori%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22tracks%22%3A%5B%2226695_vs_j99.pif%22%5D%2C%22views%22%3A%5B%7B%22assembly%22%3A%22hpylori_26695%22%7D%2C%7B%22assembly%22%3A%22hpylori_j99%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_synteny%2Fdotplot

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

{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "26695_vs_j99.pif"
      ],
      "views": [
        {
          "assembly": "hpylori_26695"
        },
        {
          "assembly": "hpylori_j99"
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/hpylori/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": "DotplotView",
      "tracks": [
        "26695_vs_j99.pif"
      ],
      "views": [
        {
          "assembly": "hpylori_26695"
        },
        {
          "assembly": "hpylori_j99"
        }
      ]
    }
  ]
}
JSON

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

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 three strains

A band is drawn between adjacent rows only, so a 26695 / CHC155 / J99 stack needs the two adjacent alignments:

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

Add the third assembly and both alignments the same way as above, then:

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

Open each strain's gene track from its own track selector.

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, and each strain's gene track from that row's own track selector. Open the session this video starts in ↗
Three H. pylori strains stacked with a gene track on each genome. Ribbons connect aligned blocks between adjacent genomes, and genes such as fliR, cbf2, efp, and lysS line up across all three strains. Open this view in JBrowse ↗

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: hpylori_26695, hpylori_chc155, hpylori_j99.
  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 “26695_vs_chc155.pif” track.
  4. 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.This figure uses the “chc155_vs_j99.pif” track.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 1 (hpylori_26695) — This figure uses the “hpylori_26695.gff” track.
  8. Track menu → Show only genes (checked)Row 1 (hpylori_26695).
  9. Type your region of interest into the location box and press Enter.Row 1 (hpylori_26695) — This figure is at NC_018939.1:177696-190329.
  10. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 2 (hpylori_chc155) — This figure uses the “hpylori_chc155.gff” track.
  11. Track menu → Show only genes (checked)Row 2 (hpylori_chc155).
  12. Type your region of interest into the location box and press Enter.Row 2 (hpylori_chc155) — This figure is at NZ_AP026446.1:287157-299790.
  13. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 3 (hpylori_j99) — This figure uses the “hpylori_j99.gff” track.
  14. Track menu → Show only genes (checked)Row 3 (hpylori_j99).
  15. Type your region of interest into the location box and press Enter.Row 3 (hpylori_j99) — This figure is at NZ_CP011330.1:872350-884982[rev].

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%2Fhpylori%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22drawCurves%22%3Atrue%2C%22tracks%22%3A%5B%5B%2226695_vs_chc155.pif%22%5D%2C%5B%22chc155_vs_j99.pif%22%5D%5D%2C%22views%22%3A%5B%7B%22loc%22%3A%22NC_018939.1%3A177696-190329%22%2C%22assembly%22%3A%22hpylori_26695%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_26695.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%2C%7B%22loc%22%3A%22NZ_AP026446.1%3A287157-299790%22%2C%22assembly%22%3A%22hpylori_chc155%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_chc155.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%2C%7B%22loc%22%3A%22NZ_CP011330.1%3A872350-884982%5Brev%5D%22%2C%22assembly%22%3A%22hpylori_j99%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_j99.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_synteny%2Flinear_synteny_genes

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939.1:177696-190329",
          "assembly": "hpylori_26695",
          "tracks": [
            {
              "trackId": "hpylori_26695.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_AP026446.1:287157-299790",
          "assembly": "hpylori_chc155",
          "tracks": [
            {
              "trackId": "hpylori_chc155.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_CP011330.1:872350-884982[rev]",
          "assembly": "hpylori_j99",
          "tracks": [
            {
              "trackId": "hpylori_j99.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/hpylori/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",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939.1:177696-190329",
          "assembly": "hpylori_26695",
          "tracks": [
            {
              "trackId": "hpylori_26695.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_AP026446.1:287157-299790",
          "assembly": "hpylori_chc155",
          "tracks": [
            {
              "trackId": "hpylori_chc155.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_CP011330.1:872350-884982[rev]",
          "assembly": "hpylori_j99",
          "tracks": [
            {
              "trackId": "hpylori_j99.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        }
      ]
    }
  ]
}
JSON

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

Each panel is a full linear genome view with its own search box, zoom and track selector. See Linear synteny view for ribbon options and URL parameters → linear synteny view for building one from a URL.

Coloring genes by ortholog

In bacteria the gene symbol is effectively the ortholog id, since NCBI reuses standardized symbols across strains. On each gene track, pick Color by... → Attribute... from the track menu and enter gene. Every distinct value gets its own deterministic color, so an ortholog carries one color down all three panels. Features with no value are grey; most genes here carry only a locus tag.

The click and its result. Left, the Color by attribute dialog on the first strain's gene track with the attribute name set to gene. Right, the same three strains after applying it: a shared symbol holds one color down all three panels. Open in JBrowse: Dialog ↗ · Result ↗

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: hpylori_26695, hpylori_chc155, hpylori_j99.
  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 “26695_vs_chc155.pif” track.
  4. 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.This figure uses the “chc155_vs_j99.pif” track.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 1 (hpylori_26695) — This figure uses the “hpylori_26695.gff” track.
  8. Track menu → Show only genes (checked)Row 1 (hpylori_26695).
  9. Type your region of interest into the location box and press Enter.Row 1 (hpylori_26695) — This figure is at NC_018939.1:177696-190329.
  10. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 2 (hpylori_chc155) — This figure uses the “hpylori_chc155.gff” track.
  11. Track menu → Show only genes (checked)Row 2 (hpylori_chc155).
  12. Type your region of interest into the location box and press Enter.Row 2 (hpylori_chc155) — This figure is at NZ_AP026446.1:287157-299790.
  13. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 3 (hpylori_j99) — This figure uses the “hpylori_j99.gff” track.
  14. Track menu → Show only genes (checked)Row 3 (hpylori_j99).
  15. Type your region of interest into the location box and press Enter.Row 3 (hpylori_j99) — This figure is at NZ_CP011330.1:872350-884982[rev].

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%2Fhpylori%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22drawCurves%22%3Atrue%2C%22tracks%22%3A%5B%5B%2226695_vs_chc155.pif%22%5D%2C%5B%22chc155_vs_j99.pif%22%5D%5D%2C%22views%22%3A%5B%7B%22loc%22%3A%22NC_018939.1%3A177696-190329%22%2C%22assembly%22%3A%22hpylori_26695%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_26695.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%2C%7B%22loc%22%3A%22NZ_AP026446.1%3A287157-299790%22%2C%22assembly%22%3A%22hpylori_chc155%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_chc155.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%2C%7B%22loc%22%3A%22NZ_CP011330.1%3A872350-884982%5Brev%5D%22%2C%22assembly%22%3A%22hpylori_j99%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_j99.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%7D%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_synteny%2Fcolor_by_attribute

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939.1:177696-190329",
          "assembly": "hpylori_26695",
          "tracks": [
            {
              "trackId": "hpylori_26695.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_AP026446.1:287157-299790",
          "assembly": "hpylori_chc155",
          "tracks": [
            {
              "trackId": "hpylori_chc155.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_CP011330.1:872350-884982[rev]",
          "assembly": "hpylori_j99",
          "tracks": [
            {
              "trackId": "hpylori_j99.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/hpylori/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",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939.1:177696-190329",
          "assembly": "hpylori_26695",
          "tracks": [
            {
              "trackId": "hpylori_26695.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_AP026446.1:287157-299790",
          "assembly": "hpylori_chc155",
          "tracks": [
            {
              "trackId": "hpylori_chc155.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        },
        {
          "loc": "NZ_CP011330.1:872350-884982[rev]",
          "assembly": "hpylori_j99",
          "tracks": [
            {
              "trackId": "hpylori_j99.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true
            }
          ]
        }
      ]
    }
  ]
}
JSON

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

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: hpylori_26695, hpylori_chc155, hpylori_j99.
  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 “26695_vs_chc155.pif” track.
  4. 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.This figure uses the “chc155_vs_j99.pif” track.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 1 (hpylori_26695) — This figure uses the “hpylori_26695.gff” track.
  8. Track menu → Show only genes (checked)Row 1 (hpylori_26695).
  9. Track menu → Color by... → Attribute... → geneRow 1 (hpylori_26695).
  10. Type your region of interest into the location box and press Enter.Row 1 (hpylori_26695) — This figure is at NC_018939.1:177696-190329.
  11. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 2 (hpylori_chc155) — This figure uses the “hpylori_chc155.gff” track.
  12. Track menu → Show only genes (checked)Row 2 (hpylori_chc155).
  13. Track menu → Color by... → Attribute... → geneRow 2 (hpylori_chc155).
  14. Type your region of interest into the location box and press Enter.Row 2 (hpylori_chc155) — This figure is at NZ_AP026446.1:287157-299790.
  15. Add your own track: open this view's track selector, click + and choose Add track, then paste a URL or choose a local file.Row 3 (hpylori_j99) — This figure uses the “hpylori_j99.gff” track.
  16. Track menu → Show only genes (checked)Row 3 (hpylori_j99).
  17. Track menu → Color by... → Attribute... → geneRow 3 (hpylori_j99).
  18. Type your region of interest into the location box and press Enter.Row 3 (hpylori_j99) — This figure is at NZ_CP011330.1:872350-884982[rev].

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%2Fhpylori%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22drawCurves%22%3Atrue%2C%22tracks%22%3A%5B%5B%2226695_vs_chc155.pif%22%5D%2C%5B%22chc155_vs_j99.pif%22%5D%5D%2C%22views%22%3A%5B%7B%22loc%22%3A%22NC_018939.1%3A177696-190329%22%2C%22assembly%22%3A%22hpylori_26695%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_26695.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22color%22%3A%22jexl%3ArandomColor%28get%28feature%2C%27gene%27%29%29%22%7D%5D%7D%2C%7B%22loc%22%3A%22NZ_AP026446.1%3A287157-299790%22%2C%22assembly%22%3A%22hpylori_chc155%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_chc155.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22color%22%3A%22jexl%3ArandomColor%28get%28feature%2C%27gene%27%29%29%22%7D%5D%7D%2C%7B%22loc%22%3A%22NZ_CP011330.1%3A872350-884982%5Brev%5D%22%2C%22assembly%22%3A%22hpylori_j99%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hpylori_j99.gff%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22color%22%3A%22jexl%3ArandomColor%28get%28feature%2C%27gene%27%29%29%22%7D%5D%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_synteny%2Fortholog_colors

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939.1:177696-190329",
          "assembly": "hpylori_26695",
          "tracks": [
            {
              "trackId": "hpylori_26695.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "color": "jexl:randomColor(get(feature,'gene'))"
            }
          ]
        },
        {
          "loc": "NZ_AP026446.1:287157-299790",
          "assembly": "hpylori_chc155",
          "tracks": [
            {
              "trackId": "hpylori_chc155.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "color": "jexl:randomColor(get(feature,'gene'))"
            }
          ]
        },
        {
          "loc": "NZ_CP011330.1:872350-884982[rev]",
          "assembly": "hpylori_j99",
          "tracks": [
            {
              "trackId": "hpylori_j99.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "color": "jexl:randomColor(get(feature,'gene'))"
            }
          ]
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/hpylori/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",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939.1:177696-190329",
          "assembly": "hpylori_26695",
          "tracks": [
            {
              "trackId": "hpylori_26695.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "color": "jexl:randomColor(get(feature,'gene'))"
            }
          ]
        },
        {
          "loc": "NZ_AP026446.1:287157-299790",
          "assembly": "hpylori_chc155",
          "tracks": [
            {
              "trackId": "hpylori_chc155.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "color": "jexl:randomColor(get(feature,'gene'))"
            }
          ]
        },
        {
          "loc": "NZ_CP011330.1:872350-884982[rev]",
          "assembly": "hpylori_j99",
          "tracks": [
            {
              "trackId": "hpylori_j99.gff",
              "type": "LinearBasicDisplay",
              "showOnlyGenes": true,
              "color": "jexl:randomColor(get(feature,'gene'))"
            }
          ]
        }
      ]
    }
  ]
}
JSON

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

The dialog writes a display color expression, which is one line of config:

{
  "type": "FeatureTrack",
  "trackId": "hpylori_26695.gff",
  "name": "H. pylori 26695 genes",
  "assemblyNames": ["hpylori_26695"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/demos/hpylori/hpylori_26695.gff.gz"
  },
  "displayDefaults": {
    "showOnlyGenes": true,
    "color": "jexl:randomColor(get(feature,'gene'))"
  }
}
jbrowse add-track https://jbrowse.org/demos/hpylori/hpylori_26695.gff.gz \
  --trackId hpylori_26695.gff \
  --name "H. pylori 26695 genes" \
  --assemblyNames hpylori_26695 \
  --displayDefaults "{\"showOnlyGenes\":true,\"color\":\"jexl:randomColor(get(feature,'gene'))\"}"

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": "hpylori_26695.gff",
  "name": "H. pylori 26695 genes",
  "assemblyNames": ["hpylori_26695"],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "https://jbrowse.org/demos/hpylori/hpylori_26695.gff.gz"
  },
  "displayDefaults": {
    "showOnlyGenes": true,
    "color": "jexl:randomColor(get(feature,'gene'))"
  }
}

Using PIF for large genomes

A bacterial PAF is small enough to load whole. For a large whole-genome alignment, convert it 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

Troubleshooting

assemblyNames in the wrong order is the common one. JBrowse checks at view load whether the top row's chromosome names belong to that assembly, and a warning in the view header names the remedy when they belong to the other row.

A synteny track whose assemblyNames are reversed. No chromosome name resolves, so the band is empty, and the header warning reports the reversal. 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: hpylori_26695, hpylori_chc155.
  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. This one needs a bgzip-indexed PAF (.pif.gz + .tbi).A synteny track the session already has is quicker: pick it under **Quick start**, which fills in the rows itself.This figure uses “26695 vs CHC155 (assemblyNames reversed)”.
  4. Click Launch.
  5. Launch synteny view dialog → Collapse panels to rulers (checked)Checked by default. A row the launch gave no tracks opens as its ruler alone instead of a "No tracks active" block; any row expands again from its own controls afterwards.
  6. Drag the bar below a synteny level to resize it.This figure's level is 200px tall.
  7. Type your region of interest into the location box and press Enter.Row 1 (hpylori_26695) — This figure is at NC_018939.1.
  8. Type your region of interest into the location box and press Enter.Row 2 (hpylori_chc155) — This figure is at NZ_AP026446.1.

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%2Fhpylori%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22SyntenyTrack%22%2C%22trackId%22%3A%22hpylori_reversed_assembly_names%22%2C%22name%22%3A%2226695+vs+CHC155+%28assemblyNames+reversed%29%22%2C%22assemblyNames%22%3A%5B%22hpylori_26695%22%2C%22hpylori_chc155%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22PairwiseIndexedPAFAdapter%22%2C%22assemblyNames%22%3A%5B%22hpylori_26695%22%2C%22hpylori_chc155%22%5D%2C%22pifGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fhpylori%2F26695_vs_chc155.pif.gz%22%2C%22locationType%22%3A%22UriLocation%22%7D%2C%22index%22%3A%7B%22indexType%22%3A%22TBI%22%2C%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fhpylori%2F26695_vs_chc155.pif.gz.tbi%22%2C%22locationType%22%3A%22UriLocation%22%7D%7D%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22tracks%22%3A%5B%5B%22hpylori_reversed_assembly_names%22%5D%5D%2C%22collapseEmptyRows%22%3Atrue%2C%22levelHeights%22%3A%5B200%5D%2C%22views%22%3A%5B%7B%22assembly%22%3A%22hpylori_26695%22%2C%22loc%22%3A%22NC_018939.1%22%7D%2C%7B%22assembly%22%3A%22hpylori_chc155%22%2C%22loc%22%3A%22NZ_AP026446.1%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+sv_synteny%2Fassembly_order_warning

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track-json '{
  "type": "SyntenyTrack",
  "trackId": "hpylori_reversed_assembly_names",
  "name": "26695 vs CHC155 (assemblyNames reversed)",
  "assemblyNames": [
    "hpylori_26695",
    "hpylori_chc155"
  ],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "assemblyNames": [
      "hpylori_26695",
      "hpylori_chc155"
    ],
    "pifGzLocation": {
      "uri": "https://jbrowse.org/demos/hpylori/26695_vs_chc155.pif.gz",
      "locationType": "UriLocation"
    },
    "index": {
      "indexType": "TBI",
      "location": {
        "uri": "https://jbrowse.org/demos/hpylori/26695_vs_chc155.pif.gz.tbi",
        "locationType": "UriLocation"
      }
    }
  }
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hpylori_26695, hpylori_chc155 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Session spec tab, or jbrowse set-default-session.

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

{
  "sessionTracks": [
    {
      "type": "SyntenyTrack",
      "trackId": "hpylori_reversed_assembly_names",
      "name": "26695 vs CHC155 (assemblyNames reversed)",
      "assemblyNames": [
        "hpylori_26695",
        "hpylori_chc155"
      ],
      "adapter": {
        "type": "PairwiseIndexedPAFAdapter",
        "assemblyNames": [
          "hpylori_26695",
          "hpylori_chc155"
        ],
        "pifGzLocation": {
          "uri": "https://jbrowse.org/demos/hpylori/26695_vs_chc155.pif.gz",
          "locationType": "UriLocation"
        },
        "index": {
          "indexType": "TBI",
          "location": {
            "uri": "https://jbrowse.org/demos/hpylori/26695_vs_chc155.pif.gz.tbi",
            "locationType": "UriLocation"
          }
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": [
        [
          "hpylori_reversed_assembly_names"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        200
      ],
      "views": [
        {
          "assembly": "hpylori_26695",
          "loc": "NC_018939.1"
        },
        {
          "assembly": "hpylori_chc155",
          "loc": "NZ_AP026446.1"
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/demos/hpylori/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'
{
  "sessionTracks": [
    {
      "type": "SyntenyTrack",
      "trackId": "hpylori_reversed_assembly_names",
      "name": "26695 vs CHC155 (assemblyNames reversed)",
      "assemblyNames": [
        "hpylori_26695",
        "hpylori_chc155"
      ],
      "adapter": {
        "type": "PairwiseIndexedPAFAdapter",
        "assemblyNames": [
          "hpylori_26695",
          "hpylori_chc155"
        ],
        "pifGzLocation": {
          "uri": "https://jbrowse.org/demos/hpylori/26695_vs_chc155.pif.gz",
          "locationType": "UriLocation"
        },
        "index": {
          "indexType": "TBI",
          "location": {
            "uri": "https://jbrowse.org/demos/hpylori/26695_vs_chc155.pif.gz.tbi",
            "locationType": "UriLocation"
          }
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": [
        [
          "hpylori_reversed_assembly_names"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        200
      ],
      "views": [
        {
          "assembly": "hpylori_26695",
          "loc": "NC_018939.1"
        },
        {
          "assembly": "hpylori_chc155",
          "loc": "NZ_AP026446.1"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hpylori/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 view that scatters its blocks randomly comes from a preset too tight for the divergence, which leaves only short spurious anchors. Raise it, and check -c --eqx were passed.

Reproduce it end to end

One script builds everything above, build_hpylori_synteny.sh:

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

It downloads the three assemblies, aligns the strain pairs, and writes a config.json with a gene track per strain, the pairwise synteny tracks, and a default session stacking all three. It needs the tools under Prerequisites.

See also

References