Skip to main content

Variant track

A variant track displays VCF records, one glyph per call, and a click opens a per-sample genotype table. The track menu's Display types switches to a multi-sample view (one row per sample), an LD heatmap, or a paired-arc view for breakends. Color by... buckets variants by SnpEff/VEP consequence severity or SV type with one click, or colors by any INFO field via a jexl expression (e.g. minor allele frequency).

Variant track marking an SNV beside the alignment track evidence.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗

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%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A14439-14515%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22volvox_filtered_vcf%22%2C%22height%22%3A60%7D%2C%22volvox_cram_alignments%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+variant_with_pileup

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 volvox, 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 VCF (.vcf.gz + .tbi).This figure uses “volvox filtered vcf”.
    1. Drag the bar at the bottom edge of the track to resize it (60px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a CRAM file (.cram + .crai).This figure uses “volvox-sorted.cram (contigA, default display)”.
  4. Type your region of interest into the location box and press Enter.This figure is at ctgA:14439-14515.

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 volvox, 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 VCF (.vcf.gz + .tbi).This figure uses “volvox filtered vcf”.
    1. Drag the bar at the bottom edge of the track to resize it (60px here).
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a CRAM file (.cram + .crai).This figure uses “volvox-sorted.cram (contigA, default display)”.
  4. Type your region of interest into the location box and press Enter.This figure is at ctgA:14439-14515.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:14439-14515",
      "tracks": [
        {
          "trackId": "volvox_filtered_vcf",
          "height": 60
        },
        "volvox_cram_alignments"
      ]
    }
  ]
}

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/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:14439-14515",
            "tracks": [
                {
                    "trackId": "volvox_filtered_vcf",
                    "height": 60
                },
                "volvox_cram_alignments"
            ]
        }
    ],
)
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/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:14439-14515 \
  --track volvox_filtered_vcf '{"height":60}' \
  --track volvox_cram_alignments \
  --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 — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:14439-14515",
      "tracks": [
        {
          "trackId": "volvox_filtered_vcf",
          "height": 60
        },
        "volvox_cram_alignments"
      ]
    }
  ]
}
JSON

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

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

Display types

In a linear genome view, the track menu's Display types switches between:

  • Variant display, the default, covered on this page
  • Multi-sample variant display draws one row per sample, each variant at its genomic position, or, with Show... → Show as genotype matrix, in equal-width columns so shared haplotypes and runs of homozygosity show whatever the spacing. See the multi-sample variant guide
  • Marks draws the variants as the marks you configure, and over an SV VCF joins each breakend to its mate with nothing configured. See links

For an LD heatmap, run PLINK over the genotypes and load its pairwise r² output as a separate track, as in the linkage disequilibrium tutorial.

In a circular view the same track gives a chord display, drawing breakends as chords across the ring.

Variant widget

Clicking a variant opens a widget with a per-sample genotype table.

Feature details panel for an SNV (C→T), with a per-sample genotype table in the SAMPLES section.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗

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%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A6257-6305%22%2C%22tracks%22%3A%5B%22volvox_test_vcf%22%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+variant_panel

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 volvox, 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 VCF (.vcf.gz + .tbi).This figure uses “volvox 1000genomes vcf”.
  3. Type your region of interest into the location box and press Enter.This figure is at ctgA:6257-6305.

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 volvox, 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 VCF (.vcf.gz + .tbi).This figure uses “volvox 1000genomes vcf”.
  3. Type your region of interest into the location box and press Enter.This figure is at ctgA:6257-6305.

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

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:6257-6305",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}

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/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:6257-6305",
            "tracks": [
                "volvox_test_vcf"
            ]
        }
    ],
)
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/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:6257-6305 \
  --track volvox_test_vcf \
  --width 1150 --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 — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:6257-6305",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --width 1150 --height 1080 \
  --spec session.json -o figure.png

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

It leaves out 3 callouts anchored to what the clicks bring up.

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 SAMPLES section lists every sample's genotype (GT) and other per-sample fields, with a plain-text or regex filter box per column. Typing '1' in the genotype filter keeps only samples with the first alternate allele (0|1 or 1|1). The 1000 Genomes SV tutorial filters a trio's genotypes this way to check whether a call is inherited.

Coloring variants

Color by... in the track menu:

  • Consequence impact buckets each variant by the severity of its most severe predicted consequence, read from SnpEff ANN or VEP CSQ in the INFO field: HIGH red, MODERATE orange, LOW yellow, MODIFIER grey
  • SV type colors by structural-variant class, with fixed colors per class and an ascending rainbow for copy-number alleles (<CN0>, <CN1>, ...)
  • Attribute... takes a field name and colors by its value, one palette color per value, with a key: a record field such as type or FILTER, or a path into INFO such as INFO.SVCLASS

The presets draw a dismissable color key naming the classes present, and work on the multi-sample displays too, where consequence impact and SV type list the terms in each tier and the color per class.

For anything else, set the display's color slot to a jexl expression. The variants plugin registers helpers for minor allele frequency, missingness and consequence impact; see helper functions for jexl color expressions.

See also