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

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

Aligning the assemblies

minimap2 -c -x asm20 --eqx hpylori_j99.fa hpylori_26695.fa > 26695_vs_j99.paf

The flags each do one thing:

  • -x asm20 is the whole-genome assembly preset, sized to how divergent the two genomes are. asm5 covers up to about 5% divergence; these H. pylori strains are the same species but diverge well past that, so they need asm20.
  • -c emits the base-level CIGAR the linear synteny view draws from.
  • --eqx splits CIGAR matches (=) from mismatches (X). The ribbon band treats both as matches, and the same track opened in a plain linear genome view draws the X operations as per-base mismatches, the way a read pileup does. Color by → Identity reads the PAF's own divergence tag, or its 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 have to be assemblies before the alignment can reference 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, which is the reverse of the minimap2 argument order: minimap2 target.fa query.fa becomes add-track -a query,target. Here 26695 was the query and J99 the target, so 26695 comes first.

Reading the whole genome in a dotplot

Add → Dotplot view opens the import form. The track just added is in the config, so the form opens in Quick start: pick it and click Launch. Swap transposes the axes, since a synteny track is queryable in either direction. Manual is where you pick 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; conserved genes then line up down the stack ribbon by ribbon.

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, so search boxes, zooming, and the track selector work per genome. See Linear synteny view for ribbon coloring, curved ribbons, and the rest of the view's options, and URL parameters → linear synteny view for building one from a session-spec URL.

Coloring genes by ortholog

The ribbons connect aligned sequence, and the gene tracks color independently. In bacteria the gene symbol is effectively the ortholog id, since NCBI reuses standardized symbols across strains. On each gene track, open the track menu and pick Color by... → Attribute..., then enter gene. The dialog prints the expression it is about to write, and every distinct value of that attribute gets its own deterministic color, so an ortholog carries one color down all three panels.

Features with no value for that attribute are painted a neutral grey; most of the genes in this window 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'))\"}"

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, and JBrowse checks for it once at view load: it asks the adapter which chromosomes belong to the top row and compares them against that assembly's own. When they belong to the other row instead, a warning appears in the view header, and the dialog behind it names the remedy.

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 draws but scatters its blocks randomly comes from the alignment: a preset too tight for the divergence leaves only short spurious anchors. Raise it, asm5 up to about 5% and asm10/asm20 past that, 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 RefSeq assemblies, aligns all three strain pairs with minimap2, downloads JBrowse, and writes a config.json with the three assemblies, a gene track per strain, the three pairwise synteny tracks, and a default session that stacks all three in one linear synteny view. It needs the same tools listed under Prerequisites.

See also

References