Skip to main content

Variant track

TL;DR: 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.

{
  "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 jexlFilters example.

Helper functions for jexl color expressions

The variants plugin registers these for color and jexlFilters:

jexl: maf(feature) // minor allele frequency over the called alleles
jexl: missingness(feature) // fraction of samples with no call
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: svTypeColor(feature) // the color "Color by SV type" 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"))

So a track colors by allele frequency with no preprocessing:

{
  "type": "VariantTrack",
  "trackId": "my_maf_track",
  "name": "Variants colored by allele frequency",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/file.vcf.gz"
  },
  "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:

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

MultiVariant display configuration

LinearMultiSampleVariantDisplay and LinearMultiSampleVariantMatrixDisplay draw a multi-sample VCF as a genotype heatmap, one row per sample. Neither is the track's default display, so preset their slots in a displays array, one block per display type. The slots both share are on SharedVariantDisplay.

Configuring default display settings

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

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",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/diversity.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "referenceDrawingMode": "draw",
      "minorAlleleFrequencyFilter": 0.05,
      "showRowLabels": true,
      "renderingMode": "alleleCount"
    },
    {
      "type": "LinearMultiSampleVariantMatrixDisplay"
    }
  ]
}
  • 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 instead of the genotype

featureColor overrides the per-genotype shading, painting every alt-carrying cell by the variant itself. It takes any per-feature jexl expression, the helper functions included, and two values match the track menu's Color by... presets: "jexl:impactColor(feature)" for consequence impact and the literal "svType" for SV type.

{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/diversity.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "featureColor": "jexl:impactColor(feature)"
    }
  ]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/diversity.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "featureColor": "jexl:impactColor(feature)"
    }
  ]
}'

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",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/diversity.vcf.gz"
  },
  "displays": [
    {
      "type": "LinearMultiSampleVariantDisplay",
      "featureColor": "jexl:impactColor(feature)"
    }
  ]
}

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

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

{
  "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",
      "colorBy": "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",
      "colorBy": "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",
      "colorBy": "population"
    }
  ]
}
  • A column colorBy 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 this view in JBrowse ↗ (large dataset — this session takes a while to load)

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 hg38.
  2. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “hg38-ncbiRefSeqCurated” track.
  3. Drag the bar at the bottom edge of the track to resize it.“hg38-ncbiRefSeqCurated”.
  4. Track menu → Show only genes (checked)“hg38-ncbiRefSeqCurated”.
  5. Add your own track: File → Open track..., then paste a URL or choose a local file.This figure uses the “hg38-clinvarMain” track.
  6. Drag the bar at the bottom edge of the track to resize it.“hg38-clinvarMain”.
  7. Track menu → Filter by... → add the expressionThis figure filters on `get(feature,'phenotypeList')=='LACTASE PERSISTENCE'`.“hg38-clinvarMain”.
  8. 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 “LCT lactase-persistence LD, 1000G European panel (r²)”.
  9. 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)”.
  10. Drag the bar at the bottom edge of the track to resize it.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  11. Click Force load in the track's "Zoom in to see features or force load" message.Loads the region even past the byte-size limit, which can be slow.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  12. Drag the bottom edge of the band of connecting lines above the rows to resize it.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  13. Track menu → Rendering mode → PhasedSplits each sample into one row per haplotype. The item stays disabled until phased variants are found in the file.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  14. 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.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  15. 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,000,000-136,150,000, which is what the row order reflects even after navigating elsewhere.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  16. Track menu → Color by... → Samples → PopulationThe Samples section lists whichever metadata columns your samples carry, so "population" appears only if yours have it.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  17. Track menu → Filter by... → Minor allele frequency → 0.35Hides variants whose minor allele frequency is below this.“1000 Genomes haplotypes across LCT (one row per haplotype)”.
  18. Type your region of interest into the location box and press Enter.This figure is at chr2:134,400,000-136,900,000.
  19. 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.

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=https%3A%2F%2Fjbrowse.org%2Fucsc%2Fhg38%2Fconfig.json&session=spec-%7B%22sessionTracks%22%3A%5B%7B%22type%22%3A%22VariantTrack%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%22VcfTabixAdapter%22%2C%22uri%22%3A%22https%3A%2F%2Fjbrowse.org%2Fdemos%2Fpopgen%2Flct_1kg38_chr2_eur_wide.vcf.gz%22%7D%2C%22displays%22%3A%5B%7B%22type%22%3A%22LDDisplay%22%2C%22showLDTriangle%22%3Atrue%2C%22showLegend%22%3Atrue%2C%22forceLoad%22%3Atrue%2C%22minorAlleleFrequencyFilter%22%3A0.35%2C%22useGenomicPositions%22%3Atrue%2C%22height%22%3A260%7D%5D%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%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%3A70%2C%22jexlFiltersSetting%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%22LDDisplay%22%7D%2C%7B%22trackId%22%3A%22kgp_lct_haplotypes%22%2C%22type%22%3A%22LinearMultiSampleVariantMatrixDisplay%22%2C%22height%22%3A520%2C%22forceLoad%22%3Atrue%2C%22lineZoneHeight%22%3A34%2C%22renderingMode%22%3A%22phased%22%2C%22runClustering%22%3Atrue%2C%22clusterRegion%22%3A%22chr2%3A135%2C000%2C000-136%2C150%2C000%22%2C%22colorBy%22%3A%22population%22%2C%22minorAlleleFrequencyFilter%22%3A0.35%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+ld%2Flct_haploblock

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-json '{
  "type": "VariantTrack",
  "trackId": "kgp_lct_ld",
  "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur_wide.vcf.gz"
  },
  "displays": [
    {
      "type": "LDDisplay",
      "showLDTriangle": true,
      "showLegend": true,
      "forceLoad": true,
      "minorAlleleFrequencyFilter": 0.35,
      "useGenomicPositions": true,
      "height": 260
    }
  ]
}'

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"
    }
  }
}'

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 Session spec tab, or jbrowse set-default-session.

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

{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_ld",
      "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur_wide.vcf.gz"
      },
      "displays": [
        {
          "type": "LDDisplay",
          "showLDTriangle": true,
          "showLegend": true,
          "forceLoad": true,
          "minorAlleleFrequencyFilter": 0.35,
          "useGenomicPositions": true,
          "height": 260
        }
      ]
    },
    {
      "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"
        }
      }
    }
  ],
  "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": 70,
          "jexlFiltersSetting": [
            "jexl:get(feature,'phenotypeList')=='LACTASE PERSISTENCE'"
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "type": "LDDisplay"
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "type": "LinearMultiSampleVariantMatrixDisplay",
          "height": 520,
          "forceLoad": true,
          "lineZoneHeight": 34,
          "renderingMode": "phased",
          "runClustering": true,
          "clusterRegion": "chr2:135,000,000-136,150,000",
          "colorBy": "population",
          "minorAlleleFrequencyFilter": 0.35
        }
      ]
    }
  ]
}

Loaded against config: https://jbrowse.org/ucsc/hg38/config.json

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

from jbrowse_anywidget import LinearGenomeView, fetch_hub

view = LinearGenomeView(
    assembly=fetch_hub("hg38"),
    location="chr2:134,400,000-136,900,000",
)

view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_1",
    "name": "My track 1",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "FeatureTrack",
    "trackId": "my_track_2",
    "name": "My track 2",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "BamAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track_3",
    "name": "My track 3",
    "assemblyNames": ["hg38"],
    "adapter": {"type": "VcfTabixAdapter", "uri": "https://your-server/your-file"},
})
view.add_track({
    "type": "VariantTrack",
    "trackId": "my_track_4",
    "name": "My track 4",
    "assemblyNames": ["hg38"],
    "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'
{
  "sessionTracks": [
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_ld",
      "name": "LCT lactase-persistence LD, 1000G European panel (r²)",
      "assemblyNames": [
        "hg38"
      ],
      "adapter": {
        "type": "VcfTabixAdapter",
        "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_eur_wide.vcf.gz"
      },
      "displays": [
        {
          "type": "LDDisplay",
          "showLDTriangle": true,
          "showLegend": true,
          "forceLoad": true,
          "minorAlleleFrequencyFilter": 0.35,
          "useGenomicPositions": true,
          "height": 260
        }
      ]
    },
    {
      "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"
        }
      }
    }
  ],
  "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": 70,
          "jexlFiltersSetting": [
            "jexl:get(feature,'phenotypeList')=='LACTASE PERSISTENCE'"
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "type": "LDDisplay"
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "type": "LinearMultiSampleVariantMatrixDisplay",
          "height": 520,
          "forceLoad": true,
          "lineZoneHeight": 34,
          "renderingMode": "phased",
          "runClustering": true,
          "clusterRegion": "chr2:135,000,000-136,150,000",
          "colorBy": "population",
          "minorAlleleFrequencyFilter": 0.35
        }
      ]
    }
  ]
}
JSON

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

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:

{
  "type": "VariantTrack",
  "trackId": "variants_ld",
  "name": "Variants with LD",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/variants.vcf.gz"
  },
  "displays": [{ "type": "LDDisplay" }]
}
jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "variants_ld",
  "name": "Variants with LD",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/variants.vcf.gz"
  },
  "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",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "VcfTabixAdapter",
    "uri": "https://yourhost/variants.vcf.gz"
  },
  "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 carries 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.

{
  "type": "LDTrack",
  "trackId": "ld_plink",
  "name": "Linkage disequilibrium",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "PlinkLDTabixAdapter",
    "uri": "https://yourhost/study.ld.gz"
  }
}
jbrowse add-track-json '{
  "type": "LDTrack",
  "trackId": "ld_plink",
  "name": "Linkage disequilibrium",
  "assemblyNames": ["hg38"],
  "adapter": {
    "type": "PlinkLDTabixAdapter",
    "uri": "https://yourhost/study.ld.gz"
  }
}'

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

Which metric, and how far to thin

ldMetric switches between two reads of the same block:

  • D' asks 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 is what finds an inversion's breakpoints
  • r² asks how well one marker predicts the other, which also requires the two to be at similar frequency, so it draws the sharper boundary. It says whether one marker can stand in for another

minorAlleleFrequencyFilter thins a dense callset 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