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... and, in Add a track from file or URL, enter:

  • Main file: https://yourhost/file.vcf.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: My Variants
  • Assembly: hg19

Click Add.

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 `color: { field: 'impact' }` paints the variant's most severe tier
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. A jexl: expression as the color object's field computes the value, and a threshold scale bins it, with a key naming each bin:

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": {
      "field": "jexl:maf(feature)",
      "scale": "threshold",
      "domain": ["0.01", "0.05"],
      "range": ["#ccc", "#74a9cf", "#045a8d"],
      "title": "Minor allele frequency"
    }
  }
}
jbrowse add-track https://yourhost/file.vcf.gz \
  --trackId my_maf_track \
  --name "Variants colored by allele frequency" \
  --assemblyNames hg38 \
  --displayDefaults '{"color":{"field":"jexl:maf(feature)","scale":"threshold","domain":["0.01","0.05"],"range":["#ccc","#74a9cf","#045a8d"],"title":"Minor allele frequency"}}'

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": {
      "field": "jexl:maf(feature)",
      "scale": "threshold",
      "domain": ["0.01", "0.05"],
      "range": ["#ccc", "#74a9cf", "#045a8d"],
      "title": "Minor allele frequency"
    }
  }
}

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,
      "unit": "sample"
    }
  ]
}
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,
      "unit": "sample"
    }
  ]
}'

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,
      "unit": "sample"
    }
  ]
}
  • 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
  • unit is sample (one row per sample, darker for homozygous) or haplotype (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 color or a jexl expression paints every alt cell of a variant, the helper functions included. A field gives each of its values a color, 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 color.

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 color 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, read from a table PLINK writes. Compute it over 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 ↗
Desktop link does nothing?

It needs JBrowse Desktop 5.0+. Or 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%22unit%22%3A%22haplotype%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

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 hg38, 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 - RefSeq Curated”.
    1. Track menu → Show only genes (checked)
  3. Add the next track the same way. This one needs a BigBed file (.bb).This figure uses “ClinVar Variants - ClinVar SNVs”.
    1. Track menu → Filter by... → add the expressionThis figure filters on get(feature,'phenotypeList')=='LACTASE PERSISTENCE'.
  4. Add the next track the same way.This figure uses “LCT lactase-persistence LD, 1000G European panel (r²)”.
  5. Add the next track the same way. 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 bottom edge of the band of connecting lines above the rows to resize it.
    2. 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.
    3. 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",
      "unit": "haplotype",
      "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. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/ucsc/hg38/config.json, which is what the Web button above opens.

{
  "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",
          "unit": "haplotype",
          "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",
                    "unit": "haplotype",
                    "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",
        "unit": "haplotype",
        "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: change the location or a track's settings, or add your own track under sessionTracks, 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",
          "unit": "haplotype",
          "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": {
      "trackId": "hg38-clinvarMain",
      "loc": "chr2:135,787,850",
      "fracY": 0.5,
      "alignX": "left"
    },
    "dx": -60
  },
  {
    "type": "text",
    "text": "Swept haplotype: one uniform cluster",
    "fontSize": 22,
    "leader": true,
    "anchor": {
      "trackId": "kgp_lct_haplotypes",
      "loc": "chr2:135,760,000",
      "fracY": 0.27
    },
    "dx": -260
  },
  {
    "type": "text",
    "text": "Every other haplotype: mosaic",
    "fontSize": 22,
    "leader": true,
    "anchor": {
      "trackId": "kgp_lct_haplotypes",
      "loc": "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.

An LDTrack draws the table. PlinkLDAdapter reads a plain .ld; PlinkLDTabixAdapter reads a bgzipped, tabix-indexed .ld.gz and fetches only the visible region. Filtering by allele frequency, Hardy-Weinberg or call rate happens in plink when it writes the table. 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... and, in Add a track from file or URL, enter:

  • Main file: https://yourhost/study.ld.gz

Click Next. JBrowse reads the adapter and track type off the file name. Then fill in:

  • Track name: Linkage disequilibrium
  • Assembly: hg38

Click Add.

Which metric, and how far to thin

color.field switches between two reads of the same block, r2 on a red ramp and dprime on a blue one unless color.scheme names another:

  • 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: 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