Skip to main content

Pangenome (cattle)

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

The bovine super-pangenome builds a set of assemblies into one graph on the ARS-UCD1.2 cattle reference, a Hereford that is itself one of them: taurine and indicine breeds, yak, bison and gaur. Each assembly is a named path through the graph, and vg deconstruct turns those paths into a VCF, so one locus reads both as a graph of where sequence is present and absent and as a callset listing which assemblies have it. We:

  • read a whole chromosome with one node per variant region
  • at HSPA1A, compare the graph's list of alleles with the callset
  • find three published breed and species variants in the callset

Every step starts from the graph's 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.

Prerequisites

# Debian/Ubuntu
sudo apt install tabix
# or conda, which has every tool above
conda install -c bioconda -c conda-forge htslib vg

The data

The OMIA build script fetches OMIA's dump, and the track configs below read the hosted files by URL. For a graph of your own, swap the prefix in uri for your gfa-to-tabix build, as Load the genome and the graph shows.

What it isFile
OMIA's database dump, the source of the curated variant trackomia.sql.gz
Read by URL (no download needed)
What it isFile
The segment and link indexbovine-arsucd12-minigraph.segs.bed.gz
bovine-arsucd12-minigraph.links.bed.gz
The bubble index, where assemblies' paths split and rejoinbovine-arsucd12-minigraph.bubbles.bed.gz
The allele inventory, one row per alternative sequence at a bubblebovine-arsucd12-minigraph.alleles.bed.gz
The overview used for whole chromosomes, with variants under 10 kb folded into the referencebovine-arsucd12-minigraph.fold10000.segs.bed.gz
bovine-arsucd12-minigraph.fold10000.links.bed.gz

Load the genome and the graph

We'll load the reference the graph is anchored to, then the graph track. Swap the prefix in uri for your own gfa-to-tabix build, which writes the tabix-indexed segments and links and the overview.

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

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

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

{
  "type": "GraphTrack",
  "trackId": "bovine_minigraph_segments",
  "name": "Bovine super-pangenome (rGFA segments)",
  "assemblyNames": ["bosTau9"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph",
    "coarse": {
      "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.fold10000",
      "aboveBpPerPx": 1000
    }
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}
jbrowse add-track-json '{
  "type": "GraphTrack",
  "trackId": "bovine_minigraph_segments",
  "name": "Bovine super-pangenome (rGFA segments)",
  "assemblyNames": ["bosTau9"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph",
    "coarse": {
      "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-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": "bovine_minigraph_segments",
  "name": "Bovine super-pangenome (rGFA segments)",
  "assemblyNames": ["bosTau9"],
  "adapter": {
    "type": "RgfaTabixAdapter",
    "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph",
    "coarse": {
      "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.fold10000",
      "aboveBpPerPx": 1000
    }
  },
  "displays": [
    { "type": "LinearGraphDisplay" },
    { "type": "LinearBasicDisplay" }
  ]
}

Overview of chr23 with small variants folded

Open chr23 on the portal page and press Open in JBrowse. The whole chromosome opens with the graph's coarse tier, which folds every variant under 10 kb into the reference.

Chromosome 23 with RefSeq genes, segments per bubble as a curve, and the graph with variants under 10 kb folded into the reference.
Open in JBrowse Web ↗

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

Or rebuild it from your own data:

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

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

  1. Open your 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 bosTau9, 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 (bosTau9)”.
  3. Add the next track the same way.This figure uses “Bovine super-pangenome: variability (segments per bubble)”.
  4. Add the next track the same way.This figure uses “Bovine super-pangenome: variants under 10 kb folded (coarse tier)”.
    1. Track menu → Show... → Labels → None
  5. Type your region of interest into the location box and press Enter.This figure is at chr23.

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",
      "id": "bovine-chr23-lgv",
      "assembly": "bosTau9",
      "loc": "chr23",
      "tracks": [
        "bosTau9_ncbiRefSeq_ucsc",
        "bovine_bubble_score",
        {
          "trackId": "bovine_minigraph_tier",
          "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",
      "id": "bovine-chr23-lgv",
      "assembly": "bosTau9",
      "loc": "chr23",
      "tracks": [
        "bosTau9_ncbiRefSeq_ucsc",
        "bovine_bubble_score",
        {
          "trackId": "bovine_minigraph_tier",
          "type": "LinearBasicDisplay",
          "showLabels": "none",
          "height": 60
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "BoLA",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "bovine_bubble_score",
      "loc": "chr23:25,900,000",
      "fracY": 0.15
    },
    "dx": -100,
    "dy": -10
  }
]
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 550 \
  --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.

BoLA, the cattle major histocompatibility complex (immune genes that vary a lot between breeds), contains the heat shock gene HSPA1A, the subject of the next section.

HSPA1A in the graph and the callset

ARS-UCD1.2 lacks an 11 kb segment beside the heat shock gene HSPA1A, which contains HSPA1B, its near-identical copy. Leonard et al. (2022) recovered it in every assembly they built. The graph lists that segment in the allele inventory. These graphs record no build order, so its firstSeenIn column names the first assembly in a fixed list, which need not contain the segment.

The callset gives a genotype per assembly. We ran vg deconstruct once per chromosome over the same graph:

# -p: vg's PackedGraph format, which deconstruct reads
vg convert -g chr1.gfa -p > chr1.vg
# -p: the reference path to decompose against
# -a: nested snarls too, so a bubble inside a bubble gets a record
vg deconstruct -p chr1 -a -t 8 chr1.vg > chr1.vcf

The VCF's CHROM column is the -p path name, which has to equal the assembly's refName. Its sample names are the three-letter codes on each assembly's path, and the sample table's first column has to match them. A mismatch leaves the row unlabelled and raises no error:

name	breed	lineage
ANG	Angus	taurine
BIS	Bison	bison

In grammar-of-graphics terms, rowColor in the track config is a color scale on each row's label bar, mapping the sample table's lineage column through domain to range. The config also sets:

  • rows.sort lists the cattle breeds above the wild species, and rows.labels writes each breed beside its row
  • unit: "haplotype" draws one row per assembly, each being one haplotype, with a second alternate allele in a separate color
  • variants draws each call once in a band above the rows, across the reference span it replaces, labelled with its VCF ID (the graph nodes that bound it) and the allele change

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

{
  "type": "VariantTrack",
  "trackId": "bovine_pangenome_vcf",
  "name": "Bovine super-pangenome variants (12 assemblies)",
  "assemblyNames": ["bosTau9"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.samples.tsv"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "unit": "haplotype",
      "variants": { "show": true },
      "rows": {
        "sort": [
          "ANG",
          "BSW",
          "HIG",
          "OBV",
          "PIE",
          "SIM",
          "BRA",
          "NEL",
          "GAU",
          "BIS",
          "YAK"
        ],
        "labels": {
          "ANG": "Angus",
          "BSW": "Brown Swiss",
          "HIG": "Highland",
          "OBV": "Original Braunvieh",
          "PIE": "Piedmontese",
          "SIM": "Simmental",
          "BRA": "Brahman",
          "NEL": "Nellore",
          "GAU": "Gaur",
          "BIS": "Bison",
          "YAK": "Yak"
        }
      },
      "rowColor": {
        "field": "lineage",
        "scale": {
          "domain": ["taurine", "indicine", "gaur", "bison", "yak"],
          "range": ["#0072B2", "#E69F00", "#009E73", "#CC79A7", "#D55E00"]
        }
      }
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "bovine_pangenome_vcf",
  "name": "Bovine super-pangenome variants (12 assemblies)",
  "assemblyNames": ["bosTau9"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.samples.tsv"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "unit": "haplotype",
      "variants": { "show": true },
      "rows": {
        "sort": [
          "ANG",
          "BSW",
          "HIG",
          "OBV",
          "PIE",
          "SIM",
          "BRA",
          "NEL",
          "GAU",
          "BIS",
          "YAK"
        ],
        "labels": {
          "ANG": "Angus",
          "BSW": "Brown Swiss",
          "HIG": "Highland",
          "OBV": "Original Braunvieh",
          "PIE": "Piedmontese",
          "SIM": "Simmental",
          "BRA": "Brahman",
          "NEL": "Nellore",
          "GAU": "Gaur",
          "BIS": "Bison",
          "YAK": "Yak"
        }
      },
      "rowColor": {
        "field": "lineage",
        "scale": {
          "domain": ["taurine", "indicine", "gaur", "bison", "yak"],
          "range": ["#0072B2", "#E69F00", "#009E73", "#CC79A7", "#D55E00"]
        }
      }
    }
  ]
}'

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": "bovine_pangenome_vcf",
  "name": "Bovine super-pangenome variants (12 assemblies)",
  "assemblyNames": ["bosTau9"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/demos/bovine_pangenome/bovine-arsucd12-minigraph.samples.tsv"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "unit": "haplotype",
      "variants": { "show": true },
      "rows": {
        "sort": [
          "ANG",
          "BSW",
          "HIG",
          "OBV",
          "PIE",
          "SIM",
          "BRA",
          "NEL",
          "GAU",
          "BIS",
          "YAK"
        ],
        "labels": {
          "ANG": "Angus",
          "BSW": "Brown Swiss",
          "HIG": "Highland",
          "OBV": "Original Braunvieh",
          "PIE": "Piedmontese",
          "SIM": "Simmental",
          "BRA": "Brahman",
          "NEL": "Nellore",
          "GAU": "Gaur",
          "BIS": "Bison",
          "YAK": "Yak"
        }
      },
      "rowColor": {
        "field": "lineage",
        "scale": {
          "domain": ["taurine", "indicine", "gaur", "bison", "yak"],
          "range": ["#0072B2", "#E69F00", "#009E73", "#CC79A7", "#D55E00"]
        }
      }
    }
  ]
}

Open this track in JBrowse Web ↗

In the chr23 view the portal opened, type chr23:27,508,000-27,536,000 to draw the graph around HSPA1A. Then:

  • Turn on the callset and the allele inventory in the track selector.
  • Open Graph settings... in the graph track's menu and set Bubble spread to Compress lengths. An insertion has no reference span to draw along, and the portal opens the graph force-directed, which draws it by its shape.
HSPA1A with the deconstructed callset, one row per assembly, the allele inventory and the graph track. The graph draws the insertion as the charcoal loop.
Open in JBrowse Web ↗

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

Or rebuild it from your own data:

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

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

  1. Open your 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 bosTau9, 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 (bosTau9)”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “Bovine super-pangenome variants (12 assemblies)”.
    1. Track menu → Show... → Variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Layout → Genotype matrix" is unchecked.
  4. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed BED (.bed.gz + .tbi).This figure uses “Bovine super-pangenome: allele inventory”.
    1. Track menu → Show... → Coverage (unchecked)
    2. Track menu → Show... → Sashimi arcs (unchecked)Hides the splice-junction arcs and keeps the coverage band underneath them.
  5. Add the next track the same way.This figure uses “Bovine super-pangenome (rGFA segments)”.
    1. Track menu → Layout → Force-directed
    2. Track menu → Graph settings... → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
  6. Type your region of interest into the location box and press Enter.This figure is at chr23:27,508,000-27,536,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",
      "id": "pangenome-bovine_bola-lgv",
      "assembly": "bosTau9",
      "loc": "chr23:27,508,000-27,536,000",
      "tracks": [
        {
          "trackId": "bosTau9_ncbiRefSeq_ucsc",
          "height": 90
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 260
        },
        {
          "trackId": "bovine_minigraph_alleles",
          "coverage": {
            "show": false
          },
          "sashimi": {
            "show": false
          },
          "height": 90
        },
        {
          "trackId": "bovine_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "bubbleSpread": "compress",
          "color": {
            "field": "position"
          },
          "maxRegionBp": 30801,
          "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",
      "id": "pangenome-bovine_bola-lgv",
      "assembly": "bosTau9",
      "loc": "chr23:27,508,000-27,536,000",
      "tracks": [
        {
          "trackId": "bosTau9_ncbiRefSeq_ucsc",
          "height": 90
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 260
        },
        {
          "trackId": "bovine_minigraph_alleles",
          "coverage": {
            "show": false
          },
          "sashimi": {
            "show": false
          },
          "height": 90
        },
        {
          "trackId": "bovine_minigraph_segments",
          "type": "LinearGraphDisplay",
          "layoutMode": "force",
          "bubbleSpread": "compress",
          "color": {
            "field": "position"
          },
          "maxRegionBp": 30801,
          "height": 420
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "graph alleles, each sequence once, whichever assemblies have it",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "bovine_minigraph_alleles",
      "loc": "chr23:27,521,000",
      "fracY": 0.45
    },
    "dx": 80,
    "dy": -10
  }
]
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 1190 \
  --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.

Published variants in the callset

Each locus below is a structural variant a paper reported in one of these breeds or species. The rows without it are the control.

The Celtic polled allele

Angus cattle are born without horns. Medugorac et al. (2012) traced the Celtic form of polledness to a 202 bp duplication and insertion on chromosome 1, which OMIA, the Online Mendelian Inheritance in Animals database, curates as OMIA 000483-9913.1

The portal page's POLLED example tells this story: it names the Celtic polled allele above the map, and each launch opens a Known alleles row and OMIA's records under the genes. Every launch up to 150 kb wide on the portal carries the OMIA row.

To add OMIA to your own JBrowse, build_omia_cattle_variants.sh writes omia_cattle_variants.gff3.gz from OMIA's nightly database dump. It keeps the cattle records published on ARS-UCD1.2 or ARS-UCD1.3, which share every chromosome's coordinates:

curl -fO https://raw.githubusercontent.com/GMOD/jbrowse-components/main/scripts/build_omia_cattle_variants.sh
bash build_omia_cattle_variants.sh

Add the records as a track:

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

{
  "trackId": "omia_cattle_variants",
  "name": "OMIA causal variants (cattle)",
  "uri": "omia_cattle_variants.gff3.gz",
  "assemblyNames": ["bosTau9"],
  "displayDefaults": {
    "labels": {
      "description": "jexl:feature.inheritance"
    }
  }
}
jbrowse add-track omia_cattle_variants.gff3.gz \
  --trackId omia_cattle_variants \
  --name "OMIA causal variants (cattle)" \
  --assemblyNames bosTau9 \
  --displayDefaults '{"labels":{"description":"jexl:feature.inheritance"}}' \
  --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:

{
  "trackId": "omia_cattle_variants",
  "name": "OMIA causal variants (cattle)",
  "uri": "omia_cattle_variants.gff3.gz",
  "assemblyNames": ["bosTau9"],
  "displayDefaults": {
    "labels": {
      "description": "jexl:feature.inheritance"
    }
  }
}

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

Then open chr1:2,428,800-2,429,800. The figure shades chr1:2,429,109-2,429,320, the stretch OMIA records as duplicated by the allele.

The POLLED locus with OMIA's record of the Celtic polled allele above the callset.
Open in JBrowse Web ↗

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

Or rebuild it from your own data:

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

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

  1. Open your 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 bosTau9, 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 “OMIA causal variants (cattle)”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “Bovine super-pangenome variants (12 assemblies)”.
    1. Track menu → Show... → Variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Layout → Genotype matrix" is unchecked.
  4. Type your region of interest into the location box and press Enter.This figure is at chr1:2,428,800-2,429,800.
  5. 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/code/jb2/main/test_data/graphgenomeview/pangenome_nonhuman.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "id": "pangenome-bovine_polled-lgv",
      "assembly": "bosTau9",
      "loc": "chr1:2,428,800-2,429,800",
      "tracks": [
        {
          "trackId": "omia_cattle_variants",
          "height": 60
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 260
        }
      ],
      "highlight": [
        {
          "refName": "chr1",
          "start": 2429108,
          "end": 2429320,
          "color": "rgba(255,193,7,0.30)"
        }
      ]
    }
  ]
}

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/pangenome_nonhuman.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "id": "pangenome-bovine_polled-lgv",
            "assembly": "bosTau9",
            "loc": "chr1:2,428,800-2,429,800",
            "tracks": [
                {
                    "trackId": "omia_cattle_variants",
                    "height": 60
                },
                {
                    "trackId": "bovine_pangenome_vcf",
                    "variants": {
                        "show": True
                    },
                    "height": 260
                }
            ],
            "highlight": [
                {
                    "refName": "chr1",
                    "start": 2429108,
                    "end": 2429320,
                    "color": "rgba(255,193,7,0.30)"
                }
            ]
        }
    ],
)
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: a data file opens as the track its name says.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/graphgenomeview/pangenome_nonhuman.json \
  --assembly bosTau9 --loc chr1:2,428,800-2,429,800 \
  --view '{"id":"pangenome-bovine_polled-lgv","highlight":[{"refName":"chr1","start":2429108,"end":2429320,"color":"rgba(255,193,7,0.30)"}]}' \
  --track omia_cattle_variants '{"height":60}' \
  --track bovine_pangenome_vcf '{"variants":{"show":true},"height":260}' \
  --width 1400 --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",
      "id": "pangenome-bovine_polled-lgv",
      "assembly": "bosTau9",
      "loc": "chr1:2,428,800-2,429,800",
      "tracks": [
        {
          "trackId": "omia_cattle_variants",
          "height": 60
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 260
        }
      ],
      "highlight": [
        {
          "refName": "chr1",
          "start": 2429108,
          "end": 2429320,
          "color": "rgba(255,193,7,0.30)"
        }
      ]
    }
  ]
}
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 580 \
  --timeout 300000 \
  --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.

A repeat upstream of KIT in white-headed cattle

Simmental and Hereford cattle have white heads. Milia et al. (2025) tied the trait to a 14.3 kb segment repeated in tandem upstream of KIT: white-headed breeds have extra copies, color-headed breeds a deletion. The Hereford reference holds one collapsed copy. Open chr6:70,080,000-70,180,000, and put the graph track back on the reference's coordinates under the callset with Anchored under the Layout row of its menu.

Upstream of KIT with the callset and the graph track, which draws the deletion as a dashed arc.
Open in JBrowse Web ↗

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

Or rebuild it from your own data:

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

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

  1. Open your 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 bosTau9, 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 (bosTau9)”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “Bovine super-pangenome variants (12 assemblies)”.
    1. Track menu → Show... → Variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Layout → Genotype matrix" is unchecked.
  4. Add the next track the same way.This figure uses “Bovine super-pangenome (rGFA segments)”.
    1. Track menu → Graph settings... → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
  5. Type your region of interest into the location box and press Enter.This figure is at chr6:70,080,000-70,180,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",
      "id": "pangenome-bovine_kit-lgv",
      "assembly": "bosTau9",
      "loc": "chr6:70,080,000-70,180,000",
      "tracks": [
        {
          "trackId": "bosTau9_ncbiRefSeq_ucsc",
          "height": 90
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 300
        },
        {
          "trackId": "bovine_minigraph_segments",
          "type": "LinearGraphDisplay",
          "color": {
            "field": "position"
          },
          "bubbleSpread": "compress",
          "maxRegionBp": 110001,
          "height": 240
        }
      ]
    }
  ]
}

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",
      "id": "pangenome-bovine_kit-lgv",
      "assembly": "bosTau9",
      "loc": "chr6:70,080,000-70,180,000",
      "tracks": [
        {
          "trackId": "bosTau9_ncbiRefSeq_ucsc",
          "height": 90
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 300
        },
        {
          "trackId": "bovine_minigraph_segments",
          "type": "LinearGraphDisplay",
          "color": {
            "field": "position"
          },
          "bubbleSpread": "compress",
          "maxRegionBp": 110001,
          "height": 240
        }
      ]
    }
  ]
}
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 920 \
  --timeout 300000 \
  --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 larger box at the left of the Simmental row is an insertion the length of the 14.3 kb segment: Simmental has one more copy than the Hereford reference.

A deletion of TAS2R46 in gaur

TAS2R46 encodes a bitter taste receptor. Leonard et al. (2022) found a 17 kb deletion in gaur that removes it. Open chr5:98,575,000-98,615,000.

TAS2R46 with the callset and the graph track, which draws the deletion as a dashed arc.
Open in JBrowse Web ↗

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

Or rebuild it from your own data:

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

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

  1. Open your 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 bosTau9, 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 (bosTau9)”.
  3. Add the next track the same way. This one needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “Bovine super-pangenome variants (12 assemblies)”.
    1. Track menu → Show... → Variant lane (checked)Draws the variants at their genomic positions in a lane above the genotype rows. Offered only while "Layout → Genotype matrix" is unchecked.
  4. Add the next track the same way.This figure uses “Bovine super-pangenome (rGFA segments)”.
    1. Track menu → Graph settings... → Bubble spread → Compress lengthsSets a floor on how long a node is drawn in the force layout, so a short allele is a visible arm rather than a speck. Does nothing in the anchored layouts, which place a node from its coordinates.
  5. Type your region of interest into the location box and press Enter.This figure is at chr5:98,575,000-98,615,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",
      "id": "pangenome-bovine_tas2r46-lgv",
      "assembly": "bosTau9",
      "loc": "chr5:98,575,000-98,615,000",
      "tracks": [
        {
          "trackId": "bosTau9_ncbiRefSeq_ucsc",
          "height": 90
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 300
        },
        {
          "trackId": "bovine_minigraph_segments",
          "type": "LinearGraphDisplay",
          "color": {
            "field": "position"
          },
          "bubbleSpread": "compress",
          "maxRegionBp": 44000,
          "height": 240
        }
      ]
    }
  ]
}

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",
      "id": "pangenome-bovine_tas2r46-lgv",
      "assembly": "bosTau9",
      "loc": "chr5:98,575,000-98,615,000",
      "tracks": [
        {
          "trackId": "bosTau9_ncbiRefSeq_ucsc",
          "height": 90
        },
        {
          "trackId": "bovine_pangenome_vcf",
          "variants": {
            "show": true
          },
          "height": 300
        },
        {
          "trackId": "bovine_minigraph_segments",
          "type": "LinearGraphDisplay",
          "color": {
            "field": "position"
          },
          "bubbleSpread": "compress",
          "maxRegionBp": 44000,
          "height": 240
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "deleted in gaur",
    "fontSize": 18,
    "leader": true,
    "anchor": {
      "trackId": "bovine_pangenome_vcf",
      "loc": "chr5:98,600,000",
      "fracY": 0.78
    },
    "dx": 60,
    "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 920 \
  --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.

Angus, Piedmontese, Brahman and Nellore, two taurine and two indicine breeds, share that allele, and only the gaur's deletes the span. The insertion boxed in each of the four rows, between TAS2R46 and the next gene, is most of the difference.

Building the bovine graph files

Pangenome (hosting your own graph) turns a graph into the files above with one command, gfa-to-tabix build. The published bovine graphs need three steps beyond it, which build_bovine_pangenome.sh runs:

  • Join the autosomes. The archive holds one graph per autosome, each numbering its segments from 1, so the script renumbers and concatenates them.
  • Recover rGFA tags. The graphs state their coordinates in P lines, and gfa_paths_to_rgfa.py converts them back into SN/SO/SR tags (each segment's contig, offset and rank).
  • Deconstruct the callset with the vg deconstruct call above.

The script stops if the reference path does not reproduce bosTau9's chromosome lengths, and a README.txt beside the hosted files records the source and every modification.

Leonard et al. also built pggb and Minigraph-Cactus graphs of the same twelve assemblies, base-level GFAs with path lines and no rGFA tags. gfa-to-tabix build writes an SM:Z: tag per segment listing the assemblies that pass through it.

See also

Citations

Notes

  1. OMIA also records the Friesian polled allele, a larger duplication further along, which Holstein cattle have. The panel has no Holstein. ↩