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

The mouse strain pangenome aligns eighteen inbred and wild-derived strain assemblies from the Mouse Genomes Project onto the GRCm39 reference with minigraph. GRCm39 is itself a strain, 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 genomes.jbrowse.org, which launches the JBrowse 5 development build until JBrowse 5 ships.

Experimental

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

The mouse graph records no strain's path, so it lists the alleles that exist and leaves out which strains have them.

Prerequisites

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.

Nothing to download: the track configs below read the index files by URL.

The files

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 gfa-to-tabix build 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.fold10000",
      "aboveBpPerPx": 1000
    }
  },
  "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.fold10000",
      "aboveBpPerPx": 1000
    }
  },
  "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.fold10000",
      "aboveBpPerPx": 1000
    }
  },
  "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 chromosomes line of the portal page, which opens the whole chromosome with the graph drawn as one node per bubble. Type chr13:119,440,000-119,600,000 to draw the segments there. Then:

  • in the graph track's menu, tick Show... → Show bubble halos
  • 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 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 ↗
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%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%22color%22%3A%7B%22field%22%3A%22position%22%7D%2C%22layers%22%3A%7B%22bubbles%22%3Atrue%7D%2C%22height%22%3A420%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fgraph_mouse_nnt_halos

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 mm39, loaded from a .2bit genome.
  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 “NCBI RefSeq genes (mm39)”.
  3. Add the next track the same way.This figure uses “Mouse strain pangenome bubbles”.
  4. Add the next track the same way.This figure uses “Mouse strain pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed
  5. Type your region of interest into the location box and press Enter.This figure is at chr13:119,440,000-119,600,000.

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

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/pangenome_nonhuman.json, which is what the Web button above opens.

{
  "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",
          "color": {
            "field": "position"
          },
          "layers": {
            "bubbles": 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: 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": "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",
          "color": {
            "field": "position"
          },
          "layers": {
            "bubbles": 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. Ranking the bubbles that overlap a gene by that count recovers the vomeronasal receptor and Speer families and the immunoglobulin heavy chain locus, each too wide for one window. Dock2 is the densest bubble that fits in one, inside one intron at chr11:34,516,045-34,560,497. To open it:

  • Paste that region into the portal page's Gene or region box and click Graph.
  • In the graph track's menu, tick Show... → Show bubble halos.
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 has one label for the whole bubble, with Dock2 pinned under the backbone. The colored 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 ↗
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%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%22color%22%3A%7B%22field%22%3A%22position%22%7D%2C%22layers%22%3A%7B%22bubbles%22%3Atrue%7D%2C%22height%22%3A600%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+pangenome%2Fmouse_dock2

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 mm39, loaded from a .2bit genome.
  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 “NCBI RefSeq genes (mm39)”.
  3. Add the next track the same way.This figure uses “Mouse strain pangenome bubbles”.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Mouse strain pangenome: allele inventory”.
  5. Add the next track the same way.This figure uses “Mouse strain pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed
  6. Type your region of interest into the location box and press Enter.This figure is at chr11:34,516,044-34,560,497.

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

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/pangenome_nonhuman.json, which is what the Web button above opens.

{
  "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",
          "color": {
            "field": "position"
          },
          "layers": {
            "bubbles": 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: 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": "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",
          "color": {
            "field": "position"
          },
          "layers": {
            "bubbles": true
          },
          "height": 600
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "C57BL/6J, the reference",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "graphNode": "s110010685+"
    },
    "dx": 160,
    "dy": -110
  },
  {
    "type": "text",
    "text": "sequence C57BL/6J lacks",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "graphNode": "s110050877+"
    },
    "dx": -150,
    "dy": 120
  }
]
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 have an allele. The allele inventory's firstSeenIn lists the first assembly to contribute it.

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, gfa-to-tabix build. build_mouse_pangenome.sh runs the whole build, and the alignment takes most of a day. It:

  1. downloads the assemblies
  2. extracts each chromosome, renamed to PanSN (sample#haplotype#contig)
  3. runs minigraph per chromosome
  4. joins the chromosomes with segment ids renumbered

The script runs two audits on the joined graph and stops if:

  • a segment has an SN tag that is neither mm39#0#chr* nor <strain>#1#chr*
  • renumbering leaves a duplicate segment id

Either failure produces a graph with wrong coordinates that every later check accepts, so copy these audits into your own build.

See also

Citations