Skip to main content

Variant track

A variant track displays VCF records, one glyph per call, with one row per sample under them when the VCF has genotypes, and a click opens a per-sample genotype table. The track menu's Display types switches to marks, which join each breakend to its mate. 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 ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open your own genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses volvox, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “volvox filtered vcf”.
  3. Add the next track the same way. Needs a CRAM file (.cram + .crai).This figure uses “volvox-sorted.cram (contigA, default display)”.
  4. Go to your region in the location box.This figure is at ctgA:14439-14515.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/code/jb2/main/test_data/volvox/config.json
- Tracks:
  - volvox filtered vcf (volvox_filtered_vcf), VariantTrack, a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi), drawn as LinearVariantDisplay
  - volvox-sorted.cram (contigA, default display) (volvox_cram_alignments), AlignmentsTrack, a CRAM file (.cram + .crai), drawn as LinearAlignmentsDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:14439-14515",
      "tracks": [
        {
          "trackId": "volvox_filtered_vcf",
          "height": 60
        },
        "volvox_cram_alignments"
      ]
    }
  ]
}
Redraw the figure headlessly
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 600 \
  --spec session.json -o figure.png

More: Using JBrowse with AI agents.

Adds these tracks to your config.json, styled as in the figure. Point each uri at your file (replace YOUR_FILE).

jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "volvox_filtered_vcf",
  "name": "volvox filtered vcf",
  "assemblyNames": [
    "volvox"
  ],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 60
  }
}'

Run beside config.json, or add --out <dir>. Needs volvox in the config (jbrowse add-assembly).

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your 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

This view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.

import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'

const configUrl = "https://jbrowse.org/code/jb2/main/test_data/volvox/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={config.tracks}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      views={[
        {
          "type": "LinearGenomeView",
          "assembly": "volvox",
          "loc": "ctgA:14439-14515",
          "tracks": [
            {
              "trackId": "volvox_filtered_vcf",
              "height": 60
            },
            "volvox_cram_alignments"
          ]
        }
      ]}
    />
  )
}

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

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

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

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

Display types

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

  • Variant display, the default: the records, and under them one row per sample, each variant at its genomic position, or, with Layout → Genotype matrix, in equal-width columns so shared haplotypes and runs of homozygosity show whatever the spacing. See the sample rows 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 ↗

Or rebuild it from your own data:

Quickest: open the view, then File → Open track... for your files.

From scratch:

  1. Open your genome: Open your own genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses volvox, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi).This figure uses “volvox 1000genomes vcf”.
  3. Go to your region in the location box.This figure is at ctgA:6257-6305.

Paste into a coding agent, with your goal on the first line.

My goal: [write yours, e.g. this view of my own files, or these track settings in my config.json]

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/code/jb2/main/test_data/volvox/config.json
- Tracks:
  - volvox 1000genomes vcf (volvox_test_vcf), VariantTrack, a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi), drawn as LinearVariantDisplay

Docs: https://jbrowse.org/jb2/docs/agents_authoring/ (writing a config), https://jbrowse.org/jb2/docs/agents/ (driving a running JBrowse). Use the jbrowse-authoring, jbrowse-hosted-data and jbrowse-capture skills if you have them. Check any config with `npx @jbrowse/cli validate`, then render it and look: a config that loads is not yet a track that drew.

The session spec that draws the view:
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:6257-6305",
      "tracks": [
        "volvox_test_vcf"
      ]
    }
  ]
}
Redraw the figure headlessly
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 1400 \
  --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.

More: Using JBrowse with AI agents.

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your 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

This view in your React 19 app, with @jbrowse/react-app2 and @jbrowse/core. Add your own files to tracks.

import { use } from 'react'
import { JBrowse } from '@jbrowse/react-app2'
import '@jbrowse/react-app2/styles.css'
import { addRelativeUris } from '@jbrowse/core/util/addRelativeUris'

const configUrl = "https://jbrowse.org/code/jb2/main/test_data/volvox/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={config.tracks}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      views={[
        {
          "type": "LinearGenomeView",
          "assembly": "volvox",
          "loc": "ctgA:6257-6305",
          "tracks": [
            "volvox_test_vcf"
          ]
        }
      ]}
    />
  )
}

jbrowse-img draws this view as an SVG, no browser needed. Swap --config or a track for your own.

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

For a PNG, --out figure.png (needs rsvg-convert: apt install librsvg2-bin, brew install librsvg).

The session spec behind the figure, over this config.

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

The SAMPLES section lists every sample's genotype (GT) and other per-sample fields, with a plain-text or regex filter box per column. Type '1' in the genotype filter to keep 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>, ...)
  • Field... 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 color the genotype cells 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 encoding.color 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