Skip to main content

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.15. Desktop beta builds are coming soon.

We compare three Helicobacter pylori strains (26695, CHC155 and J99) by aligning their assemblies with minimap2. The steps work the same on any pair of assemblies. We:

  • align each pair of genomes and load the assemblies and the PAF
  • open the whole-genome alignment in a dotplot
  • stack the strains in a linear synteny view, and color genes by ortholog
  • index a large alignment as PIF

Aligning each pair of genomes separately is one of two routes to a stacked view. The other aligns every genome against every other in one minimap2 run, and Synteny visualization (all-vs-all minimap2) follows it through five E. coli strains.

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

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 isFile
26695 GCF_000307795.1 sequenceGCF_000307795.1.fa.gz
CHC155 GCF_025998455.1 sequenceGCF_025998455.1.fa.gz
J99 GCF_000982695.1 sequenceGCF_000982695.1.fa.gz

Aligning the assemblies

minimap2 -c -x asm20 --eqx hpylori_j99.fa.gz hpylori_26695.fa.gz > 26695_vs_j99.paf
  • -x asm20 is the assembly preset for strains this diverged.
  • -c emits the base-level CIGAR the linear synteny view draws from.
  • --eqx splits CIGAR matches (=) from mismatches (X). Color by value → 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

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:

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

{
  "name": "strainA",
  "uri": "strainA.fa.gz"
}
jbrowse add-assembly strainA.fa.gz \
  --name strainA \
  --load copy

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.

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"
  }
}
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 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.
Open in JBrowse Web ↗

This session loads a large dataset and takes a while to open.

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your 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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_000307795.1, GCF_025998455.1.
  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. Drag the bar below a synteny level to resize it.This figure's level is 200px tall.
  6. Row 1 (GCF_000307795.1)
    1. Type your region of interest into the location box and press Enter.This figure is at NC_018939v1.
  7. Row 2 (GCF_025998455.1)
    1. Type your region of interest into the location box and press Enter.This figure is at NZ_AP026446v1.

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": [
    "GCF_000307795.1",
    "GCF_025998455.1"
  ],
  "adapter": {
    "type": "PairwiseIndexedPAFAdapter",
    "assemblyNames": [
      "GCF_000307795.1",
      "GCF_025998455.1"
    ],
    "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 GCF_000307795.1, GCF_025998455.1 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 Spec tab, or jbrowse set-default-session.

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

{
  "sessionTracks": [
    {
      "type": "SyntenyTrack",
      "trackId": "hpylori_reversed_assembly_names",
      "name": "26695 vs CHC155 (assemblyNames reversed)",
      "assemblyNames": [
        "GCF_000307795.1",
        "GCF_025998455.1"
      ],
      "adapter": {
        "type": "PairwiseIndexedPAFAdapter",
        "assemblyNames": [
          "GCF_000307795.1",
          "GCF_025998455.1"
        ],
        "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": "GCF_000307795.1",
          "loc": "NC_018939v1"
        },
        {
          "assembly": "GCF_025998455.1",
          "loc": "NZ_AP026446v1"
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hpylori/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "type": "SyntenyTrack",
            "trackId": "hpylori_reversed_assembly_names",
            "name": "26695 vs CHC155 (assemblyNames reversed)",
            "assemblyNames": [
                "GCF_000307795.1",
                "GCF_025998455.1"
            ],
            "adapter": {
                "type": "PairwiseIndexedPAFAdapter",
                "assemblyNames": [
                    "GCF_000307795.1",
                    "GCF_025998455.1"
                ],
                "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": "GCF_000307795.1",
                    "loc": "NC_018939v1"
                },
                {
                    "assembly": "GCF_025998455.1",
                    "loc": "NZ_AP026446v1"
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > tracks.json <<'JSON'
[
  {
    "type": "SyntenyTrack",
    "trackId": "hpylori_reversed_assembly_names",
    "name": "26695 vs CHC155 (assemblyNames reversed)",
    "assemblyNames": [
      "GCF_000307795.1",
      "GCF_025998455.1"
    ],
    "adapter": {
      "type": "PairwiseIndexedPAFAdapter",
      "assemblyNames": [
        "GCF_000307795.1",
        "GCF_025998455.1"
      ],
      "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"
        }
      }
    }
  }
]
JSON

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "tracks": [
        [
          "hpylori_reversed_assembly_names"
        ]
      ],
      "collapseEmptyRows": true,
      "levelHeights": [
        200
      ],
      "views": [
        {
          "assembly": "GCF_000307795.1",
          "loc": "NC_018939v1"
        },
        {
          "assembly": "GCF_025998455.1",
          "loc": "NZ_AP026446v1"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/hpylori/config.json \
  --tracks tracks.json \
  --spec session.json \
  --width 1500 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "sessionTracks": [
    {
      "type": "SyntenyTrack",
      "trackId": "hpylori_reversed_assembly_names",
      "name": "26695 vs CHC155 (assemblyNames reversed)",
      "assemblyNames": [
        "GCF_000307795.1",
        "GCF_025998455.1"
      ],
      "adapter": {
        "type": "PairwiseIndexedPAFAdapter",
        "assemblyNames": [
          "GCF_000307795.1",
          "GCF_025998455.1"
        ],
        "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": "GCF_000307795.1",
          "loc": "NC_018939v1"
        },
        {
          "assembly": "GCF_025998455.1",
          "loc": "NZ_AP026446v1"
        }
      ]
    }
  ]
}
JSON

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

The figure's clicks open the synteny warnings dialog; this command draws the view under it.

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.

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.
Open in JBrowse Web ↗

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

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

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

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

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

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

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

npx @jbrowse/img dotplot --config https://jbrowse.org/demos/hpylori/config.json \
  --spec session.json \
  --width 1500 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

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

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

The figure's clicks switch the import form to Manual, which this command does not do, so its picture differs there.

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.

26695 (x) against J99 (y). The backbone runs anti-diagonal.
Open in JBrowse Web ↗

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your 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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure has GCF_000307795.1 on X and GCF_000982695.1 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. 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 both axes itself.This figure uses “26695_vs_j99.pif”.
  4. Click Launch.

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

{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "26695_vs_j99.pif"
      ],
      "views": [
        {
          "assembly": "GCF_000307795.1"
        },
        {
          "assembly": "GCF_000982695.1"
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hpylori/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "DotplotView",
            "tracks": [
                "26695_vs_j99.pif"
            ],
            "views": [
                {
                    "assembly": "GCF_000307795.1"
                },
                {
                    "assembly": "GCF_000982695.1"
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "26695_vs_j99.pif"
      ],
      "views": [
        {
          "assembly": "GCF_000307795.1"
        },
        {
          "assembly": "GCF_000982695.1"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img dotplot --config https://jbrowse.org/demos/hpylori/config.json \
  --spec session.json \
  --width 1500 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "26695_vs_j99.pif"
      ],
      "views": [
        {
          "assembly": "GCF_000307795.1"
        },
        {
          "assembly": "GCF_000982695.1"
        }
      ]
    }
  ]
}
JSON

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

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

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

A single all-vs-all PAF is the alternative to one file per pair: every band of the stack reads the same file, in any row order, at the cost of renaming each genome's sequences to PanSN names before aligning (Synteny visualization (all-vs-all minimap2)).

Take the third assembly from its hub and add 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 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.

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

  1. Choose Manual, then set a genome for each row
  2. Add a third row for the third strain
  3. Each arrow between rows has already found its alignment
  4. It opens empty; add each strain's genes from its own row
  5. Three strains stacked with their genes, alignments drawn between
Open this view in JBrowse Web ↗ ·

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

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

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

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

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

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

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

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

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "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

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.

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

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your 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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_000307795.1, GCF_025998455.1, GCF_000982695.1.
  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.pif”.
  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 one needs a bgzip-indexed PAF (.pif.gz + .tbi).This figure uses “chc155_vs_j99.pif”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Row 1 (GCF_000307795.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
    2. Type your region of interest into the location box and press Enter.This figure is at NC_018939v1:1489400-1509400[rev].
  8. Row 2 (GCF_025998455.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
    2. Type your region of interest into the location box and press Enter.This figure is at NZ_AP026446v1:99000-119000.
  9. Row 3 (GCF_000982695.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
    2. Type your region of interest into the location box and press Enter.This figure is at NZ_CP011330v1:1238100-1258100.

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hpylori/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "drawCurves": True,
            "tracks": [
                [
                    "26695_vs_chc155.pif"
                ],
                [
                    "chc155_vs_j99.pif"
                ]
            ],
            "views": [
                {
                    "loc": "NC_018939v1:1489400-1509400[rev]",
                    "assembly": "GCF_000307795.1",
                    "tracks": [
                        {
                            "trackId": "GCF_000307795.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            }
                        }
                    ]
                },
                {
                    "loc": "NZ_AP026446v1:99000-119000",
                    "assembly": "GCF_025998455.1",
                    "tracks": [
                        {
                            "trackId": "GCF_025998455.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            }
                        }
                    ]
                },
                {
                    "loc": "NZ_CP011330v1:1238100-1258100",
                    "assembly": "GCF_000982695.1",
                    "tracks": [
                        {
                            "trackId": "GCF_000982695.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            }
                        }
                    ]
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/hpylori/config.json \
  --spec session.json \
  --width 1500 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}
JSON

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

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

Coloring genes by ortholog

NCBI reuses standardized gene symbols across bacterial strains, so the symbol is effectively an ortholog id. In grammar-of-graphics terms, a track's color is a color scale, a field mapped to colors. Pick Color by... → Attribute... on each gene track's menu and enter gene as the field. An ortholog is one color down all the panels, and features with no gene value (most genes here have only a locus tag) stay grey. Inside the inversion, rsmA and rlmN trade places in J99. Advanced → Edit plot... in the same menu shows the setting as text and applies edits live.

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.
Open in JBrowse Web ↗

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your 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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_000307795.1, GCF_025998455.1, GCF_000982695.1.
  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.pif”.
  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 one needs a bgzip-indexed PAF (.pif.gz + .tbi).This figure uses “chc155_vs_j99.pif”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Row 1 (GCF_000307795.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
    2. Type your region of interest into the location box and press Enter.This figure is at NC_018939v1:1489400-1509400[rev].
  8. Row 2 (GCF_025998455.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
    2. Type your region of interest into the location box and press Enter.This figure is at NZ_AP026446v1:99000-119000.
  9. Row 3 (GCF_000982695.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
    2. Type your region of interest into the location box and press Enter.This figure is at NZ_CP011330v1:1238100-1258100.

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hpylori/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "drawCurves": True,
            "tracks": [
                [
                    "26695_vs_chc155.pif"
                ],
                [
                    "chc155_vs_j99.pif"
                ]
            ],
            "views": [
                {
                    "loc": "NC_018939v1:1489400-1509400[rev]",
                    "assembly": "GCF_000307795.1",
                    "tracks": [
                        {
                            "trackId": "GCF_000307795.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            }
                        }
                    ]
                },
                {
                    "loc": "NZ_AP026446v1:99000-119000",
                    "assembly": "GCF_025998455.1",
                    "tracks": [
                        {
                            "trackId": "GCF_025998455.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            }
                        }
                    ]
                },
                {
                    "loc": "NZ_CP011330v1:1238100-1258100",
                    "assembly": "GCF_000982695.1",
                    "tracks": [
                        {
                            "trackId": "GCF_000982695.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            }
                        }
                    ]
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/hpylori/config.json \
  --spec session.json \
  --width 900 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

The figure stacks 2 frames: one command draws each, and ImageMagick stacks them.

Frame 1: Dialog

cat > session-1.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hpylori/config.json \
  --width 900 --height 842 \
  --spec session-1.json -o frame-1.png

The figure was taken after clicks this command does not make, so its picture can differ.

Frame 2: Result

cat > session-2.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hpylori/config.json \
  --width 900 --height 842 \
  --spec session-2.json -o frame-2.png
magick frame-1.png frame-2.png -bordercolor white -border 12 +append 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.

Open in JBrowse Web ↗

Or rebuild it from your own data:

The short route: open the view in JBrowse Web, where File → Open track... adds your own files beside its hosted genome and tracks.

From scratch with your own data, the steps behind the figure:

  1. Open your 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. For JBrowse Web, run jbrowse add-assembly once for each to put them in your config.json.This figure's rows, top to bottom: GCF_000307795.1, GCF_025998455.1, GCF_000982695.1.
  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.pif”.
  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 one needs a bgzip-indexed PAF (.pif.gz + .tbi).This figure uses “chc155_vs_j99.pif”.
  5. Click Launch.
  6. Synteny display settings (the sliders button in the view header) → Curved lines (checked)
  7. Row 1 (GCF_000307795.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
      2. Track menu → Color by... → Attribute... → gene
      3. Track menu → Show... → Legend (unchecked)
    2. Type your region of interest into the location box and press Enter.This figure is at NC_018939v1:1489400-1509400[rev].
  8. Row 2 (GCF_025998455.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
      2. Track menu → Color by... → Attribute... → gene
      3. Track menu → Show... → Legend (unchecked)
    2. Type your region of interest into the location box and press Enter.This figure is at NZ_AP026446v1:99000-119000.
  9. Row 3 (GCF_000982695.1)
    1. Add a track: open this view's track selector and check one your config has, or click + and choose Add track to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq All (GFF)”.
      1. Track menu → Filter by... → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
      2. Track menu → Color by... → Attribute... → gene
      3. Track menu → Show... → Legend (unchecked)
    2. Type your region of interest into the location box and press Enter.This figure is at NZ_CP011330v1:1238100-1258100.

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        }
      ]
    }
  ]
}

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/demos/hpylori/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "drawCurves": True,
            "tracks": [
                [
                    "26695_vs_chc155.pif"
                ],
                [
                    "chc155_vs_j99.pif"
                ]
            ],
            "views": [
                {
                    "loc": "NC_018939v1:1489400-1509400[rev]",
                    "assembly": "GCF_000307795.1",
                    "tracks": [
                        {
                            "trackId": "GCF_000307795.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            },
                            "color": {
                                "field": "gene"
                            },
                            "showLegend": False
                        }
                    ]
                },
                {
                    "loc": "NZ_AP026446v1:99000-119000",
                    "assembly": "GCF_025998455.1",
                    "tracks": [
                        {
                            "trackId": "GCF_025998455.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            },
                            "color": {
                                "field": "gene"
                            },
                            "showLegend": False
                        }
                    ]
                },
                {
                    "loc": "NZ_CP011330v1:1238100-1258100",
                    "assembly": "GCF_000982695.1",
                    "tracks": [
                        {
                            "trackId": "GCF_000982695.1-ncbiGff",
                            "type": "LinearBasicDisplay",
                            "filter": {
                                "genes": "only"
                            },
                            "color": {
                                "field": "gene"
                            },
                            "showLegend": False
                        }
                    ]
                }
            ]
        }
    ],
)
app  # display the widget

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/hpylori/config.json \
  --spec session.json \
  --width 900 --out figure.svg

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

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit: change the location or a track's settings, or add your own track under sessionTracks, and rerun.

The figure stacks 2 frames: one command draws each, and ImageMagick stacks them.

Frame 1: Dialog

cat > session-1.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              }
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hpylori/config.json \
  --width 900 --height 842 \
  --spec session-1.json -o frame-1.png

The figure was taken after clicks this command does not make, so its picture can differ.

Frame 2: Result

cat > session-2.json <<'JSON'
{
  "views": [
    {
      "type": "LinearSyntenyView",
      "drawCurves": true,
      "tracks": [
        [
          "26695_vs_chc155.pif"
        ],
        [
          "chc155_vs_j99.pif"
        ]
      ],
      "views": [
        {
          "loc": "NC_018939v1:1489400-1509400[rev]",
          "assembly": "GCF_000307795.1",
          "tracks": [
            {
              "trackId": "GCF_000307795.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_AP026446v1:99000-119000",
          "assembly": "GCF_025998455.1",
          "tracks": [
            {
              "trackId": "GCF_025998455.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        },
        {
          "loc": "NZ_CP011330v1:1238100-1258100",
          "assembly": "GCF_000982695.1",
          "tracks": [
            {
              "trackId": "GCF_000982695.1-ncbiGff",
              "type": "LinearBasicDisplay",
              "filter": {
                "genes": "only"
              },
              "color": {
                "field": "gene"
              },
              "showLegend": false
            }
          ]
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/hpylori/config.json \
  --width 900 --height 842 \
  --spec session-2.json -o frame-2.png
magick frame-1.png frame-2.png -bordercolor white -border 12 +append 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 config below is the same setting on the hub's gene track:

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": { "genes": "only" },
    "color": { "field": "gene" }
  }
}
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": { "genes": "only" },
    "color": { "field": "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": "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": { "genes": "only" },
    "color": { "field": "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:

  1. Download each strain's sequence and config from its genome hub, so the alignments and the assemblies come from the same files.
  2. Align 26695 to CHC155, CHC155 to J99 and 26695 to J99 with minimap2 -x asm20 --eqx.
  3. 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

See also

Citations