Skip to main content

Pangenome (pggb)

3 videos in this tutorial

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

A pangenome graph stores the sequence several genomes share once, as a path every genome follows, and branches where they differ. We build one of five E. coli strains with pggb and turn its outputs into JBrowse tracks on the K12 genome. Most are linear projections, which flatten the graph onto K12's coordinates so it loads as an ordinary track:

  • synteny between the strains
  • the variants the graph calls against K12
  • the whole-genome alignment
  • depth and per-strain presence, which show the core and accessory genome
  • the graph itself, drawn as a track you browse by locus
Experimental

The graph view is a beta plugin. We welcome your feedback.

Prerequisites

apt install samtools tabix unzip python3 covers four of those on Debian/Ubuntu, and datasets and bedGraphToBigWig are each a single-binary download.

Where the data comes from

The build script fetches the five E. coli RefSeq assemblies by accession with the NCBI datasets CLI. The nanopore reads are the one file to download by hand, with the curl under Testing the CPZ-55 depth trough with nanopore reads.

Building the graph

pggb takes one FASTA of all the genomes, with PanSN names, sample#haplotype#contig. Concatenate the five haploid strains as haplotype 1 and index the result:

for strain in K12 Sakai CFT073 NCTC86 IAI39; do
  awk -v s="$strain" '/^>/{print ">" s "#1#chr"; next} {print}' "$strain.fa"
done > all.fa
bgzip all.fa
samtools faidx all.fa.gz

The pggb image includes every tool below, odgi among them, so wrap docker run once and run pggb:

in_pggb() {
  docker run --rm -u "$(id -u):$(id -g)" -w /data -v "$PWD":/data \
    ghcr.io/pangenome/pggb:202603141454453ade6b "$@"
}

# -n: haplotype count
# -c: mappings kept per segment; raise it along with -n
# -p: minimum identity; -s: segment length
# -V K12:10000: a VCF against the K12 path; -M: a MAF
in_pggb pggb -i /data/all.fa.gz -o /data/pggb \
  -n 5 -c 4 -p 90 -s 5000 -V K12:10000 -M -t "$(nproc)"
og=$(ls pggb/*.smooth.final.og)

Under singularity, singularity exec --bind "$PWD":/data --pwd /data docker://<image> replaces the wrapper body.

Load the genomes

Every projection is a track on a strain's assembly, and each strain's FASTA holds one sequence named chr, the refName the graph's paths are renamed to below. We'll add K12, the reference the projections land on, from a bgzip-compressed, indexed FASTA:

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

{
  "name": "K12",
  "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.fa.gz"
}
jbrowse add-assembly https://jbrowse.org/demos/ecoli_pangenome/K12.fa.gz \
  --name K12

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:

https://jbrowse.org/demos/ecoli_pangenome/K12.fa.gz
https://jbrowse.org/demos/ecoli_pangenome/K12.fa.gz.fai
https://jbrowse.org/demos/ecoli_pangenome/K12.fa.gz.gzi

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

  • Genome name: K12

Sakai, CFT073, NCTC86 and IAI39 load the same way, named as in the assemblyNames of the tracks below.

Synteny between the strains (wfmash)

pggb's first step is an all-vs-all alignment by wfmash, which JBrowse reads as a synteny track once jbrowse make-pif indexes it:

cp pggb/*.alignments.wfmash.paf ecoli_pggb_ava.paf
jbrowse make-pif ecoli_pggb_ava.paf

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

{
  "type": "SyntenyTrack",
  "trackId": "ecoli_pggb_ava",
  "name": "pggb graph: all-vs-all synteny (wfmash)",
  "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "ecoli_pggb_ava.pif.gz",
    "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"]
  }
}
jbrowse add-track ecoli_pggb_ava.pif.gz \
  --trackId ecoli_pggb_ava \
  --name "pggb graph: all-vs-all synteny (wfmash)" \
  --assemblyNames K12,Sakai,CFT073,NCTC86,IAI39 \
  --adapterType MultiGenomeIndexedPAFAdapter \
  --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": "ecoli_pggb_ava",
  "name": "pggb graph: all-vs-all synteny (wfmash)",
  "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "ecoli_pggb_ava.pif.gz",
    "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"]
  }
}

ecoli_pggb_ava.pif.gz 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.

Stack the five strains with Add → Linear synteny view, whose Quick start fills in a row per assembly the track lists.

The wfmash alignment pggb built the graph from: five strains stacked K12 to IAI39, a ribbon between each adjacent pair. The crossings in the bottom band are IAI39's inversions.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearSyntenyView%22%2C%22views%22%3A%5B%7B%22assembly%22%3A%22K12%22%7D%2C%7B%22assembly%22%3A%22Sakai%22%7D%2C%7B%22assembly%22%3A%22CFT073%22%7D%2C%7B%22assembly%22%3A%22NCTC86%22%7D%2C%7B%22assembly%22%3A%22IAI39%22%7D%5D%2C%22tracks%22%3A%5B%22ecoli_pggb_ava%22%5D%2C%22drawCurves%22%3Afalse%2C%22minAlignmentLength%22%3A10000%2C%22levelHeights%22%3A%5B110%2C110%2C110%2C110%5D%2C%22collapseEmptyRows%22%3Atrue%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_synteny

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: K12, Sakai, CFT073, NCTC86, IAI39.
  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 “pggb graph: all-vs-all synteny (wfmash)”.
  4. Click Launch.
  5. Synteny display settings (the sliders button in the view header) → Curved lines (unchecked)
  6. Synteny display settings (the sliders button in the view header) → Min length → drag to 10,000bpHides alignments shorter than this, which is what clears the hairball of short spurious chains at whole-genome zoom.
  7. Drag the bar below a synteny level to resize it.This figure's 4 levels are 110, 110, 110, 110px tall.

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

{
  "views": [
    {
      "type": "LinearSyntenyView",
      "views": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "Sakai"
        },
        {
          "assembly": "CFT073"
        },
        {
          "assembly": "NCTC86"
        },
        {
          "assembly": "IAI39"
        }
      ],
      "tracks": [
        "ecoli_pggb_ava"
      ],
      "drawCurves": false,
      "minAlignmentLength": 10000,
      "levelHeights": [
        110,
        110,
        110,
        110
      ],
      "collapseEmptyRows": true
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearSyntenyView",
            "views": [
                {
                    "assembly": "K12"
                },
                {
                    "assembly": "Sakai"
                },
                {
                    "assembly": "CFT073"
                },
                {
                    "assembly": "NCTC86"
                },
                {
                    "assembly": "IAI39"
                }
            ],
            "tracks": [
                "ecoli_pggb_ava"
            ],
            "drawCurves": False,
            "minAlignmentLength": 10000,
            "levelHeights": [
                110,
                110,
                110,
                110
            ],
            "collapseEmptyRows": True
        }
    ],
)
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": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "Sakai"
        },
        {
          "assembly": "CFT073"
        },
        {
          "assembly": "NCTC86"
        },
        {
          "assembly": "IAI39"
        }
      ],
      "tracks": [
        "ecoli_pggb_ava"
      ],
      "drawCurves": false,
      "minAlignmentLength": 10000,
      "levelHeights": [
        110,
        110,
        110,
        110
      ],
      "collapseEmptyRows": true
    }
  ]
}
JSON

npx @jbrowse/img synteny --config https://jbrowse.org/demos/ecoli_pangenome/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",
      "views": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "Sakai"
        },
        {
          "assembly": "CFT073"
        },
        {
          "assembly": "NCTC86"
        },
        {
          "assembly": "IAI39"
        }
      ],
      "tracks": [
        "ecoli_pggb_ava"
      ],
      "drawCurves": false,
      "minAlignmentLength": 10000,
      "levelHeights": [
        110,
        110,
        110,
        110
      ],
      "collapseEmptyRows": true
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1500 --height 715 \
  --timeout 120000 \
  --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.

Select a span on K12's ruler and pick Launch → Linear synteny view to stack the strains over that span alone. The same selection on another strain's row, with Replace current view, re-anchors the stack on that strain:

One selection, a synteny stack: the Launch menu over a K12 window, the stack anchored on K12, where Sakai's row has a prophage K12 lacks, and a drag across it on the Sakai row re-anchoring the stack on Sakai.

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

  1. K-12, with one lane per strain and the graph segments
  2. Select a span and launch a stack of the strains on it
  3. Sakai's row runs twice as long: 38 kb sits where K-12 has none
  4. Select that stretch on Sakai's row to re-anchor the stack on Sakai
  5. Anchored on Sakai: the white wedge is its prophage, which K-12 lacks

Open this view in JBrowse Web ↗ · Open this view in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A783%2C000-832%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ecoli_ava%22%2C%22type%22%3A%22LGVSyntenyDisplay%22%2C%22facet%22%3A%22mateAssembly%22%2C%22hideSelfAlignments%22%3Atrue%2C%22featureHeight%22%3A14%2C%22height%22%3A135%7D%2C%7B%22trackId%22%3A%22ecoli_minigraph_segments%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22none%22%2C%22height%22%3A60%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+synteny%2Fecoli_roundtrip

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file.This figure uses “E. coli pangenome (all-vs-all PAF)”.
    1. Track menu → Group by... → Mate assemblySynteny tracks only: one section per assembly on the other side of the alignment.
    2. Track menu → Group by... → Hide self-alignment lane (checked)Below a divider at the foot of that submenu, and only meaningful on an all-vs-all track, which is what has a self lane.
    3. Track menu → Feature height → Custom... → 14px
  3. Add the next track the same way.This figure uses “minigraph graph: rGFA segments (browsable by locus)”.
    1. Track menu → Show... → Labels → None
  4. Type your region of interest into the location box and press Enter.This figure is at chr:783,000-832,000.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:783,000-832,000",
      "tracks": [
        {
          "trackId": "ecoli_ava",
          "type": "LGVSyntenyDisplay",
          "facet": "mateAssembly",
          "hideSelfAlignments": true,
          "featureHeight": 14,
          "height": 135
        },
        {
          "trackId": "ecoli_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 60
        }
      ]
    }
  ]
}

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:783,000-832,000",
      "tracks": [
        {
          "trackId": "ecoli_ava",
          "type": "LGVSyntenyDisplay",
          "facet": "mateAssembly",
          "hideSelfAlignments": true,
          "featureHeight": 14,
          "height": 135
        },
        {
          "trackId": "ecoli_minigraph_segments",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 60
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1920 --height 780 \
  --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.

Synteny read out of the graph with odgi untangle

odgi untangle follows each strain's path and reports which stretch of the K12 path it traverses, so this synteny comes from the graph itself. -p writes it as a PAF, which make-pif indexes the same way:

printf 'K12#1#chr\n' > target.txt
printf 'Sakai#1#chr\nCFT073#1#chr\nNCTC86#1#chr\nIAI39#1#chr\n' > query.txt
# -m merges runs shorter than this into the previous segment
# -j is the minimum jaccard similarity for a match
# -e forces a segment boundary every N bp; omit it on graphs with many haplotypes
in_pggb odgi untangle -i "/data/$og" \
  -R /data/target.txt -Q /data/query.txt -m 1000 -j 0.5 -e 5000 -p -t "$(nproc)" \
  > ecoli_pggb_untangle.paf
jbrowse make-pif ecoli_pggb_untangle.paf

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

{
  "type": "SyntenyTrack",
  "trackId": "ecoli_pggb_untangle",
  "name": "pggb graph: synteny from the graph (odgi untangle)",
  "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "ecoli_pggb_untangle.pif.gz",
    "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"]
  }
}
jbrowse add-track ecoli_pggb_untangle.pif.gz \
  --trackId ecoli_pggb_untangle \
  --name "pggb graph: synteny from the graph (odgi untangle)" \
  --assemblyNames K12,Sakai,CFT073,NCTC86,IAI39 \
  --adapterType MultiGenomeIndexedPAFAdapter \
  --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": "ecoli_pggb_untangle",
  "name": "pggb graph: synteny from the graph (odgi untangle)",
  "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
  "adapter": {
    "type": "MultiGenomeIndexedPAFAdapter",
    "uri": "ecoli_pggb_untangle.pif.gz",
    "assemblyNames": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"]
  }
}

ecoli_pggb_untangle.pif.gz 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.

untangle_to_bed.py turns the same PAF into a BED with a strain column, so one track can draw every strain on K12's axis. In grammar-of-graphics terms, rows assigns one row per strain, and color is a color scale that here uses scale: "identity" for the colors the file states, red where the strain runs inverted:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/untangle_to_bed.py
python3 untangle_to_bed.py ecoli_pggb_untangle.paf chr > ecoli_pggb_untangle_rows.bed
jbrowse sort-bed ecoli_pggb_untangle_rows.bed | bgzip > ecoli_pggb_untangle_rows.bed.gz
tabix -p bed ecoli_pggb_untangle_rows.bed.gz

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

{
  "type": "FeatureTrack",
  "trackId": "ecoli_pggb_untangle_rows",
  "name": "pggb graph: untangle per strain (orientation, vs K12)",
  "uri": "ecoli_pggb_untangle_rows.bed.gz",
  "assemblyNames": ["K12"],
  "displays": [
    {
      "type": "LinearMultiRowFeatureDisplay",
      "rows": {
        "field": "strain",
        "domain": ["Sakai", "CFT073", "NCTC86", "IAI39"]
      },
      "color": {
        "scale": "identity",
        "domain": ["rgb(153,153,153)", "rgb(214,39,40)"],
        "labels": ["Same orientation as K12", "Inverted"]
      }
    }
  ]
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "ecoli_pggb_untangle_rows",
  "name": "pggb graph: untangle per strain (orientation, vs K12)",
  "uri": "ecoli_pggb_untangle_rows.bed.gz",
  "assemblyNames": ["K12"],
  "displays": [
    {
      "type": "LinearMultiRowFeatureDisplay",
      "rows": {
        "field": "strain",
        "domain": ["Sakai", "CFT073", "NCTC86", "IAI39"]
      },
      "color": {
        "scale": "identity",
        "domain": ["rgb(153,153,153)", "rgb(214,39,40)"],
        "labels": ["Same orientation as K12", "Inverted"]
      }
    }
  ]
}'

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": "ecoli_pggb_untangle_rows",
  "name": "pggb graph: untangle per strain (orientation, vs K12)",
  "uri": "ecoli_pggb_untangle_rows.bed.gz",
  "assemblyNames": ["K12"],
  "displays": [
    {
      "type": "LinearMultiRowFeatureDisplay",
      "rows": {
        "field": "strain",
        "domain": ["Sakai", "CFT073", "NCTC86", "IAI39"]
      },
      "color": {
        "scale": "identity",
        "domain": ["rgb(153,153,153)", "rgb(214,39,40)"],
        "labels": ["Same orientation as K12", "Inverted"]
      }
    }
  ]
}

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

The odgi untangle synteny read two ways, with each of IAI39's inverted arms boxed in a distinct color in both. Above, one row per strain over the whole K12 chromosome, red where the strain runs backwards and white where it has no segment. Below, K12 against IAI39 as a dotplot, where every descending segment is an inversion.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A1-4%2C641%2C652%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ecoli_pggb_untangle_rows%22%2C%22type%22%3A%22LinearMultiRowFeatureDisplay%22%2C%22height%22%3A240%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_untangle_rows

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “pggb graph: untangle per strain (orientation, vs K12)”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr:1-4,641,652.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1-4,641,652",
      "tracks": [
        {
          "trackId": "ecoli_pggb_untangle_rows",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 240
        }
      ]
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "K12",
            "loc": "chr:1-4,641,652",
            "tracks": [
                {
                    "trackId": "ecoli_pggb_untangle_rows",
                    "type": "LinearMultiRowFeatureDisplay",
                    "height": 240
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --assembly K12 --loc chr:1-4,641,652 \
  --track ecoli_pggb_untangle_rows display:LinearMultiRowFeatureDisplay '{"height":240}' \
  --width 1000 --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: Rows

cat > session-1.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1-4,641,652",
      "tracks": [
        {
          "trackId": "ecoli_pggb_untangle_rows",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 240
        }
      ]
    }
  ]
}
JSON

cat > callouts-1.json <<'JSON'
[
  {
    "type": "box",
    "color": "#ef6c00",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:213,443-262,948"
    }
  },
  {
    "type": "box",
    "color": "#2e7d32",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:302,899-501,436"
    }
  },
  {
    "type": "box",
    "color": "#6a1b9a",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:914,963-1,194,177"
    }
  },
  {
    "type": "box",
    "color": "#1565c0",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:1,635,838-2,229,302"
    }
  },
  {
    "type": "box",
    "color": "#00838f",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:3,946,786-4,171,723"
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 450 \
  --timeout 90000 \
  --spec session-1.json --annotations callouts-1.json -o frame-1.png

Frame 2: Dotplot

cat > session-2.json <<'JSON'
{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "ecoli_pggb_untangle"
      ],
      "views": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "IAI39"
        }
      ]
    }
  ]
}
JSON

cat > callouts-2.json <<'JSON'
[
  {
    "type": "box",
    "color": "#ef6c00",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:213,443-262,948",
      "vLoc": "chr:449,188-493,004"
    }
  },
  {
    "type": "box",
    "color": "#2e7d32",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:302,899-501,436",
      "vLoc": "chr:228,426-443,280"
    }
  },
  {
    "type": "box",
    "color": "#6a1b9a",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:914,963-1,194,177",
      "vLoc": "chr:2,058,958-2,336,701"
    }
  },
  {
    "type": "box",
    "color": "#1565c0",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:1,635,838-2,229,302",
      "vLoc": "chr:906,630-1,574,975"
    }
  },
  {
    "type": "box",
    "color": "#00838f",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:3,946,786-4,171,723",
      "vLoc": "chr:3,083,154-3,330,675"
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 640 \
  --timeout 120000 \
  --spec session-2.json --annotations callouts-2.json -o frame-2.png
magick frame-1.png frame-2.png -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 ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22DotplotView%22%2C%22tracks%22%3A%5B%22ecoli_pggb_untangle%22%5D%2C%22views%22%3A%5B%7B%22assembly%22%3A%22K12%22%7D%2C%7B%22assembly%22%3A%22IAI39%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_untangle_dotplot

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 has K12 on X and IAI39 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 “pggb graph: synteny from the graph (odgi untangle)”.
  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/ecoli_pangenome/config.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "ecoli_pggb_untangle"
      ],
      "views": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "IAI39"
        }
      ]
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "DotplotView",
            "tracks": [
                "ecoli_pggb_untangle"
            ],
            "views": [
                {
                    "assembly": "K12"
                },
                {
                    "assembly": "IAI39"
                }
            ]
        }
    ],
)
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": [
        "ecoli_pggb_untangle"
      ],
      "views": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "IAI39"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/img dotplot --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --spec session.json \
  --width 1000 --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: Rows

cat > session-1.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1-4,641,652",
      "tracks": [
        {
          "trackId": "ecoli_pggb_untangle_rows",
          "type": "LinearMultiRowFeatureDisplay",
          "height": 240
        }
      ]
    }
  ]
}
JSON

cat > callouts-1.json <<'JSON'
[
  {
    "type": "box",
    "color": "#ef6c00",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:213,443-262,948"
    }
  },
  {
    "type": "box",
    "color": "#2e7d32",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:302,899-501,436"
    }
  },
  {
    "type": "box",
    "color": "#6a1b9a",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:914,963-1,194,177"
    }
  },
  {
    "type": "box",
    "color": "#1565c0",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:1,635,838-2,229,302"
    }
  },
  {
    "type": "box",
    "color": "#00838f",
    "strokeWidth": 3,
    "anchor": {
      "trackId": "ecoli_pggb_untangle_rows",
      "loc": "chr:3,946,786-4,171,723"
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 450 \
  --timeout 90000 \
  --spec session-1.json --annotations callouts-1.json -o frame-1.png

Frame 2: Dotplot

cat > session-2.json <<'JSON'
{
  "views": [
    {
      "type": "DotplotView",
      "tracks": [
        "ecoli_pggb_untangle"
      ],
      "views": [
        {
          "assembly": "K12"
        },
        {
          "assembly": "IAI39"
        }
      ]
    }
  ]
}
JSON

cat > callouts-2.json <<'JSON'
[
  {
    "type": "box",
    "color": "#ef6c00",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:213,443-262,948",
      "vLoc": "chr:449,188-493,004"
    }
  },
  {
    "type": "box",
    "color": "#2e7d32",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:302,899-501,436",
      "vLoc": "chr:228,426-443,280"
    }
  },
  {
    "type": "box",
    "color": "#6a1b9a",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:914,963-1,194,177",
      "vLoc": "chr:2,058,958-2,336,701"
    }
  },
  {
    "type": "box",
    "color": "#1565c0",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:1,635,838-2,229,302",
      "vLoc": "chr:906,630-1,574,975"
    }
  },
  {
    "type": "box",
    "color": "#00838f",
    "strokeWidth": 3,
    "anchor": {
      "hLoc": "chr:3,946,786-4,171,723",
      "vLoc": "chr:3,083,154-3,330,675"
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 640 \
  --timeout 120000 \
  --spec session-2.json --annotations callouts-2.json -o frame-2.png
magick frame-1.png frame-2.png -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.

Variants against K12 (pggb -V)

pggb -V wrote a VCF of every variant the graph decomposes against the K12 path, genotyped in the other four strains. Its CHROM is the PanSN path, K12#1#chr, so rename it to the assembly's chr:

printf 'K12#1#chr\tchr\n' > rename_chrs.tsv
in_pggb bash -c "bcftools annotate --rename-chrs /data/rename_chrs.tsv \
  /data/pggb/*.smooth.final.K12.decomposed.vcf \
  | bcftools sort -Oz -o /data/ecoli_pggb.vcf.gz && tabix -p vcf /data/ecoli_pggb.vcf.gz"

Each strain is one haplotype, so unit: "haplotype" draws one row per strain, colored by that strain's allele:

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

{
  "type": "VariantTrack",
  "trackId": "ecoli_pggb_variants",
  "name": "pggb graph: pangenome variants (vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "ecoli_pggb.vcf.gz"
  },
  "displays": [
    { "type": "LinearMultiSampleVariantDisplay", "unit": "haplotype" }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "ecoli_pggb_variants",
  "name": "pggb graph: pangenome variants (vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "ecoli_pggb.vcf.gz"
  },
  "displays": [
    { "type": "LinearMultiSampleVariantDisplay", "unit": "haplotype" }
  ]
}'

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": "VariantTrack",
  "trackId": "ecoli_pggb_variants",
  "name": "pggb graph: pangenome variants (vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "ecoli_pggb.vcf.gz"
  },
  "displays": [
    { "type": "LinearMultiSampleVariantDisplay", "unit": "haplotype" }
  ]
}

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

With a length after the path name, as in -V K12:10000, pggb runs vcfbub and vcfwave over the VCF to decompose large sites into smaller variants, giving *.decomposed.vcf.

The undecomposed *.smooth.final.K12.vcf keeps one record per bubble (where paths split and rejoin) for the graph track to read.

Whole-genome alignment onto K12 (MAF)

pggb -M wrote the multiple alignment as a MAF. Re-root every block on K12, rename the rows to sample.chr, and blank the padding smoothxg writes around each row, then convert the MAF to the tabix-indexed BED that MafTabixAdapter reads:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/reroot_maf.py
# all.fa.gz is the pggb input: the padding sits on either end of a row, so
# only the genome says which bases are the row's own
python3 reroot_maf.py pggb/*.smooth.maf ecoli_pggb.maf all.fa.gz K12#1#chr
curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/maf_to_bed.py
python3 maf_to_bed.py ecoli_pggb.maf ecoli_pggb.maf.bed
bgzip ecoli_pggb.maf.bed
tabix -p bed ecoli_pggb.maf.bed.gz

To order the rows by how much graph each pair of strains shares, build a tree from odgi similarity and point nhLocation at it:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/odgi_similarity_to_newick.py
in_pggb odgi similarity -i "/data/$og" -D '#' -p 1 > ecoli_pggb_similarity.tsv
python3 odgi_similarity_to_newick.py ecoli_pggb_similarity.tsv ecoli_pggb.nh

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

{
  "type": "MafTrack",
  "trackId": "ecoli_pggb_maf",
  "name": "pggb graph: whole-genome alignment (MAF, vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "MafTabixAdapter",
    "samples": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
    "nhLocation": { "uri": "ecoli_pggb.nh" },
    "uri": "ecoli_pggb.maf.bed.gz"
  }
}
jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "ecoli_pggb_maf",
  "name": "pggb graph: whole-genome alignment (MAF, vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "MafTabixAdapter",
    "samples": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
    "nhLocation": { "uri": "ecoli_pggb.nh" },
    "uri": "ecoli_pggb.maf.bed.gz"
  }
}'

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": "MafTrack",
  "trackId": "ecoli_pggb_maf",
  "name": "pggb graph: whole-genome alignment (MAF, vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "MafTabixAdapter",
    "samples": ["K12", "Sakai", "CFT073", "NCTC86", "IAI39"],
    "nhLocation": { "uri": "ecoli_pggb.nh" },
    "uri": "ecoli_pggb.maf.bed.gz"
  }
}

ecoli_pggb.nh, ecoli_pggb.maf.bed.gz are relative to a config.json. Replace each with its URL or its path on this computer.

The graph's whole-genome alignment projected onto K12, one row per strain in the tree's order, with the variant calls above. A blank row is a strain with no alignment to K12 there.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A4%2C540%2C000-4%2C600%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_variants%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22showVariantLane%22%3Atrue%2C%22unit%22%3A%22haplotype%22%2C%22height%22%3A170%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_maf%22%2C%22type%22%3A%22LinearMafDisplay%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fmaf

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 genes”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “pggb graph: pangenome variants (vs K12)”.
    1. Track menu → Show... → Show variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Show as genotype matrix" is unchecked.
    2. Track menu → Rows → Per haplotypeSplits each sample into one row per haplotype. The item stays disabled until phased variants are found in the file.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed MAF (.maf.gz + .tbi).This figure uses “pggb graph: whole-genome alignment (MAF, vs K12)”.
  5. Type your region of interest into the location box and press Enter.This figure is at chr:4,540,000-4,600,000.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:4,540,000-4,600,000",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay"
        },
        {
          "trackId": "ecoli_pggb_variants",
          "type": "LinearMultiSampleVariantDisplay",
          "showVariantLane": true,
          "unit": "haplotype",
          "height": 170
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay"
        }
      ]
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "K12",
            "loc": "chr:4,540,000-4,600,000",
            "tracks": [
                {
                    "trackId": "K12_genes",
                    "type": "LinearBasicDisplay"
                },
                {
                    "trackId": "ecoli_pggb_variants",
                    "type": "LinearMultiSampleVariantDisplay",
                    "showVariantLane": True,
                    "unit": "haplotype",
                    "height": 170
                },
                {
                    "trackId": "ecoli_pggb_maf",
                    "type": "LinearMafDisplay"
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --assembly K12 --loc chr:4,540,000-4,600,000 \
  --track K12_genes display:LinearBasicDisplay \
  --track ecoli_pggb_variants display:LinearMultiSampleVariantDisplay '{"showVariantLane":true,"unit":"haplotype","height":170}' \
  --track ecoli_pggb_maf display:LinearMafDisplay \
  --width 1000 --out figure.svg

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

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:4,540,000-4,600,000",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay"
        },
        {
          "trackId": "ecoli_pggb_variants",
          "type": "LinearMultiSampleVariantDisplay",
          "showVariantLane": true,
          "unit": "haplotype",
          "height": 170
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 710 \
  --timeout 90000 \
  --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.

Drag across the rows, and the menu on release lists each strain the selection covers under two submenus:

  • Open aligned genome at the matching region opens that strain's genome at the aligned stretch
  • Linear synteny view, K12 vs... opens K12 and that strain as a linear synteny view
From the pggb alignment's rows to a two-strain synteny view: a drag across the rows, the menu listing the strains it covers, and the synteny view the IAI39 entry opens, with no ribbon under ybhH and ybhI, the two K12 genes IAI39 lacks.

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

  1. The pggb alignment, one row per strain; IAI39's row is blank mid-window
  2. Drag across the rows; the menu offers a view per strain
  3. K-12 over IAI39: no ribbon under ybhH and ybhI, which IAI39 lacks

Open this view in JBrowse Web ↗ · Open this view in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A800%2C100-804%2C300%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showOnlyGenes%22%3Atrue%2C%22displayMode%22%3A%22compact%22%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_maf%22%2C%22type%22%3A%22LinearMafDisplay%22%2C%22showTree%22%3Atrue%2C%22height%22%3A150%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+synteny%2Fmaf_row_synteny

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 genes”.
    1. Track menu → Show only genes (checked)
    2. Track menu → Feature height → Compact
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed MAF (.maf.gz + .tbi).This figure uses “pggb graph: whole-genome alignment (MAF, vs K12)”.
    1. Track menu → Show... → Show tree (checked)On by default. The item is disabled until there is a tree to show — a clustering run, or a MAF track’s guide tree; the row labels have their own toggle beneath it.
  4. Type your region of interest into the location box and press Enter.This figure is at chr:800,100-804,300.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:800,100-804,300",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact"
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay",
          "showTree": true,
          "height": 150
        }
      ]
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "K12",
            "loc": "chr:800,100-804,300",
            "tracks": [
                {
                    "trackId": "K12_genes",
                    "type": "LinearBasicDisplay",
                    "showOnlyGenes": True,
                    "displayMode": "compact"
                },
                {
                    "trackId": "ecoli_pggb_maf",
                    "type": "LinearMafDisplay",
                    "showTree": True,
                    "height": 150
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --assembly K12 --loc chr:800,100-804,300 \
  --track K12_genes display:LinearBasicDisplay '{"showOnlyGenes":true,"displayMode":"compact"}' \
  --track ecoli_pggb_maf display:LinearMafDisplay '{"showTree":true,"height":150}' \
  --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": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:800,100-804,300",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "showOnlyGenes": true,
          "displayMode": "compact"
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay",
          "showTree": true,
          "height": 150
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1920 --height 1340 \
  --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.

Pangenome depth: core versus accessory sequence

odgi depth counts how many paths cross each K12 window: about five over core sequence and one over sequence only K12 has. Make 500 bp windows, count, and write a bigWig:

reflen=$(awk -v p="K12#1#chr" '$1 == p {print $2}' all.fa.gz.fai)
awk -v p="K12#1#chr" -v len="$reflen" -v w=500 \
  'BEGIN { for (s = 0; s < len; s += w) { e = s + w; if (e > len) e = len
           print p "\t" s "\t" e } }' > depth_windows.bed

in_pggb odgi depth -i "/data/$og" -b /data/depth_windows.bed |
  awk -v p="K12#1#chr" -v OFS='\t' '$1 == p && $4 + 0 == $4 { print "chr", $2, $3, $4 }' |
  sort -k1,1 -k2,2n > ecoli_pggb_depth.bedgraph

printf 'chr\t%s\n' "$reflen" > chrom.sizes
bedGraphToBigWig ecoli_pggb_depth.bedgraph chrom.sizes ecoli_pggb_depth.bw

The config draws reference lines at the strain count and at 1:

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

{
  "type": "QuantitativeTrack",
  "trackId": "ecoli_pggb_depth",
  "name": "pggb graph: pangenome depth (paths over K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "ecoli_pggb_depth.bw"
  },
  "displayDefaults": {
    "scales": {
      "y": {
        "title": "paths",
        "rules": [
          { "value": 5, "label": "all five strains" },
          { "value": 1, "label": "K12 alone" }
        ]
      }
    }
  }
}
jbrowse add-track ecoli_pggb_depth.bw \
  --trackId ecoli_pggb_depth \
  --name "pggb graph: pangenome depth (paths over K12)" \
  --assemblyNames K12 \
  --displayDefaults '{"scales":{"y":{"title":"paths","rules":[{"value":5,"label":"all five strains"},{"value":1,"label":"K12 alone"}]}}}' \
  --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": "QuantitativeTrack",
  "trackId": "ecoli_pggb_depth",
  "name": "pggb graph: pangenome depth (paths over K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "BigWigAdapter",
    "uri": "ecoli_pggb_depth.bw"
  },
  "displayDefaults": {
    "scales": {
      "y": {
        "title": "paths",
        "rules": [
          { "value": 5, "label": "all five strains" },
          { "value": 1, "label": "K12 alone" }
        ]
      }
    }
  }
}

ecoli_pggb_depth.bw is relative to a config.json. Replace it with its URL or its path on this computer.

The curve rises past the strain-count line over the rRNA operons (repeated ribosomal RNA genes), because the graph collapses their copies into one.

Per-strain presence

odgi pav splits depth per strain, as the fraction of each window that the strain's path crosses. Write one bigWig per strain other than K12:

in_pggb odgi pav -i "/data/$og" -b /data/depth_windows.bed > pav.tsv
for strain in Sakai CFT073 NCTC86 IAI39; do
  awk -F'\t' -v OFS='\t' -v g="${strain}#1#chr" \
    '$5 == g && $6 + 0 == $6 { print "chr", $2, $3, $6 }' pav.tsv |
    sort -k1,1 -k2,2n > "pav_${strain}.bedgraph"
  bedGraphToBigWig "pav_${strain}.bedgraph" chrom.sizes "ecoli_pggb_pav_${strain}.bw"
done

The four bigWigs load as one heatmap track, a row per strain, where a white column is a stretch that strain lacks:

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

{
  "type": "MultiQuantitativeTrack",
  "trackId": "ecoli_pggb_pav",
  "name": "pggb graph: per-strain presence (odgi pav, vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "Sakai",
        "uri": "ecoli_pggb_pav_Sakai.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "CFT073",
        "uri": "ecoli_pggb_pav_CFT073.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "NCTC86",
        "uri": "ecoli_pggb_pav_NCTC86.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "IAI39",
        "uri": "ecoli_pggb_pav_IAI39.bw"
      }
    ]
  },
  "displayDefaults": { "mark": "span" }
}
jbrowse add-track-json '{
  "type": "MultiQuantitativeTrack",
  "trackId": "ecoli_pggb_pav",
  "name": "pggb graph: per-strain presence (odgi pav, vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "Sakai",
        "uri": "ecoli_pggb_pav_Sakai.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "CFT073",
        "uri": "ecoli_pggb_pav_CFT073.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "NCTC86",
        "uri": "ecoli_pggb_pav_NCTC86.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "IAI39",
        "uri": "ecoli_pggb_pav_IAI39.bw"
      }
    ]
  },
  "displayDefaults": { "mark": "span" }
}'

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": "MultiQuantitativeTrack",
  "trackId": "ecoli_pggb_pav",
  "name": "pggb graph: per-strain presence (odgi pav, vs K12)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "MultiWiggleAdapter",
    "subadapters": [
      {
        "type": "BigWigAdapter",
        "name": "Sakai",
        "uri": "ecoli_pggb_pav_Sakai.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "CFT073",
        "uri": "ecoli_pggb_pav_CFT073.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "NCTC86",
        "uri": "ecoli_pggb_pav_NCTC86.bw"
      },
      {
        "type": "BigWigAdapter",
        "name": "IAI39",
        "uri": "ecoli_pggb_pav_IAI39.bw"
      }
    ]
  },
  "displayDefaults": { "mark": "span" }
}

ecoli_pggb_pav_Sakai.bw, ecoli_pggb_pav_CFT073.bw, ecoli_pggb_pav_NCTC86.bw, ecoli_pggb_pav_IAI39.bw are relative to a config.json. Replace each with its URL or its path on this computer.

Open chr:450,000-590,000 with the K12 genes on. The figure shades chr:501,500-539,000.

K12 genes, the aggregate depth curve, and odgi pav on the same windows below it, one row per non-K12 strain. Under the shaded span the IAI39 row goes white and the curve drops by one, and in its middle CFT073's row goes white too and the curve drops again; where the curve falls to K12 alone at the right, every row goes white.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A450%2C000-590%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr%22%2C%22start%22%3A501500%2C%22end%22%3A539000%2C%22color%22%3A%22rgba%28255%2C193%2C7%2C0.30%29%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A90%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_depth%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22height%22%3A150%2C%22scales%22%3A%7B%22y%22%3A%7B%22title%22%3A%22paths%22%2C%22rules%22%3A%5B%7B%22value%22%3A5%2C%22label%22%3A%22all+five+strains%22%7D%2C%7B%22value%22%3A1%2C%22label%22%3A%22K12+alone%22%7D%5D%7D%7D%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_pav%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22mark%22%3A%22span%22%2C%22height%22%3A240%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpav

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 genes”.
  3. Add the next track the same way. This one needs a BigWig file (.bw).This figure uses “pggb graph: pangenome depth (paths over K12)”.
    1. Track menu → Y axis... → Reference linesHorizontal lines at 5 and 1, on the same scale as the plot. Each row takes a value, a label and a color; removing every row removes every line.
  4. Add the next track the same way.This figure uses “pggb graph: per-strain presence (odgi pav, vs K12)”.
    1. Track menu → Plot type → Density
  5. Type your region of interest into the location box and press Enter.This figure is at chr:450,000-590,000.
  6. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:450,000-590,000",
      "highlight": [
        {
          "refName": "chr",
          "start": 501500,
          "end": 539000,
          "color": "rgba(255,193,7,0.30)"
        }
      ],
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "height": 90
        },
        {
          "trackId": "ecoli_pggb_depth",
          "type": "LinearWiggleDisplay",
          "height": 150,
          "scales": {
            "y": {
              "title": "paths",
              "rules": [
                {
                  "value": 5,
                  "label": "all five strains"
                },
                {
                  "value": 1,
                  "label": "K12 alone"
                }
              ]
            }
          }
        },
        {
          "trackId": "ecoli_pggb_pav",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "height": 240
        }
      ]
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "K12",
            "loc": "chr:450,000-590,000",
            "highlight": [
                {
                    "refName": "chr",
                    "start": 501500,
                    "end": 539000,
                    "color": "rgba(255,193,7,0.30)"
                }
            ],
            "tracks": [
                {
                    "trackId": "K12_genes",
                    "type": "LinearBasicDisplay",
                    "height": 90
                },
                {
                    "trackId": "ecoli_pggb_depth",
                    "type": "LinearWiggleDisplay",
                    "height": 150,
                    "scales": {
                        "y": {
                            "title": "paths",
                            "rules": [
                                {
                                    "value": 5,
                                    "label": "all five strains"
                                },
                                {
                                    "value": 1,
                                    "label": "K12 alone"
                                }
                            ]
                        }
                    }
                },
                {
                    "trackId": "ecoli_pggb_pav",
                    "type": "LinearWiggleDisplay",
                    "mark": "span",
                    "height": 240
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --assembly K12 --loc chr:450,000-590,000 \
  --track K12_genes display:LinearBasicDisplay '{"height":90}' \
  --track ecoli_pggb_depth display:LinearWiggleDisplay '{"height":150,"scales":{"y":{"title":"paths","rules":[{"value":5,"label":"all five strains"},{"value":1,"label":"K12 alone"}]}}}' \
  --track ecoli_pggb_pav display:LinearWiggleDisplay '{"mark":"span","height":240}' \
  --width 1000 --out figure.svg

It has no flag for this figure's highlight, so its picture can differ there.

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

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:450,000-590,000",
      "highlight": [
        {
          "refName": "chr",
          "start": 501500,
          "end": 539000,
          "color": "rgba(255,193,7,0.30)"
        }
      ],
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "height": 90
        },
        {
          "trackId": "ecoli_pggb_depth",
          "type": "LinearWiggleDisplay",
          "height": 150,
          "scales": {
            "y": {
              "title": "paths",
              "rules": [
                {
                  "value": 5,
                  "label": "all five strains"
                },
                {
                  "value": 1,
                  "label": "K12 alone"
                }
              ]
            }
          }
        },
        {
          "trackId": "ecoli_pggb_pav",
          "type": "LinearWiggleDisplay",
          "mark": "span",
          "height": 240
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 775 \
  --timeout 90000 \
  --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.

Testing the CPZ-55 depth trough with nanopore reads

We'll check the depth trough at CPZ-55, a cryptic prophage found in K12 alone, with nanopore reads from E. coli E146, an isolate outside the graph. Download them:

curl -fO https://ftp.sra.ebi.ac.uk/vol1/fastq/DRR193/DRR193901/DRR193901_1.fastq.gz

Map them onto K12:

minimap2 -ax map-ont K12.fa DRR193901_1.fastq.gz | samtools sort -o ecoli_e146_ont.bam
samtools index ecoli_e146_ont.bam

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

{
  "trackId": "ecoli_e146_ont",
  "name": "E146 nanopore reads (vs K12)",
  "uri": "ecoli_e146_ont.bam",
  "assemblyNames": ["K12"]
}
jbrowse add-track ecoli_e146_ont.bam \
  --trackId ecoli_e146_ont \
  --name "E146 nanopore reads (vs K12)" \
  --assemblyNames K12 \
  --load copy

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track... and, in Add a track from file or URL, enter:

  • Main file: ecoli_e146_ont.bam

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: E146 nanopore reads (vs K12)
  • Assembly: K12

Click Add.

ecoli_e146_ont.bam is relative to a config.json. Replace it with its URL or its path on this computer.

Type chr:2,554,000-2,570,000. Reads long enough to cross the trough show it as a single labelled deletion.

Nanopore reads from an unrelated E. coli isolate over one K12 depth trough, with the graph's depth curve and its MAF below. The reads, the depth curve and the MAF rows all break at the edges of the cryptic prophage CPZ-55.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%2Fecoli_pangenome%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A2%2C554%2C000-2%2C570%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%7D%2C%7B%22trackId%22%3A%22ecoli_e146_ont%22%2C%22type%22%3A%22LinearAlignmentsDisplay%22%2C%22unit%22%3A%22chain%22%2C%22facet%22%3A%22split%22%2C%22color%22%3A%7B%22field%22%3A%22pairOrientation%22%7D%2C%22height%22%3A210%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_depth%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22height%22%3A100%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_maf%22%2C%22type%22%3A%22LinearMafDisplay%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Flong_reads

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

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 genes”.
  3. Add the next track the same way. This one needs a BAM file (.bam + .bai).This figure uses “E146 nanopore reads (vs K12)”.
    1. Track menu → Read connections → View as pairs / link supplementary alignments (checked)
    2. Track menu → Group by... → Split read (SA tag)
    3. Track menu → Color by... → Paired end → Pair orientation
  4. Add the next track the same way. This one needs a BigWig file (.bw).This figure uses “pggb graph: pangenome depth (paths over K12)”.
  5. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed MAF (.maf.gz + .tbi).This figure uses “pggb graph: whole-genome alignment (MAF, vs K12)”.
  6. Type your region of interest into the location box and press Enter.This figure is at chr:2,554,000-2,570,000.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:2,554,000-2,570,000",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay"
        },
        {
          "trackId": "ecoli_e146_ont",
          "type": "LinearAlignmentsDisplay",
          "unit": "chain",
          "facet": "split",
          "color": {
            "field": "pairOrientation"
          },
          "height": 210
        },
        {
          "trackId": "ecoli_pggb_depth",
          "type": "LinearWiggleDisplay",
          "height": 100
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay"
        }
      ]
    }
  ]
}

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/ecoli_pangenome/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "K12",
            "loc": "chr:2,554,000-2,570,000",
            "tracks": [
                {
                    "trackId": "K12_genes",
                    "type": "LinearBasicDisplay"
                },
                {
                    "trackId": "ecoli_e146_ont",
                    "type": "LinearAlignmentsDisplay",
                    "unit": "chain",
                    "facet": "split",
                    "color": {
                        "field": "pairOrientation"
                    },
                    "height": 210
                },
                {
                    "trackId": "ecoli_pggb_depth",
                    "type": "LinearWiggleDisplay",
                    "height": 100
                },
                {
                    "trackId": "ecoli_pggb_maf",
                    "type": "LinearMafDisplay"
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --assembly K12 --loc chr:2,554,000-2,570,000 \
  --track K12_genes display:LinearBasicDisplay \
  --track ecoli_e146_ont display:LinearAlignmentsDisplay '{"unit":"chain","facet":"split","color":{"field":"pairOrientation"},"height":210}' \
  --track ecoli_pggb_depth display:LinearWiggleDisplay '{"height":100}' \
  --track ecoli_pggb_maf display:LinearMafDisplay \
  --width 1000 --out figure.svg

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

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

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:2,554,000-2,570,000",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay"
        },
        {
          "trackId": "ecoli_e146_ont",
          "type": "LinearAlignmentsDisplay",
          "unit": "chain",
          "facet": "split",
          "color": {
            "field": "pairOrientation"
          },
          "height": 210
        },
        {
          "trackId": "ecoli_pggb_depth",
          "type": "LinearWiggleDisplay",
          "height": 100
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay"
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/demos/ecoli_pangenome/config.json \
  --width 1000 --height 865 \
  --timeout 120000 \
  --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.

The graph as a track

The graph genome view plugin draws the graph itself as a track of the linear view. gfa-to-tabix build indexes it by following the K12 path, and takes the bubbles from pggb's undecomposed VCF, renamed like the decomposed one:

in_pggb bash -c "bcftools annotate --rename-chrs /data/rename_chrs.tsv \
  /data/pggb/*.smooth.final.K12.vcf \
  | bcftools sort -Oz -o /data/ecoli_pggb_snarls.vcf.gz && tabix -p vcf /data/ecoli_pggb_snarls.vcf.gz"
cargo install gfa-to-tabix
gfa-to-tabix build pggb/*.smooth.final.gfa -o ecoli_pggb --reference K12 --snarls ecoli_pggb_snarls.vcf.gz

The command writes the segments and links, a coarse tier with variants under 50 bp folded into the reference, and ecoli_pggb.config.json. The uris below are our hosted copy; a local build uses ecoli_pggb:

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

{
  "type": "GraphTrack",
  "trackId": "ecoli_pggb_segments",
  "name": "pggb graph segments (whole graph, by locus)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
    "coarse": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
      "aboveBpPerPx": 5
    }
  },
  "displayDefaults": { "showLabels": "none" },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}
jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "ecoli_pggb_segments",
  "name": "pggb graph segments (whole graph, by locus)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
    "coarse": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
      "aboveBpPerPx": 5
    }
  },
  "displayDefaults": { "showLabels": "none" },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}'

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": "GraphTrack",
  "trackId": "ecoli_pggb_segments",
  "name": "pggb graph segments (whole graph, by locus)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
    "coarse": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
      "aboveBpPerPx": 5
    }
  },
  "displayDefaults": { "showLabels": "none" },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}

Open track... → Add pangenome graph track adds the same track from an empty session:

A K12 session with no graph in it, to a graph track: the track added through Open track... → Add pangenome graph track, the window narrowed onto the IS5 element, and the track drawing the graph on K12's coordinates.

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

  1. Load the graph by URL from File, Open track
  2. The graph draws under the genes, cut from the window on screen
  3. Select the IS5 element on the scale bar and zoom to it
  4. At IS5 the graph re-cuts: strains without the element take the arc past it

Open this view in JBrowse Web ↗ · Open this view in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22K12_genes%22%2C%22name%22%3A%22K12+genes%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22Gff3TabixAdapter%22%2C%22gffGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz%22%7D%2C%22index%22%3A%7B%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz.tbi%22%7D%7D%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A1%2C290%2C000-1%2C310%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A70%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_subgraph_launch

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 genes”.
  3. Type your region of interest into the location box and press Enter.This figure is at chr:1,290,000-1,310,000.

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": "FeatureTrack",
  "trackId": "K12_genes",
  "name": "K12 genes",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
    },
    "index": {
      "location": {
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
      }
    }
  }
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs K12 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/code/jb2/main/test_data/graphgenomeview/config.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "K12_genes",
      "name": "K12 genes",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,290,000-1,310,000",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "height": 70
        }
      ]
    }
  ]
}

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/code/jb2/main/test_data/graphgenomeview/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "type": "FeatureTrack",
            "trackId": "K12_genes",
            "name": "K12 genes",
            "assemblyNames": [
                "K12"
            ],
            "adapter": {
                "type": "Gff3TabixAdapter",
                "gffGzLocation": {
                    "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
                },
                "index": {
                    "location": {
                        "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
                    }
                }
            }
        }
    ],
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "K12",
            "loc": "chr:1,290,000-1,310,000",
            "tracks": [
                {
                    "trackId": "K12_genes",
                    "type": "LinearBasicDisplay",
                    "height": 70
                }
            ]
        }
    ],
)
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": "FeatureTrack",
    "trackId": "K12_genes",
    "name": "K12 genes",
    "assemblyNames": [
      "K12"
    ],
    "adapter": {
      "type": "Gff3TabixAdapter",
      "gffGzLocation": {
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
      },
      "index": {
        "location": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
        }
      }
    }
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/config.json \
  --tracks tracks.json \
  --assembly K12 --loc chr:1,290,000-1,310,000 \
  --track K12_genes display:LinearBasicDisplay '{"height":70}' \
  --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'
{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "K12_genes",
      "name": "K12 genes",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,290,000-1,310,000",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "height": 70
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/config.json \
  --width 1920 --height 780 \
  --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.

Type chr:1,292,500-1,307,500. Zoomed out past five bp per pixel, the track draws the coarse tier, the graph with variants under 50 bp folded into the reference, with charcoal where the strains differ. The tier also loads as a separate track:

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

{
  "type": "GraphTrack",
  "trackId": "ecoli_pggb_tier50",
  "name": "pggb graph, variants under 50 bp folded (coarse tier)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50"
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}
jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "ecoli_pggb_tier50",
  "name": "pggb graph, variants under 50 bp folded (coarse tier)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50"
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}'

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": "GraphTrack",
  "trackId": "ecoli_pggb_tier50",
  "name": "pggb graph, variants under 50 bp folded (coarse tier)",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50"
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}

In the tier track's menu, Display types → Feature display draws the tier's segments as a row at any zoom. The tier marks where the strains differ, and between the tier and the graph the MAF track shows which strain, since its row breaks across each bubble it skips.

K12 around two insertion sequences, variants under 50 bp folded: the tier, the MAF's strain rows, and the graph track, which draws from the tier at this zoom. The highlight and boxed node are the IS5 element insH21, which all four other strains skip, their MAF rows breaking across it; NCTC86's row runs through insZ to its left.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22K12_genes%22%2C%22name%22%3A%22K12+genes%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22Gff3TabixAdapter%22%2C%22gffGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz%22%7D%2C%22index%22%3A%7B%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz.tbi%22%7D%7D%7D%7D%2C%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22K12_insertion_sequences%22%2C%22name%22%3A%22K12+insertion+sequences%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22Gff3TabixAdapter%22%2C%22gffGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz%22%7D%2C%22index%22%3A%7B%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz.tbi%22%7D%7D%7D%7D%2C%7B%22type%22%3A%22GraphTrack%22%2C%22trackId%22%3A%22ecoli_pggb_tier50%22%2C%22name%22%3A%22pggb+graph%2C+variants+under+50+bp+folded+%28coarse+tier%29%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22RgfaTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb.fold50%22%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearGraphDisplay%22%7D%2C%7B%22type%22%3A%22LinearBasicDisplay%22%7D%5D%7D%2C%7B%22type%22%3A%22MafTrack%22%2C%22trackId%22%3A%22ecoli_pggb_maf%22%2C%22name%22%3A%22pggb+graph%3A+whole-genome+alignment+%28MAF%2C+vs+K12%29%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22MafTabixAdapter%22%2C%22samples%22%3A%5B%22K12%22%2C%22Sakai%22%2C%22CFT073%22%2C%22NCTC86%22%2C%22IAI39%22%5D%2C%22nhLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb.nh%22%7D%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb.maf.bed.gz%22%7D%7D%2C%7B%22type%22%3A%22GraphTrack%22%2C%22trackId%22%3A%22ecoli_pggb_segments%22%2C%22name%22%3A%22pggb+graph+segments+%28whole+graph%2C+by+locus%29%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22RgfaTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb%22%2C%22coarse%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb.fold50%22%2C%22aboveBpPerPx%22%3A5%7D%7D%2C%22displayDefaults%22%3A%7B%22showLabels%22%3A%22none%22%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearGraphDisplay%22%7D%2C%7B%22type%22%3A%22LinearBasicDisplay%22%7D%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A1%2C292%2C500-1%2C307%2C500%22%2C%22highlight%22%3A%5B%7B%22assemblyName%22%3A%22K12%22%2C%22refName%22%3A%22chr%22%2C%22start%22%3A1299498%2C%22end%22%3A1300697%2C%22color%22%3A%22rgba%2821%2C101%2C192%2C0.12%29%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_insertion_sequences%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22filter%22%3A%5B%22jexl%3AstartsWith%28get%28feature%2C%27name%27%29+%7C%7C+%27%27%2C%27ins%27%29%22%5D%2C%22height%22%3A50%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_tier50%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22showLabels%22%3A%22none%22%2C%22height%22%3A50%2C%22color%22%3A%22jexl%3Aget%28feature%2C%27rank%27%29%3E0+%3F+%27rgb%2860%2C65%2C72%29%27+%3A+%27hsl%28%27+%2B+min%28300%2C+max%280%2C+%28%28get%28feature%2C%27start%27%29%2Bget%28feature%2C%27end%27%29%29%2F2+-+1292500%29+%2F+15000+*+300%29%29+%2B+%27%2C70%25%2C50%25%29%27%22%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_maf%22%2C%22type%22%3A%22LinearMafDisplay%22%2C%22rows%22%3A%7B%22domain%22%3A%5B%22K12%22%2C%22CFT073%22%2C%22IAI39%22%2C%22NCTC86%22%2C%22Sakai%22%5D%7D%2C%22showCoverage%22%3Afalse%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22color%22%3A%7B%22field%22%3A%22position%22%2C%22domainMin%22%3A1292500%2C%22domainMax%22%3A1307500%7D%2C%22geneTrackId%22%3A%22K12_genes%22%2C%22height%22%3A190%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_bubble_tier

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

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 insertion sequences”.
    1. Track menu → Filter by... → add the expressionThis figure filters on startsWith(get(feature,'name') || '','ins').
  3. Add the next track the same way.This figure uses “pggb graph, variants under 50 bp folded (coarse tier)”.
    1. Track menu → Show... → Labels → None
    2. Track menu → Settings → colorA per-feature expression. The Color by... radios write a solid color, a field's palette, and the strand colors only, so an expression is authored on the track config.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed MAF (.maf.gz + .tbi).This figure uses “pggb graph: whole-genome alignment (MAF, vs K12)”.
    1. Track menu → Edit colors/arrangement... → drag the rows into orderThe same dialog renames a row and recolors it, so a figure's 5 rows carry their order, any labels it shows, and any color it picked.
    2. Track menu → Show... → Show coverage (unchecked)
  5. Add the next track the same way.This figure uses “pggb graph segments (whole graph, by locus)”.
  6. Type your region of interest into the location box and press Enter.This figure is at chr:1,292,500-1,307,500.
  7. View menu → Zoom to region / use the location box, then add a highlightThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

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": "FeatureTrack",
  "trackId": "K12_genes",
  "name": "K12 genes",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
    },
    "index": {
      "location": {
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
      }
    }
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "K12_insertion_sequences",
  "name": "K12 insertion sequences",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
    },
    "index": {
      "location": {
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
      }
    }
  }
}'

jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "ecoli_pggb_tier50",
  "name": "pggb graph, variants under 50 bp folded (coarse tier)",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50"
  },
  "displays": [
    {
      "type": "LinearGraphDisplay"
    },
    {
      "type": "LinearBasicDisplay"
    }
  ]
}'

jbrowse add-track-json '{
  "type": "MafTrack",
  "trackId": "ecoli_pggb_maf",
  "name": "pggb graph: whole-genome alignment (MAF, vs K12)",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "MafTabixAdapter",
    "samples": [
      "K12",
      "Sakai",
      "CFT073",
      "NCTC86",
      "IAI39"
    ],
    "nhLocation": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.nh"
    },
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.maf.bed.gz"
  }
}'

jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "ecoli_pggb_segments",
  "name": "pggb graph segments (whole graph, by locus)",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
    "coarse": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
      "aboveBpPerPx": 5
    }
  },
  "displayDefaults": {
    "showLabels": "none"
  },
  "displays": [
    {
      "type": "LinearGraphDisplay"
    },
    {
      "type": "LinearBasicDisplay"
    }
  ]
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs K12 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/code/jb2/main/test_data/graphgenomeview/config.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "K12_genes",
      "name": "K12 genes",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    },
    {
      "type": "FeatureTrack",
      "trackId": "K12_insertion_sequences",
      "name": "K12 insertion sequences",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    },
    {
      "type": "GraphTrack",
      "trackId": "ecoli_pggb_tier50",
      "name": "pggb graph, variants under 50 bp folded (coarse tier)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50"
      },
      "displays": [
        {
          "type": "LinearGraphDisplay"
        },
        {
          "type": "LinearBasicDisplay"
        }
      ]
    },
    {
      "type": "MafTrack",
      "trackId": "ecoli_pggb_maf",
      "name": "pggb graph: whole-genome alignment (MAF, vs K12)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "MafTabixAdapter",
        "samples": [
          "K12",
          "Sakai",
          "CFT073",
          "NCTC86",
          "IAI39"
        ],
        "nhLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.nh"
        },
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.maf.bed.gz"
      }
    },
    {
      "type": "GraphTrack",
      "trackId": "ecoli_pggb_segments",
      "name": "pggb graph segments (whole graph, by locus)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
        "coarse": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
          "aboveBpPerPx": 5
        }
      },
      "displayDefaults": {
        "showLabels": "none"
      },
      "displays": [
        {
          "type": "LinearGraphDisplay"
        },
        {
          "type": "LinearBasicDisplay"
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,292,500-1,307,500",
      "highlight": [
        {
          "assemblyName": "K12",
          "refName": "chr",
          "start": 1299498,
          "end": 1300697,
          "color": "rgba(21,101,192,0.12)"
        }
      ],
      "tracks": [
        {
          "trackId": "K12_insertion_sequences",
          "type": "LinearBasicDisplay",
          "filter": [
            "jexl:startsWith(get(feature,'name') || '','ins')"
          ],
          "height": 50
        },
        {
          "trackId": "ecoli_pggb_tier50",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 50,
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 1292500) / 15000 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay",
          "rows": {
            "domain": [
              "K12",
              "CFT073",
              "IAI39",
              "NCTC86",
              "Sakai"
            ]
          },
          "showCoverage": false,
          "height": 110
        },
        {
          "trackId": "ecoli_pggb_segments",
          "type": "LinearGraphDisplay",
          "color": {
            "field": "position",
            "domainMin": 1292500,
            "domainMax": 1307500
          },
          "geneTrackId": "K12_genes",
          "height": 190
        }
      ]
    }
  ]
}

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": "FeatureTrack",
      "trackId": "K12_genes",
      "name": "K12 genes",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    },
    {
      "type": "FeatureTrack",
      "trackId": "K12_insertion_sequences",
      "name": "K12 insertion sequences",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    },
    {
      "type": "GraphTrack",
      "trackId": "ecoli_pggb_tier50",
      "name": "pggb graph, variants under 50 bp folded (coarse tier)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50"
      },
      "displays": [
        {
          "type": "LinearGraphDisplay"
        },
        {
          "type": "LinearBasicDisplay"
        }
      ]
    },
    {
      "type": "MafTrack",
      "trackId": "ecoli_pggb_maf",
      "name": "pggb graph: whole-genome alignment (MAF, vs K12)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "MafTabixAdapter",
        "samples": [
          "K12",
          "Sakai",
          "CFT073",
          "NCTC86",
          "IAI39"
        ],
        "nhLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.nh"
        },
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.maf.bed.gz"
      }
    },
    {
      "type": "GraphTrack",
      "trackId": "ecoli_pggb_segments",
      "name": "pggb graph segments (whole graph, by locus)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
        "coarse": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
          "aboveBpPerPx": 5
        }
      },
      "displayDefaults": {
        "showLabels": "none"
      },
      "displays": [
        {
          "type": "LinearGraphDisplay"
        },
        {
          "type": "LinearBasicDisplay"
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,292,500-1,307,500",
      "highlight": [
        {
          "assemblyName": "K12",
          "refName": "chr",
          "start": 1299498,
          "end": 1300697,
          "color": "rgba(21,101,192,0.12)"
        }
      ],
      "tracks": [
        {
          "trackId": "K12_insertion_sequences",
          "type": "LinearBasicDisplay",
          "filter": [
            "jexl:startsWith(get(feature,'name') || '','ins')"
          ],
          "height": 50
        },
        {
          "trackId": "ecoli_pggb_tier50",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 50,
          "color": "jexl:get(feature,'rank')>0 ? 'rgb(60,65,72)' : 'hsl(' + min(300, max(0, ((get(feature,'start')+get(feature,'end'))/2 - 1292500) / 15000 * 300)) + ',70%,50%)'"
        },
        {
          "trackId": "ecoli_pggb_maf",
          "type": "LinearMafDisplay",
          "rows": {
            "domain": [
              "K12",
              "CFT073",
              "IAI39",
              "NCTC86",
              "Sakai"
            ]
          },
          "showCoverage": false,
          "height": 110
        },
        {
          "trackId": "ecoli_pggb_segments",
          "type": "LinearGraphDisplay",
          "color": {
            "field": "position",
            "domainMin": 1292500,
            "domainMax": 1307500
          },
          "geneTrackId": "K12_genes",
          "height": 190
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "box",
    "color": "#1565c0",
    "strokeWidth": 3,
    "pad": 8,
    "anchor": {
      "graphNode": "160195"
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/config.json \
  --width 1000 --height 730 \
  --timeout 120000 \
  --spec session.json --annotations callouts.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.

Right-click the IS5 node in the graph track and take Open in K12, the route the HPRC page describes for a haplotype. A segment K12 lacks has coordinates on the strain that has it, so type chr:1,004,500-1,004,961, right-click the 75 bp CFT073 segment and pick Open in CFT073.

The node's menu opened on the CFT073 allele, under the K12 genes it bypasses, and the view its Open in entry adds: CFT073 in CFT073 coordinates, where ssuE runs straight into pyrD.

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

  1. Right-click the CFT073 allele and open it on CFT073
  2. On CFT073, ssuE runs into pyrD: the genes K-12 has between them are gone

Open this view in JBrowse Web ↗ · Open this view in JBrowse Desktop ↗

Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fecoli_pangenome.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22GraphTrack%22%2C%22trackId%22%3A%22ecoli_pggb_segments%22%2C%22name%22%3A%22pggb+graph+segments+%28whole+graph%2C+by+locus%29%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22RgfaTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb%22%2C%22coarse%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb.fold50%22%2C%22aboveBpPerPx%22%3A5%7D%7D%2C%22displayDefaults%22%3A%7B%22showLabels%22%3A%22none%22%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearGraphDisplay%22%7D%2C%7B%22type%22%3A%22LinearBasicDisplay%22%7D%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A996%2C800-1%2C005%2C900%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%7D%5D%7D%2C%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A1%2C004%2C500-1%2C004%2C961%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22ecoli_pggb_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22force%22%2C%22color%22%3A%7B%22field%22%3A%22rank%22%7D%2C%22maxRegionBp%22%3A508%2C%22layers%22%3A%7B%22bubbles%22%3Afalse%7D%2C%22height%22%3A420%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_out_to_strain

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 pane 1: Add → Linear genome view.
    1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
    2. 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 “K12 genes”.
    3. Type your region of interest into the location box and press Enter.This figure is at chr:996,800-1,005,900.
  2. Open pane 2: Add → Linear genome view.
    1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
    2. 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 figure uses “pggb graph segments (whole graph, by locus)”.
      1. Track menu → Layout → Force-directed
    3. Type your region of interest into the location box and press Enter.This figure is at chr:1,004,500-1,004,961.

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

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": "GraphTrack",
  "trackId": "ecoli_pggb_segments",
  "name": "pggb graph segments (whole graph, by locus)",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
    "coarse": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
      "aboveBpPerPx": 5
    }
  },
  "displayDefaults": {
    "showLabels": "none"
  },
  "displays": [
    {
      "type": "LinearGraphDisplay"
    },
    {
      "type": "LinearBasicDisplay"
    }
  ]
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs K12 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/code/jb2/main/test_data/graphgenomeview/ecoli_pangenome.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "GraphTrack",
      "trackId": "ecoli_pggb_segments",
      "name": "pggb graph segments (whole graph, by locus)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
        "coarse": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
          "aboveBpPerPx": 5
        }
      },
      "displayDefaults": {
        "showLabels": "none"
      },
      "displays": [
        {
          "type": "LinearGraphDisplay"
        },
        {
          "type": "LinearBasicDisplay"
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:996,800-1,005,900",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay"
        }
      ]
    },
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,004,500-1,004,961",
      "tracks": [
        {
          "trackId": "ecoli_pggb_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "color": {
            "field": "rank"
          },
          "maxRegionBp": 508,
          "layers": {
            "bubbles": false
          },
          "height": 420
        }
      ]
    }
  ]
}

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": "GraphTrack",
      "trackId": "ecoli_pggb_segments",
      "name": "pggb graph segments (whole graph, by locus)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb",
        "coarse": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.fold50",
          "aboveBpPerPx": 5
        }
      },
      "displayDefaults": {
        "showLabels": "none"
      },
      "displays": [
        {
          "type": "LinearGraphDisplay"
        },
        {
          "type": "LinearBasicDisplay"
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:996,800-1,005,900",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay"
        }
      ]
    },
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,004,500-1,004,961",
      "tracks": [
        {
          "trackId": "ecoli_pggb_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "color": {
            "field": "rank"
          },
          "maxRegionBp": 508,
          "layers": {
            "bubbles": false
          },
          "height": 420
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/ecoli_pangenome.json \
  --width 1920 --height 1290 \
  --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 each segment by how many strains have it

The index records which strains pass through each segment, and a feature track over the same files colors each segment by that count:

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

{
  "type": "FeatureTrack",
  "trackId": "ecoli_pggb_carriage",
  "name": "pggb graph: strains per segment",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb"
  },
  "displayDefaults": {
    "displayMode": "collapsed",
    "showLabels": "none",
    "color": {
      "field": "sampleCount",
      "domain": ["5", "4", "3", "2", "1"],
      "range": ["#bdbdbd", "#fed976", "#feb24c", "#fd8d3c", "#e31a1c"],
      "labels": [
        "All 5 strains (core)",
        "4 strains",
        "3 strains",
        "2 strains",
        "1 strain (private)"
      ],
      "title": "Strains"
    }
  }
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "ecoli_pggb_carriage",
  "name": "pggb graph: strains per segment",
  "assemblyNames": ["K12"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb"
  },
  "displayDefaults": {
    "displayMode": "collapsed",
    "showLabels": "none",
    "color": {
      "field": "sampleCount",
      "domain": ["5", "4", "3", "2", "1"],
      "range": ["#bdbdbd", "#fed976", "#feb24c", "#fd8d3c", "#e31a1c"],
      "labels": [
        "All 5 strains (core)",
        "4 strains",
        "3 strains",
        "2 strains",
        "1 strain (private)"
      ],
      "title": "Strains"
    }
  }
}'

In JBrowse Desktop, or in any running JBrowse Web session, open a view on this track’s assembly, then File → Open track..., choose Add pangenome graph track, and fill in:

  • File type: rGFA segments (tabix BED pair)
  • Path: https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb.segs.bed.gz
  • Track name: pggb graph: strains per segment
  • Assembly: K12

Type chr:1,299,499-1,300,693, the IS5 element. Advanced → Edit plot... in the track menu shows the color block as text and applies edits live.

The IS5 element in K12: the windowed depth curve, and under it the strains-per-segment track, colored by how many strains have each segment, so the red box is a segment K12 alone has.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fgraphgenomeview%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22K12_genes%22%2C%22name%22%3A%22K12+genes%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22Gff3TabixAdapter%22%2C%22gffGzLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz%22%7D%2C%22index%22%3A%7B%22location%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2FK12.gff.gz.tbi%22%7D%7D%7D%7D%2C%7B%22type%22%3A%22QuantitativeTrack%22%2C%22trackId%22%3A%22ecoli_pggb_depth%22%2C%22name%22%3A%22pggb+graph%3A+pangenome+depth+%28paths+over+K12%29%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22BigWigAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb_depth.bw%22%7D%2C%22displayDefaults%22%3A%7B%22scales%22%3A%7B%22y%22%3A%7B%22title%22%3A%22paths%22%2C%22rules%22%3A%5B%7B%22value%22%3A5%2C%22label%22%3A%22all+five+strains%22%7D%2C%7B%22value%22%3A1%2C%22label%22%3A%22K12+alone%22%7D%5D%7D%7D%7D%7D%2C%7B%22type%22%3A%22FeatureTrack%22%2C%22trackId%22%3A%22ecoli_pggb_carriage%22%2C%22name%22%3A%22pggb+graph%3A+strains+per+segment%22%2C%22assemblyNames%22%3A%5B%22K12%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22RgfaTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fecoli_pangenome%2Fecoli_pggb%22%7D%2C%22displayDefaults%22%3A%7B%22displayMode%22%3A%22collapsed%22%2C%22showLabels%22%3A%22none%22%2C%22color%22%3A%7B%22field%22%3A%22sampleCount%22%2C%22domain%22%3A%5B%225%22%2C%224%22%2C%223%22%2C%222%22%2C%221%22%5D%2C%22range%22%3A%5B%22%23bdbdbd%22%2C%22%23fed976%22%2C%22%23feb24c%22%2C%22%23fd8d3c%22%2C%22%23e31a1c%22%5D%2C%22labels%22%3A%5B%22All+5+strains+%28core%29%22%2C%224+strains%22%2C%223+strains%22%2C%222+strains%22%2C%221+strain+%28private%29%22%5D%2C%22title%22%3A%22Strains%22%7D%7D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22K12%22%2C%22loc%22%3A%22chr%3A1%2C299%2C300-1%2C300%2C900%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22K12_genes%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A70%2C%22filter%22%3A%5B%22jexl%3Afeature.type%3D%3D%27gene%27%22%5D%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_depth%22%2C%22type%22%3A%22LinearWiggleDisplay%22%2C%22height%22%3A100%7D%2C%7B%22trackId%22%3A%22ecoli_pggb_carriage%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A150%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fpggb_carriage_lane

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

Or rebuild it from your own data:

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

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

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one). For JBrowse Web, jbrowse add-assembly puts it in your config.json.This figure uses K12, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  2. Add a track: check one your config has in the track selector, or File → Open track... to paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “K12 genes”.
    1. Track menu → Filter by... → add the expressionThis figure filters on feature.type=='gene'.
  3. Add the next track the same way. This one needs a BigWig file (.bw).This figure uses “pggb graph: pangenome depth (paths over K12)”.
  4. Add the next track the same way.This figure uses “pggb graph: strains per segment”.
  5. Type your region of interest into the location box and press Enter.This figure is at chr:1,299,300-1,300,900.

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": "FeatureTrack",
  "trackId": "K12_genes",
  "name": "K12 genes",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "gffGzLocation": {
      "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
    },
    "index": {
      "location": {
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
      }
    }
  }
}'

jbrowse add-track https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb_depth.bw \
  --trackId ecoli_pggb_depth \
  --name "pggb graph: pangenome depth (paths over K12)" \
  --assemblyNames K12 \
  --displayDefaults '{"scales":{"y":{"title":"paths","rules":[{"value":5,"label":"all five strains"},{"value":1,"label":"K12 alone"}]}}}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "ecoli_pggb_carriage",
  "name": "pggb graph: strains per segment",
  "assemblyNames": [
    "K12"
  ],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb"
  },
  "displayDefaults": {
    "displayMode": "collapsed",
    "showLabels": "none",
    "color": {
      "field": "sampleCount",
      "domain": [
        "5",
        "4",
        "3",
        "2",
        "1"
      ],
      "range": [
        "#bdbdbd",
        "#fed976",
        "#feb24c",
        "#fd8d3c",
        "#e31a1c"
      ],
      "labels": [
        "All 5 strains (core)",
        "4 strains",
        "3 strains",
        "2 strains",
        "1 strain (private)"
      ],
      "title": "Strains"
    }
  }
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs K12 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/code/jb2/main/test_data/graphgenomeview/config.json, which is what the Web button above opens.

{
  "sessionTracks": [
    {
      "type": "FeatureTrack",
      "trackId": "K12_genes",
      "name": "K12 genes",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    },
    {
      "type": "QuantitativeTrack",
      "trackId": "ecoli_pggb_depth",
      "name": "pggb graph: pangenome depth (paths over K12)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "BigWigAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb_depth.bw"
      },
      "displayDefaults": {
        "scales": {
          "y": {
            "title": "paths",
            "rules": [
              {
                "value": 5,
                "label": "all five strains"
              },
              {
                "value": 1,
                "label": "K12 alone"
              }
            ]
          }
        }
      }
    },
    {
      "type": "FeatureTrack",
      "trackId": "ecoli_pggb_carriage",
      "name": "pggb graph: strains per segment",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb"
      },
      "displayDefaults": {
        "displayMode": "collapsed",
        "showLabels": "none",
        "color": {
          "field": "sampleCount",
          "domain": [
            "5",
            "4",
            "3",
            "2",
            "1"
          ],
          "range": [
            "#bdbdbd",
            "#fed976",
            "#feb24c",
            "#fd8d3c",
            "#e31a1c"
          ],
          "labels": [
            "All 5 strains (core)",
            "4 strains",
            "3 strains",
            "2 strains",
            "1 strain (private)"
          ],
          "title": "Strains"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,299,300-1,300,900",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "height": 70,
          "filter": [
            "jexl:feature.type=='gene'"
          ]
        },
        {
          "trackId": "ecoli_pggb_depth",
          "type": "LinearWiggleDisplay",
          "height": 100
        },
        {
          "trackId": "ecoli_pggb_carriage",
          "type": "LinearBasicDisplay",
          "height": 150
        }
      ]
    }
  ]
}

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": "FeatureTrack",
      "trackId": "K12_genes",
      "name": "K12 genes",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "Gff3TabixAdapter",
        "gffGzLocation": {
          "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz"
        },
        "index": {
          "location": {
            "uri": "https://jbrowse.org/demos/ecoli_pangenome/K12.gff.gz.tbi"
          }
        }
      }
    },
    {
      "type": "QuantitativeTrack",
      "trackId": "ecoli_pggb_depth",
      "name": "pggb graph: pangenome depth (paths over K12)",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "BigWigAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb_depth.bw"
      },
      "displayDefaults": {
        "scales": {
          "y": {
            "title": "paths",
            "rules": [
              {
                "value": 5,
                "label": "all five strains"
              },
              {
                "value": 1,
                "label": "K12 alone"
              }
            ]
          }
        }
      }
    },
    {
      "type": "FeatureTrack",
      "trackId": "ecoli_pggb_carriage",
      "name": "pggb graph: strains per segment",
      "assemblyNames": [
        "K12"
      ],
      "adapter": {
        "type": "RgfaTabixAdapter",
        "uri": "https://jbrowse.org/demos/ecoli_pangenome/ecoli_pggb"
      },
      "displayDefaults": {
        "displayMode": "collapsed",
        "showLabels": "none",
        "color": {
          "field": "sampleCount",
          "domain": [
            "5",
            "4",
            "3",
            "2",
            "1"
          ],
          "range": [
            "#bdbdbd",
            "#fed976",
            "#feb24c",
            "#fd8d3c",
            "#e31a1c"
          ],
          "labels": [
            "All 5 strains (core)",
            "4 strains",
            "3 strains",
            "2 strains",
            "1 strain (private)"
          ],
          "title": "Strains"
        }
      }
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "K12",
      "loc": "chr:1,299,300-1,300,900",
      "tracks": [
        {
          "trackId": "K12_genes",
          "type": "LinearBasicDisplay",
          "height": 70,
          "filter": [
            "jexl:feature.type=='gene'"
          ]
        },
        {
          "trackId": "ecoli_pggb_depth",
          "type": "LinearWiggleDisplay",
          "height": 100
        },
        {
          "trackId": "ecoli_pggb_carriage",
          "type": "LinearBasicDisplay",
          "height": 150
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "odgi depth, windowed",
    "fontSize": 15,
    "anchor": {
      "trackId": "ecoli_pggb_depth",
      "loc": "chr:1,300,000",
      "fracY": 0.3
    }
  },
  {
    "type": "text",
    "text": "GFA SM:Z: tag, per segment",
    "fontSize": 15,
    "anchor": {
      "trackId": "ecoli_pggb_carriage",
      "loc": "chr:1,299,340",
      "fracY": 0.55
    }
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/config.json \
  --width 1000 --height 610 \
  --timeout 120000 \
  --spec session.json --annotations callouts.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.

Reproduce it end to end

build_ecoli_pangenome_graph.sh runs every step above except the E146 read mapping, downloads JBrowse, and writes a config.json with the five assemblies, their gene tracks, every other track on this page, and a default session:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_ecoli_pangenome_graph.sh
bash build_ecoli_pangenome_graph.sh
npx --yes serve ecoli_pangenome_graph_build/jbrowse2

CONTAINER=singularity forces the container runtime. To add genomes, add rows to the strain table in the script; wfmash time grows with the square of the genome count.

See also