Skip to main content

Variant track

TL;DR: 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 indicating an SNV alongside the alignment track evidence. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  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”.
  3. Drag the bar at the bottom edge of the track to resize it.“volvox filtered vcf”.
  4. 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)”.
  5. Type your region of interest into the location box and press Enter.This figure is at ctgA:14439-14515.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

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

This session spec pastes after &session=spec- on any JBrowse Web instance.

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

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:14439-14515",
)

view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "VcfTabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "AlignmentsTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "CramAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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 \
  --session 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, and what the rest of this page covers.
  • Multi-sample variant display (regular) draws one row per sample at each variant's true genomic position, the only multi-sample display that renders structural variants at the right scale.
  • Multi-sample variant display (matrix) gives every visible variant a full column regardless of spacing, so shared haplotypes, runs of homozygosity, and population structure become visible. Both are covered in the multi-sample variant guide.
  • LD heatmap display computes pairwise r² from the phased genotypes live and draws the triangle. See the linkage disequilibrium tutorial.
  • Paired arc display joins the two ends of each breakend record with an arc.

Adding the same track to a circular view instead gives a chord display, which draws long-range breakends as chords across the ring.

Variant widget

Clicking a variant opens a widget with a per-sample genotype table. Multi-sample VCFs (like 1000 Genomes) can contain thousands of samples.

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

The steps behind the figure above, run against your own data.

  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.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

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

This session spec pastes after &session=spec- on any JBrowse Web instance.

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

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:6257-6305",
)

view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track",
    "name": "My track",
    "assemblyNames": ["volvox"],
    "adapter": {"type": "VcfTabixAdapter", "uri": "https://your-server/your-file"},
})

view  # display the widget

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 \
  --session 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 SAMPLES section lists every sample with its genotype (GT) and other per-sample fields, and each column has its own filter box accepting plain text or a regex. For example, typing '1' in the genotype filter keeps only samples carrying the first alternate allele (0|1 or 1|1), hiding the many homozygous-reference rows. GT=0 is the REF allele, and any non-zero value is an ALT allele. Filtering a trio's genotypes this way is how the 1000 Genomes SV tutorial checks whether a call is inherited.

Coloring variants

Color by... in the track menu has two one-click presets that read the VCF's own annotations, plus two escape hatches:

  • 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 any attribute name and colors by its value, generating a jexl:randomColor(get(feature,'<attr>')) expression. Distinct values get distinct, stable colors, so it works on any categorical INFO field

Both presets draw a floating color key naming only the classes present, which you can dismiss, and both work on the multi-sample displays, where consequence impact and SV type are covered in full, with the terms in each tier and the color per SV class.

For anything else, set the display's color slot to a jexl expression. The variants plugin registers helper functions for it, so a track can be colored by minor allele frequency, missingness, or consequence impact without preprocessing the VCF: see helper functions for jexl color expressions.

See also