Skip to main content

Pangenome (mouse)

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

The mouse strain pangenome aligns eighteen inbred and wild-derived strains from the Mouse Genomes Project onto the GRCm39 reference with minigraph. GRCm39 is itself one of the strains, C57BL/6J, which inverts the sign of the best-known variant in the panel. No locus list has been published for these strains, so we rank the graph's bubbles, the regions where the strains' paths split and rejoin, by how many segments each holds, and open the densest. We:

  • at Nnt, read a C57BL/6J deletion as sequence the other strains have
  • rank the bubbles in the graph and open the densest one that fits in a window, at Dock2
  • look the Dock2 bubble up in the hosted index

Every step starts from the mouse graph page on staging.genomes.jbrowse.org, where it stays until a JBrowse 5 host for the graph plugin ships.

Experimental

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

Prerequisites

  • htslib (tabix), to query the hosted index
  • minigraph, to build a graph like this one

Where the data comes from

The reference is UCSC's mm39 and the strains are the Mouse Genomes Project assemblies as UCSC GenArk rehosts them. We host the graph as the index files below.

Hosting your own graph describes what each file holds.

Load the graph

We'll load the reference, then the graph and its bubbles. The graph track names the file prefix build_pangenome_graph.sh writes, and the uris below are our hosted copy, so swap the prefix for your own build.

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

{
  "name": "mm39",
  "aliases": ["GRCm39"],
  "uri": "https://hgdownload.soe.ucsc.edu/goldenPath/mm39/bigZips/mm39.2bit",
  "refNameAliases": {
    "uri": "https://jbrowse.org/ucsc/mm39/mm39.chromAlias.txt"
  }
}
jbrowse add-assembly https://hgdownload.soe.ucsc.edu/goldenPath/mm39/bigZips/mm39.2bit \
  --name mm39 \
  --alias GRCm39 \
  --refNameAliases https://jbrowse.org/ucsc/mm39/mm39.chromAlias.txt

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

{
  "type": "GraphTrack",
  "trackId": "mouse_minigraph_segments",
  "name": "Mouse strain pangenome (rGFA segments)",
  "assemblyNames": ["mm39"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph",
    "coarse": {
      "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.tier10000",
      "aboveBpPerPx": 328
    }
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}
jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "mouse_minigraph_segments",
  "name": "Mouse strain pangenome (rGFA segments)",
  "assemblyNames": ["mm39"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph",
    "coarse": {
      "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.tier10000",
      "aboveBpPerPx": 328
    }
  },
  "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": "mouse_minigraph_segments",
  "name": "Mouse strain pangenome (rGFA segments)",
  "assemblyNames": ["mm39"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph",
    "coarse": {
      "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.tier10000",
      "aboveBpPerPx": 328
    }
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}

The bubbles track reads the same build's bubble index:

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

{
  "type": "FeatureTrack",
  "trackId": "mouse_minigraph_bubbles",
  "name": "Mouse strain pangenome bubbles",
  "assemblyNames": ["mm39"],
  "adapter": {
    "type": "MinigraphBubbleAdapter",
    "uri": "https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.bubbles.bed.gz"
  }
}
jbrowse add-track https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.bubbles.bed.gz \
  --trackId mouse_minigraph_bubbles \
  --name "Mouse strain pangenome bubbles" \
  --assemblyNames mm39 \
  --adapterType MinigraphBubbleAdapter

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: Minigraph bubbles (tabix BED)
  • Path: https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.bubbles.bed.gz
  • Track name: Mouse strain pangenome bubbles
  • Assembly: mm39

Nnt: a C57BL/6J deletion that appears as an insertion

Click chr13 on the Whole chromosome line of the portal page, which opens the whole chromosome with the graph drawn as one node per bubble, a region where the strains' paths split and rejoin. Type chr13:119,440,000-119,600,000, and the graph track draws the segments there. Then:

  • in the graph track's menu, pick Layout → Force-directed layout and tick Mark bubbles
  • turn on the bubbles track in the track selector

C57BL/6J has a multi-exon deletion at Nnt (nicotinamide nucleotide transhydrogenase) that abolishes the protein and makes C57BL/6J mice glucose intolerant. GRCm39 is C57BL/6J, so the backbone of this graph, the reference path, is the strain with the deletion. The graph shows the deletion as sequence that the other strains have and the reference lacks, the opposite sign from the published descriptions.

The Nnt window with the RefSeq genes and the bubbles track above the force-directed graph track. The node hanging off the backbone beside Nnt is haloed and labelled as an insertion, because the reference is the strain that lacks the sequence.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗

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

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

Nothing happens?

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%2Fpangenome_nonhuman.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22mm39%22%2C%22loc%22%3A%22chr13%3A119%2C440%2C000-119%2C600%2C000%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22mm39_ncbiRefSeq_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A48%7D%2C%7B%22trackId%22%3A%22mouse_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A52%7D%2C%7B%22trackId%22%3A%22mouse_minigraph_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22showBubbles%22%3Atrue%2C%22height%22%3A420%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_mouse_nnt_halos

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).This figure uses mm39, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (mm39)”.
    1. Drag the bar at the bottom edge of the track to resize it (48px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (52px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Mark bubbles (checked)
    4. Drag the bar at the bottom edge of the track to resize it (420px here).
  5. Type your region of interest into the location box and press Enter.This figure is at chr13:119,440,000-119,600,000.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses mm39, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (mm39)”.
    1. Drag the bar at the bottom edge of the track to resize it (48px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (52px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Mark bubbles (checked)
    4. Drag the bar at the bottom edge of the track to resize it (420px here).
  5. Type your region of interest into the location box and press Enter.This figure is at chr13:119,440,000-119,600,000.

This session spec draws the figure from test_data/graphgenomeview/pangenome_nonhuman.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "mm39",
      "loc": "chr13:119,440,000-119,600,000",
      "tracks": [
        {
          "trackId": "mm39_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "height": 48
        },
        {
          "trackId": "mouse_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 52
        },
        {
          "trackId": "mouse_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "showBubbles": true,
          "height": 420
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "mm39",
      "loc": "chr13:119,440,000-119,600,000",
      "tracks": [
        {
          "trackId": "mm39_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "height": 48
        },
        {
          "trackId": "mouse_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 52
        },
        {
          "trackId": "mouse_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "showBubbles": true,
          "height": 420
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "Sequence the other strains have and C57BL/6J lacks: its Nnt deletion",
    "fontSize": 17,
    "maxWidth": 330,
    "leader": true,
    "anchor": {
      "graphNode": "s130043141+"
    },
    "dx": 160,
    "dy": 40
  }
]
JSON

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

Ranking the graph's bubbles to find Dock2

The whole-chromosome overview records how many segments each bubble holds, and more segments mean more variation. Ranking the bubbles by that count finds where the graph varies most, and matching them to the reference annotation names each locus. generatePangenomeLoci.ts in the genomes.jbrowse.org repo computes the ranking.

The portal page's Loci table shows that ranking. It recovers the vomeronasal receptor and Speer families and the immunoglobulin heavy chain locus. The rows above Dock2 are too wide for one window; its row is the densest bubble that fits in one, inside one intron at chr11:34,516,044-34,560,497. Click its graph link, then pick Layout → Force-directed layout from the graph track menu and tick Mark bubbles:

The Dock2 intron bubble, the densest in the mouse graph that fits in one window. The bubbles track is a single row, the allele inventory draws each alternative path at its size, and the graph carries one label for the whole bubble, with Dock2 pinned under the backbone. The coloured path is C57BL/6J, the reference, and each charcoal loop is sequence other strains have and the reference lacks.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗

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

Or rebuild it from your own data:

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

Nothing happens?

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%2Fpangenome_nonhuman.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22mm39%22%2C%22loc%22%3A%22chr11%3A34%2C516%2C044-34%2C560%2C497%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22mm39_ncbiRefSeq_ucsc%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A48%7D%2C%7B%22trackId%22%3A%22mouse_minigraph_bubbles%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A52%7D%2C%7B%22trackId%22%3A%22mouse_minigraph_alleles%22%2C%22type%22%3A%22LinearPileupDisplay%22%2C%22height%22%3A110%7D%2C%7B%22trackId%22%3A%22mouse_minigraph_segments%22%2C%22type%22%3A%22LinearGraphDisplay%22%2C%22layoutMode%22%3A%22force%22%2C%22colorScheme%22%3A%22reference-position%22%2C%22showBubbles%22%3Atrue%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fmouse_dock2

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).This figure uses mm39, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (mm39)”.
    1. Drag the bar at the bottom edge of the track to resize it (48px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (52px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Mouse strain pangenome: allele inventory”.
    1. Drag the bar at the bottom edge of the track to resize it (110px here).
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Mark bubbles (checked)
    4. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr11:34,516,044-34,560,497.

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

  1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.This figure uses mm39, loaded from a .2bit genome.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq genes (mm39)”.
    1. Drag the bar at the bottom edge of the track to resize it (48px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome bubbles”.
    1. Drag the bar at the bottom edge of the track to resize it (52px here).
  4. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Mouse strain pangenome: allele inventory”.
    1. Drag the bar at the bottom edge of the track to resize it (110px here).
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “Mouse strain pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed layout
    2. Track menu → Color → Reference position
    3. Track menu → Mark bubbles (checked)
    4. Drag the bar at the bottom edge of the track to resize it (600px here).
  6. Type your region of interest into the location box and press Enter.This figure is at chr11:34,516,044-34,560,497.

This session spec draws the figure from test_data/graphgenomeview/pangenome_nonhuman.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "mm39",
      "loc": "chr11:34,516,044-34,560,497",
      "tracks": [
        {
          "trackId": "mm39_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "height": 48
        },
        {
          "trackId": "mouse_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 52
        },
        {
          "trackId": "mouse_minigraph_alleles",
          "type": "LinearPileupDisplay",
          "height": 110
        },
        {
          "trackId": "mouse_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "showBubbles": true,
          "height": 600
        }
      ]
    }
  ]
}

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "mm39",
      "loc": "chr11:34,516,044-34,560,497",
      "tracks": [
        {
          "trackId": "mm39_ncbiRefSeq_ucsc",
          "type": "LinearBasicDisplay",
          "height": 48
        },
        {
          "trackId": "mouse_minigraph_bubbles",
          "type": "LinearBasicDisplay",
          "height": 52
        },
        {
          "trackId": "mouse_minigraph_alleles",
          "type": "LinearPileupDisplay",
          "height": 110
        },
        {
          "trackId": "mouse_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "colorScheme": "reference-position",
          "showBubbles": true,
          "height": 600
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "C57BL/6J, the reference",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "graphNode": "s110010685+"
    },
    "dx": -60,
    "dy": -30
  },
  {
    "type": "text",
    "text": "sequence C57BL/6J lacks",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "graphNode": "s110050877+"
    },
    "dx": -80,
    "dy": -40
  }
]
JSON

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

minigraph writes no path lines, so the graph does not record which strains carry an allele; the allele inventory's firstSeenIn names the first assembly to contribute it.

Looking up the Dock2 bubble in the hosted bubbles BED

The Dock2 bubble is one row of the hosted bubbles BED, with the same segment count and span the figure labels:

tabix https://jbrowse.org/demos/mouse_pangenome/mouse-mm39-minigraph.bubbles.bed.gz \
  'mm39#0#chr11:34516044-34560497'

Building a minigraph graph from the strain assemblies

To build a graph like this one, run minigraph once per chromosome over the sequence for that chromosome from each assembly, reference first so that its segments take rank 0, the earliest build order:

# -xggs: incremental graph construction, adding each genome in turn
# -c: base-level alignment, which minigraph recommends for graph generation
minigraph -cxggs -t 8 mm39.chr13.fa strain1.chr13.fa strain2.chr13.fa > chr13.gfa

Pangenome (hosting your own graph) then turns the graph into the files above with one command, build_pangenome_graph.sh. build_mouse_pangenome.sh runs the whole build: it downloads the assemblies, extracts each chromosome renamed to PanSN (sample#haplotype#contig), runs minigraph per chromosome, and joins the chromosomes with segment ids renumbered; the alignment takes most of a day.

The script writes a README.txt beside the data recording the source, the modifications, the tool versions and the audits that ran. The build stops if the reference path does not reproduce the reference chromosome lengths, or if renumbering leaves a duplicate segment id; either failure produces a graph with wrong coordinates that every later check accepts. Copy these audits into your own build.

See also

Citations