Skip to main content

Variant track

A VariantTrack with a VcfTabixAdapter handles single- and multi-sample VCFs. Color variants with a jexl: expression on the display's color slot, and reach for the multi-sample or LD displays for cohort data.

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

{
  "type": "VariantTrack",
  "trackId": "my_track",
  "name": "My Variants",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/file.vcf.gz"
  }
}
jbrowse add-track https://yourhost/file.vcf.gz \
  --trackId my_track \
  --name "My Variants" \
  --assemblyNames hg19

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": "my_track",
  "name": "My Variants",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/file.vcf.gz"
  }
}

The uri shorthand resolves a sibling .tbi; add "csi": true for a .csi (the uri shorthand).

Coloring variants

color takes a jexl: expression over the record. INFO fields parse as arrays, so feature.INFO.SVTYPE[0] is the first value; the cookbook has the SV-type lookup table and a filter example.

Helper functions for jexl color expressions

The variants plugin registers these for color and filter:

jexl: maf(feature) // minor allele frequency over the called alleles
jexl: missingness(feature) // fraction of alleles with no call, so ./1 counts half
jexl: impact(feature) // HIGH, MODERATE, LOW or MODIFIER, from SnpEff ANN / VEP CSQ
jexl: consequence(feature) // e.g. missense_variant, from the same annotation — the MOST SEVERE one alone
jexl: 'missense_variant' in consequences(feature) // every consequence term on the record, across all transcripts (bcftools INFO/CSQ ~ "missense_variant")
jexl: impactColor(feature) // the color the "Color by consequence impact" menu item uses
jexl: alleleLength(feature) >= 50 // longest allele in bp, so an insertion is not measured by its reference span
jexl: svType(feature) == 'DEL' // SV class, read off a symbolic ALT before falling back to INFO/SVTYPE (bcftools INFO/SVTYPE)
jexl: nAlt(feature) == 1 // ALT alleles the record declares, i.e. biallelic-only (bcftools N_ALT)
jexl: genotypeCount(feature, 'het') > 0 // samples in a genotype class — ref, alt, hom, het or mis (bcftools N_PASS(GT="het"))

With those functions available, a track colors by allele frequency with no preprocessing:

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

{
  "trackId": "my_maf_track",
  "name": "Variants colored by allele frequency",
  "uri": "https://yourhost/file.vcf.gz",
  "assemblyNames": ["hg38"],
  "displayDefaults": {
    "color": "jexl:maf(feature)<0.01?'#ccc':maf(feature)<0.05?'#74a9cf':'#045a8d'"
  }
}
jbrowse add-track https://yourhost/file.vcf.gz \
  --trackId my_maf_track \
  --name "Variants colored by allele frequency" \
  --assemblyNames hg38 \
  --displayDefaults "{\"color\":\"jexl:maf(feature)<0.01?'#ccc':maf(feature)<0.05?'#74a9cf':'#045a8d'\"}"

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": "my_maf_track",
  "name": "Variants colored by allele frequency",
  "uri": "https://yourhost/file.vcf.gz",
  "assemblyNames": ["hg38"],
  "displayDefaults": {
    "color": "jexl:maf(feature)<0.01?'#ccc':maf(feature)<0.05?'#74a9cf':'#045a8d'"
  }
}

MultiVariant display configuration

LinearMultiSampleVariantDisplay draws a multi-sample VCF as a genotype heatmap, one row per sample, each variant at its genomic position or, with variantLayout: 'columns', in equal-width columns. It is not the track's default display, so preset its slots in a displays array; they are listed on LinearMultiSampleVariantDisplay.

Configuring default display settings

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

{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "referenceDrawingMode": "draw",
      "minorAlleleFrequencyFilter": 0.05,
      "showRowLabels": true,
      "renderingMode": "alleleCount"
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "referenceDrawingMode": "draw",
      "minorAlleleFrequencyFilter": 0.05,
      "showRowLabels": true,
      "renderingMode": "alleleCount"
    }
  ]
}'

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": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "referenceDrawingMode": "draw",
      "minorAlleleFrequencyFilter": 0.05,
      "showRowLabels": true,
      "renderingMode": "alleleCount"
    }
  ]
}
  • referenceDrawingMode is draw to paint reference alleles too, or skip (the default) to leave the row solid gray with only ALT alleles on top, which keeps overlapping variants readable
  • renderingMode is alleleCount (dosage, darker for homozygous) or phased (one row per haplotype)
  • minorAlleleFrequencyFilter and maxMissingnessFilter hide variants below an allele-frequency floor or above a no-call ceiling

Coloring cells by the variant

color paints every cell with an alt allele by the variant itself. A CSS colour or a jexl expression paints every alt cell of a variant, the helper functions included. A field gives each of its values a colour, with a key. Three fields are the track menu's Color by... presets: impact for consequence impact, svType for SV type and phaseSet for the phase set in phased mode. Any other field is read off the record, such as INFO.CLNSIG or QUAL, and a variant with no value keeps the default alt colour.

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

{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "color": { "field": "impact" }
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "color": { "field": "impact" }
    }
  ]
}'

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": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "color": { "field": "impact" }
    }
  ]
}

A number cuts into ranges with a threshold scale: domain lists the cut points and range one colour per range, one more than the cuts. Allele frequency split into ultra-rare, rare, low-frequency and common:

"displays": [
  {
    "type": "LinearMultiSampleVariantDisplay",
    "color": {
      "field": "INFO.AF",
      "scale": "threshold",
      "domain": ["0.001", "0.01", "0.05"],
      "range": ["#b2182b", "#ef8a62", "#67a9cf", "#2166ac"]
    }
  }
]

Auto-coloring samples by metadata

Point the adapter's samplesTsvLocation at a TSV whose first column is name, matching the VCF sample names, with any further columns as metadata:

name	population	region	phenotype
SAMPLE001	EUR	Western	case
SAMPLE002	AFR	Eastern	control
SAMPLE003	EUR	Western	control
SAMPLE004	EAS	Pacific	case

rowColor on the display names one of those columns, and each distinct value gets its own palette color:

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

{
  "type": "VariantTrack",
  "trackId": "population_vcf",
  "name": "Population VCF",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/samples.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://yourhost/sample_metadata.tsv"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "rowColor": "population"
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "population_vcf",
  "name": "Population VCF",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/samples.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://yourhost/sample_metadata.tsv"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "rowColor": "population"
    }
  ]
}'

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": "population_vcf",
  "name": "Population VCF",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/samples.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://yourhost/sample_metadata.tsv"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "rowColor": "population"
    }
  ]
}
  • A column rowColor names that the TSV lacks logs a console warning and skips the coloring
  • Sample names match exactly. A TSV matching some of the VCF's samples draws those and reports the ones it dropped; one matching none fails the track. The usual cause is a prefixed or suffixed id, 1000GP_HG00096 against a header naming HG00096

Linkage disequilibrium (LD) display

JBrowse draws a triangular heatmap of pairwise r² (or D') between variants, computed live from a VCF's genotypes or read from a PLINK file. Point it at a single population panel: r² is a correlation across the samples in the file, so a pooled multi-population callset averages the block away.

An LD triangle of pairwise r² at the human lactase locus (LCT/MCM6), over the haplotype matrix it summarises. Red is a pair of SNPs almost always inherited together, and the block over the highlighted gene is one long haplotype.
Open in JBrowse Web ↗Open in JBrowse Desktop ↗

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

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=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22LDTrack%22%2C%22trackId%22%3A%22kgp_lct_ld%22%2C%22name%22%3A%22LCT+lactase-persistence+LD%2C+1000G+European+panel+%28r%C2%B2%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22PlinkLDTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fpopgen%2Flct_1kg38_chr2_eur.ld.gz%22%7D%2C%22displayDefaults%22%3A%7B%22variantLayout%22%3A%22genomic%22%2C%22showLegend%22%3Atrue%2C%22height%22%3A360%7D%7D%2C%7B%22type%22%3A%22VariantTrack%22%2C%22trackId%22%3A%22kgp_lct_haplotypes%22%2C%22name%22%3A%221000+Genomes+haplotypes+across+LCT+%28one+row+per+haplotype%29%22%2C%22assemblyNames%22%3A%5B%22hg38%22%5D%2C%22adapter%22%3A%7B%22type%22%3A%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fpopgen%2Flct_1kg38_chr2_6pop.vcf.gz%22%2C%22samplesTsvLocation%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fgenomes%2Fhg19%2F1000g.sorted.csv.gz%22%7D%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22variantLayout%22%3A%22columns%22%2C%22renderingMode%22%3A%22phased%22%2C%22rowColor%22%3A%22population%22%2C%22minorAlleleFrequencyFilter%22%3A0.35%2C%22forceLoad%22%3Atrue%2C%22height%22%3A700%7D%5D%7D%5D%2C%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg38%22%2C%22loc%22%3A%22chr2%3A134%2C400%2C000-136%2C900%2C000%22%2C%22highlight%22%3A%5B%7B%22refName%22%3A%22chr2%22%2C%22start%22%3A135787850%2C%22end%22%3A135876467%2C%22assemblyName%22%3A%22hg38%22%7D%5D%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22hg38-ncbiRefSeqCurated%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A60%2C%22showOnlyGenes%22%3Atrue%7D%2C%7B%22trackId%22%3A%22hg38-clinvarMain%22%2C%22type%22%3A%22LinearBasicDisplay%22%2C%22height%22%3A56%2C%22filter%22%3A%5B%22jexl%3Aget%28feature%2C%27phenotypeList%27%29%3D%3D%27LACTASE+PERSISTENCE%27%22%5D%7D%2C%7B%22trackId%22%3A%22kgp_lct_ld%22%2C%22type%22%3A%22LDTrackDisplay%22%2C%22height%22%3A260%7D%2C%7B%22trackId%22%3A%22kgp_lct_haplotypes%22%2C%22type%22%3A%22LinearMultiSampleVariantDisplay%22%2C%22height%22%3A520%2C%22lineZoneHeight%22%3A34%2C%22runClustering%22%3Atrue%2C%22clusterRegion%22%3A%22chr2%3A135%2C787%2C850-135%2C876%2C467%22%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+ld%2Flct_haploblock

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 hg38, 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 GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. Drag the bar at the bottom edge of the track to resize it (60px here).
    2. Track menu → Show only genes (checked)
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a BigBed file (.bb).This figure uses “ClinVar Variants - ClinVar SNVs”.
    1. Drag the bar at the bottom edge of the track to resize it (56px here).
    2. Track menu → Filter by... → add the expressionThis figure filters on get(feature,'phenotypeList')=='LACTASE PERSISTENCE'.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “LCT lactase-persistence LD, 1000G European panel (r²)”.
    1. Drag the bar at the bottom edge of the track to resize it (260px here).
  5. 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 “1000 Genomes haplotypes across LCT (one row per haplotype)”.
    1. Drag the bar at the bottom edge of the track to resize it (520px here).
    2. Drag the bottom edge of the band of connecting lines above the rows to resize it.
    3. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
    4. Navigate to the region you want to cluster on, then Track menu → Cluster rows by genotype...Clustering is scoped to the region it was run over — this figure clustered on chr2:135,787,850-135,876,467, which is what the row order reflects even after navigating elsewhere.
  6. Type your region of interest into the location box and press Enter.This figure is at chr2:134,400,000-136,900,000.
  7. 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.

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 hg38, 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 GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. Drag the bar at the bottom edge of the track to resize it (60px here).
    2. Track menu → Show only genes (checked)
  3. Add your own track: File → Open track..., then paste a URL or choose a local file. This one needs a BigBed file (.bb).This figure uses “ClinVar Variants - ClinVar SNVs”.
    1. Drag the bar at the bottom edge of the track to resize it (56px here).
    2. Track menu → Filter by... → add the expressionThis figure filters on get(feature,'phenotypeList')=='LACTASE PERSISTENCE'.
  4. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses “LCT lactase-persistence LD, 1000G European panel (r²)”.
    1. Drag the bar at the bottom edge of the track to resize it (260px here).
  5. 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 “1000 Genomes haplotypes across LCT (one row per haplotype)”.
    1. Drag the bar at the bottom edge of the track to resize it (520px here).
    2. Drag the bottom edge of the band of connecting lines above the rows to resize it.
    3. Track menu → Clustering → Cluster rows by similarityOrders the rows by how alike they are across the region in view, and draws the tree it built beside them. It clusters over what is displayed, so the same menu item somewhere else gives a different order.
    4. Navigate to the region you want to cluster on, then Track menu → Cluster rows by genotype...Clustering is scoped to the region it was run over — this figure clustered on chr2:135,787,850-135,876,467, which is what the row order reflects even after navigating elsewhere.
  6. Type your region of interest into the location box and press Enter.This figure is at chr2:134,400,000-136,900,000.
  7. 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.

A figure adds its tracks to one session. The jbrowse CLI writes the same tracks into a config.json instead, where every session that opens it has them: add-track where flags cover the whole track, add-track-json where they do not.

jbrowse add-track https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur.ld.gz \
  --trackId kgp_lct_ld \
  --name "LCT lactase-persistence LD, 1000G European panel (r²)" \
  --assemblyNames hg38 \
  --displayDefaults '{"variantLayout":"genomic","showLegend":true,"height":360}'

jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "kgp_lct_haplotypes",
  "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
    "samplesTsvLocation": {
      "uri": "https://jbrowse.org/genomes/hg19/1000g.sorted.csv.gz"
    }
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "variantLayout": "columns",
      "renderingMode": "phased",
      "rowColor": "population",
      "minorAlleleFrequencyFilter": 0.35,
      "forceLoad": true,
      "height": 700
    }
  ]
}'

Run these where the config.json is, or add --out <dir>, and point each uri at your own file. The config needs hg38 already — jbrowse add-assembly adds yours. The location and the settings the steps carry are session state rather than track config — that half is the Spec tab, or jbrowse set-default-session.

This session spec draws the figure from https://jbrowse.org/ucsc/hg38/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

{
  "sessionTracks": [
    {
      "type": "LDTrack",
      "trackId": "kgp_lct_ld",
      "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "PlinkLDTabixAdapter",
        "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur.ld.gz"
      },
      "displayDefaults": {
        "variantLayout": "genomic",
        "showLegend": true,
        "height": 360
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_haplotypes",
      "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
        "samplesTsvLocation": {
          "uri": "https://jbrowse.org/genomes/hg19/1000g.sorted.csv.gz"
        }
      },
      "displays": [
        {
          "type": "LinearMultiSampleVariantDisplay",
          "variantLayout": "columns",
          "renderingMode": "phased",
          "rowColor": "population",
          "minorAlleleFrequencyFilter": 0.35,
          "forceLoad": true,
          "height": 700
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr2:134,400,000-136,900,000",
      "highlight": [
        {
          "refName": "chr2",
          "start": 135787850,
          "end": 135876467,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "type": "LinearBasicDisplay",
          "height": 60,
          "showOnlyGenes": true
        },
        {
          "trackId": "hg38-clinvarMain",
          "type": "LinearBasicDisplay",
          "height": 56,
          "filter": [
            "jexl:get(feature,'phenotypeList')=='LACTASE PERSISTENCE'"
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "type": "LDTrackDisplay",
          "height": 260
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 520,
          "lineZoneHeight": 34,
          "runClustering": true,
          "clusterRegion": "chr2:135,787,850-135,876,467"
        }
      ]
    }
  ]
}

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/ucsc/hg38/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []) + [
        {
            "type": "LDTrack",
            "trackId": "kgp_lct_ld",
            "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
            "assemblyNames": [
                "hg38"
            ],
            "adapter": {
                "type": "PlinkLDTabixAdapter",
                "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur.ld.gz"
            },
            "displayDefaults": {
                "variantLayout": "genomic",
                "showLegend": True,
                "height": 360
            }
        },
        {
            "type": "VariantTrack",
            "trackId": "kgp_lct_haplotypes",
            "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
            "assemblyNames": [
                "hg38"
            ],
            "adapter": {
                "type": "VcfTabixAdapter",
                "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
                "samplesTsvLocation": {
                    "uri": "https://jbrowse.org/genomes/hg19/1000g.sorted.csv.gz"
                }
            },
            "displays": [
                {
                    "type": "LinearMultiSampleVariantDisplay",
                    "variantLayout": "columns",
                    "renderingMode": "phased",
                    "rowColor": "population",
                    "minorAlleleFrequencyFilter": 0.35,
                    "forceLoad": True,
                    "height": 700
                }
            ]
        }
    ],
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg38",
            "loc": "chr2:134,400,000-136,900,000",
            "highlight": [
                {
                    "refName": "chr2",
                    "start": 135787850,
                    "end": 135876467,
                    "assemblyName": "hg38"
                }
            ],
            "tracks": [
                {
                    "trackId": "hg38-ncbiRefSeqCurated",
                    "type": "LinearBasicDisplay",
                    "height": 60,
                    "showOnlyGenes": True
                },
                {
                    "trackId": "hg38-clinvarMain",
                    "type": "LinearBasicDisplay",
                    "height": 56,
                    "filter": [
                        "jexl:get(feature,'phenotypeList')=='LACTASE PERSISTENCE'"
                    ]
                },
                {
                    "trackId": "kgp_lct_ld",
                    "type": "LDTrackDisplay",
                    "height": 260
                },
                {
                    "trackId": "kgp_lct_haplotypes",
                    "type": "LinearMultiSampleVariantDisplay",
                    "height": 520,
                    "lineZoneHeight": 34,
                    "runClustering": True,
                    "clusterRegion": "chr2:135,787,850-135,876,467"
                }
            ]
        }
    ],
)
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.

cat > tracks.json <<'JSON'
[
  {
    "type": "LDTrack",
    "trackId": "kgp_lct_ld",
    "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
    "assemblyNames": [
      "hg38"
    ],
    "adapter": {
      "type": "PlinkLDTabixAdapter",
      "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur.ld.gz"
    },
    "displayDefaults": {
      "variantLayout": "genomic",
      "showLegend": true,
      "height": 360
    }
  },
  {
    "type": "VariantTrack",
    "trackId": "kgp_lct_haplotypes",
    "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
    "assemblyNames": [
      "hg38"
    ],
    "adapter": {
      "type": "VcfTabixAdapter",
      "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
      "samplesTsvLocation": {
        "uri": "https://jbrowse.org/genomes/hg19/1000g.sorted.csv.gz"
      }
    },
    "displays": [
      {
        "type": "LinearMultiSampleVariantDisplay",
        "variantLayout": "columns",
        "renderingMode": "phased",
        "rowColor": "population",
        "minorAlleleFrequencyFilter": 0.35,
        "forceLoad": true,
        "height": 700
      }
    ]
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --tracks tracks.json \
  --assembly hg38 --loc chr2:134,400,000-136,900,000 \
  --track hg38-ncbiRefSeqCurated display:LinearBasicDisplay '{"height":60,"showOnlyGenes":true}' \
  --track hg38-clinvarMain display:LinearBasicDisplay '{"height":56,"filter":["jexl:get(feature,'\''phenotypeList'\'')=='\''LACTASE PERSISTENCE'\''"]}' \
  --track kgp_lct_ld display:LDTrackDisplay '{"height":260}' \
  --track kgp_lct_haplotypes display:LinearMultiSampleVariantDisplay '{"height":520,"lineZoneHeight":34,"runClustering":true,"clusterRegion":"chr2:135,787,850-135,876,467"}' \
  --width 1500 --out figure.svg

It has no flag for this figure's highlight, so its picture can differ there.

--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'
{
  "sessionTracks": [
    {
      "type": "LDTrack",
      "trackId": "kgp_lct_ld",
      "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "PlinkLDTabixAdapter",
        "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur.ld.gz"
      },
      "displayDefaults": {
        "variantLayout": "genomic",
        "showLegend": true,
        "height": 360
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_haplotypes",
      "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
        "samplesTsvLocation": {
          "uri": "https://jbrowse.org/genomes/hg19/1000g.sorted.csv.gz"
        }
      },
      "displays": [
        {
          "type": "LinearMultiSampleVariantDisplay",
          "variantLayout": "columns",
          "renderingMode": "phased",
          "rowColor": "population",
          "minorAlleleFrequencyFilter": 0.35,
          "forceLoad": true,
          "height": 700
        }
      ]
    }
  ],
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg38",
      "loc": "chr2:134,400,000-136,900,000",
      "highlight": [
        {
          "refName": "chr2",
          "start": 135787850,
          "end": 135876467,
          "assemblyName": "hg38"
        }
      ],
      "tracks": [
        {
          "trackId": "hg38-ncbiRefSeqCurated",
          "type": "LinearBasicDisplay",
          "height": 60,
          "showOnlyGenes": true
        },
        {
          "trackId": "hg38-clinvarMain",
          "type": "LinearBasicDisplay",
          "height": 56,
          "filter": [
            "jexl:get(feature,'phenotypeList')=='LACTASE PERSISTENCE'"
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "type": "LDTrackDisplay",
          "height": 260
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "type": "LinearMultiSampleVariantDisplay",
          "height": 520,
          "lineZoneHeight": 34,
          "runClustering": true,
          "clusterRegion": "chr2:135,787,850-135,876,467"
        }
      ]
    }
  ]
}
JSON

cat > callouts.json <<'JSON'
[
  {
    "type": "text",
    "text": "LCT/MCM6",
    "fontSize": 20,
    "leader": true,
    "anchor": {
      "track": "hg38-clinvarMain",
      "locus": "chr2:135,787,850",
      "fracY": 0.5,
      "alignX": "left"
    },
    "dx": -60
  },
  {
    "type": "text",
    "text": "Swept haplotype: one uniform cluster",
    "fontSize": 22,
    "leader": true,
    "anchor": {
      "track": "kgp_lct_haplotypes",
      "locus": "chr2:135,760,000",
      "fracY": 0.27
    },
    "dx": -260
  },
  {
    "type": "text",
    "text": "Every other haplotype: mosaic",
    "fontSize": 22,
    "leader": true,
    "anchor": {
      "track": "kgp_lct_haplotypes",
      "locus": "chr2:135,760,000",
      "fracY": 0.75
    },
    "dx": -260
  }
]
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/ucsc/hg38/config.json \
  --width 1500 --height 1224 \
  --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.

Computed from a VCF. Add an LDDisplay to a normal VariantTrack. The raw genotypes are present, so the filters (minor allele frequency, HWE, call rate, jexl) and signed LD are available:

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

{
  "type": "VariantTrack",
  "trackId": "variants_ld",
  "name": "Variants with LD",
  "uri": "https://yourhost/variants.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [{ "type": "LDDisplay" }]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "variants_ld",
  "name": "Variants with LD",
  "uri": "https://yourhost/variants.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [{ "type": "LDDisplay" }]
}'

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": "variants_ld",
  "name": "Variants with LD",
  "uri": "https://yourhost/variants.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [{ "type": "LDDisplay" }]
}

Pre-computed with PLINK. A standalone LDTrack serves a cohort too large to compute in the browser, or a fixed matrix to publish. PlinkLDAdapter reads a plain .ld; PlinkLDTabixAdapter reads a bgzipped, tabix-indexed .ld.gz and fetches only the visible region. PLINK data has only the final r²/D' values, so the filters and signed LD are absent here. The GWAS track guide has the plink command, and the same file drives LD coloring on a GWAS track.

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

{
  "trackId": "ld_plink",
  "name": "Linkage disequilibrium",
  "uri": "https://yourhost/study.ld.gz",
  "assemblyNames": ["hg38"]
}
jbrowse add-track https://yourhost/study.ld.gz \
  --trackId ld_plink \
  --name "Linkage disequilibrium" \
  --assemblyNames hg38

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": "ld_plink",
  "name": "Linkage disequilibrium",
  "uri": "https://yourhost/study.ld.gz",
  "assemblyNames": ["hg38"]
}

Which metric, and how far to thin

ldMetric switches between two reads of the same block:

  • D' measures whether recombination has been seen between two markers, so it saturates near 1 wherever no recombinant haplotype has turned up. It recovers where crossing over stops, which finds an inversion's breakpoints
  • r² measures how well one marker predicts the other, which also requires the two to be at similar frequency, so it draws the sharper boundary. It shows whether one marker can stand in for another

Thinning is plink's --maf, decided when the table is written rather than in the browser: it holds the dense callset down to the common, block-tagging variants. High enough it reaches the tagging variants themselves, and the block fades. Several haplotypes at one locus fragment the block too, since no single pair of biallelic markers tags them all, so a soft sweep reads patchier than its strength suggests.

See also