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 encoding.color; a multi-sample VCF draws its genotypes as rows under the records, and an LD track draws a cohort's linkage.

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

Edits config.json in the current folder. See JBrowse CLI with Desktop.

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

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

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

Edits config.json in the current folder. See JBrowse CLI with Desktop.

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

Variant display configuration

LinearVariantDisplay draws the records as a feature track does and, under them, a multi-sample VCF's genotypes, one row per sample, each variant at its genomic position or, with variantLayout: 'columns', in equal-width columns. Preset its slots in a displays array; they are listed on LinearVariantDisplay.

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": "LinearVariantDisplay",
      "genotypes": { "reference": { "show": true } },
      "filter": [{ "field": "minorAlleleFrequency", "gte": 0.05 }],
      "rows": { "field": "sample", "axis": { "labels": true } }
    }
  ]
}

Edits config.json in the current folder. See JBrowse CLI with Desktop.

jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearVariantDisplay",
      "genotypes": { "reference": { "show": true } },
      "filter": [{ "field": "minorAlleleFrequency", "gte": 0.05 }],
      "rows": { "field": "sample", "axis": { "labels": true } }
    }
  ]
}'

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": "LinearVariantDisplay",
      "genotypes": { "reference": { "show": true } },
      "filter": [{ "field": "minorAlleleFrequency", "gte": 0.05 }],
      "rows": { "field": "sample", "axis": { "labels": true } }
    }
  ]
}
  • genotypes.reference.show on paints reference alleles too; off (the default) leaves the row solid gray with only ALT alleles on top, which keeps overlapping variants readable
  • rows.field is sample (one row per sample, darker for homozygous) or haplotype (one row per phased haplotype, named <sample> HP1, <sample> HP2, counting from 1). Each haplotype row is matched to its sample's name, so the rest of rows applies in both modes
  • filter is a list of field tests: minorAlleleFrequency with gte hides variants below an allele-frequency floor, missingness with lte hides those above a no-call ceiling, and a jexl: string is an expression a variant must pass

Coloring cells by the variant

encoding.color paints every cell with an alt allele by the variant itself. A value, 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": "LinearVariantDisplay",
      "encoding": { "color": "impact" }
    }
  ]
}

Edits config.json in the current folder. See JBrowse CLI with Desktop.

jbrowse add-track-json '{
  "type": "VariantTrack",
  "trackId": "diversity_panel",
  "name": "Diversity Panel",
  "uri": "https://yourhost/diversity.vcf.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearVariantDisplay",
      "encoding": { "color": "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": "LinearVariantDisplay",
      "encoding": { "color": "impact" }
    }
  ]
}

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

"displays": [
  {
    "type": "LinearVariantDisplay",
    "encoding": {
      "color": {
        "field": "INFO.AF",
        "scale": {
          "type": "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

rows.color on the display names one of those columns, and each distinct value gets a different 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": "LinearVariantDisplay",
      "rows": { "color": "population" }
    }
  ]
}

Edits config.json in the current folder. See JBrowse CLI with Desktop.

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": "LinearVariantDisplay",
      "rows": { "color": "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": "LinearVariantDisplay",
      "rows": { "color": "population" }
    }
  ]
}
  • A column rows.color 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 LCT/MCM6 over the haplotype matrix it summarises.
Open in JBrowse Web ↗

Large dataset: slow to open.

Or rebuild it from your own data:

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

From scratch:

  1. Open your genome: Open your own genome in JBrowse Desktop, or jbrowse add-assembly for JBrowse Web.This figure uses hg38, loaded from a .2bit genome.
  2. Add your track: File → Open track..., or check it in the track selector. Needs a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi).This figure uses “NCBI RefSeq - RefSeq Curated”.
    1. Track menu → Filter by → Genes → Only genesGenes counts every gene, transcript and RNA type, the configured transcript and container types, and a top-level CDS; the rest of a GFF, such as NCBI region and match rows, is not a gene.
  3. Add the next track the same way. Needs a BigBed file (.bb).This figure uses “ClinVar Variants - ClinVar SNVs”.
    1. Track menu → Filter by → Edit filters...
  4. Add the next track the same way. Needs a tabix-indexed PLINK LD file (.ld.gz + .tbi).This figure uses “LCT lactase-persistence LD, 1000G European panel (r²)”.
  5. Add the next track the same way. 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 genotype...Orders the rows by how alike they are across the region in view, and draws the tree it built beside them. This figure clusters over chr2:135,787,850-135,876,467: zoom there, run it, then zoom back out, and the order holds.
  6. Go to your region in the location box.This figure is at chr2:134,400,000-136,900,000.
  7. Drag a selection across the ruler → Highlight regionThis figure highlights 1 region; highlights can also be set with the &highlight= URL parameter.

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

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

Start from this JBrowse view.
- Config it loads: https://jbrowse.org/ucsc/hg38/config.json
- Tracks:
  - NCBI RefSeq - RefSeq Curated (hg38-ncbiRefSeqCurated), FeatureTrack, a bgzip-compressed, tabix-indexed GFF3 (.gff.gz + .tbi), drawn as LinearBasicDisplay
  - ClinVar Variants - ClinVar SNVs (hg38-clinvarMain), FeatureTrack, a BigBed file (.bb), drawn as LinearBasicDisplay
  - LCT lactase-persistence LD, 1000G European panel (r²) (kgp_lct_ld), LDTrack, a tabix-indexed PLINK LD file (.ld.gz + .tbi), drawn as LDTrackDisplay
  - 1000 Genomes haplotypes across LCT (one row per haplotype) (kgp_lct_haplotypes), VariantTrack, a bgzip-compressed, tabix-indexed VCF (.vcf.gz + .tbi), drawn as LinearVariantDisplay

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

The session spec that draws the view:
{
  "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",
        "csi": true
      },
      "displayDefaults": {
        "variantLayout": "genomic",
        "legend": {
          "show": true
        },
        "height": 360
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_haplotypes",
      "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
      "assemblyNames": [
        "hg38"
      ],
      "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
      "csi": true,
      "displays": [
        {
          "type": "LinearVariantDisplay",
          "variantLayout": "columns",
          "rows": "haplotype",
          "filter": [
            {
              "field": "minorAlleleFrequency",
              "gte": 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",
          "height": 60,
          "filter": [
            "geneLike"
          ]
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 56,
          "filter": [
            {
              "field": "phenotypeList",
              "equal": "LACTASE PERSISTENCE"
            }
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "height": 260
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "height": 520,
          "connectors": {
            "height": 34
          },
          "runClustering": true,
          "clusterRegion": "chr2:135,787,850-135,876,467"
        }
      ]
    }
  ]
}
Redraw the figure headlessly
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",
        "csi": true
      },
      "displayDefaults": {
        "variantLayout": "genomic",
        "legend": {
          "show": true
        },
        "height": 360
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_haplotypes",
      "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
      "assemblyNames": [
        "hg38"
      ],
      "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
      "csi": true,
      "displays": [
        {
          "type": "LinearVariantDisplay",
          "variantLayout": "columns",
          "rows": "haplotype",
          "filter": [
            {
              "field": "minorAlleleFrequency",
              "gte": 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",
          "height": 60,
          "filter": [
            "geneLike"
          ]
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 56,
          "filter": [
            {
              "field": "phenotypeList",
              "equal": "LACTASE PERSISTENCE"
            }
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "height": 260
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "height": 520,
          "connectors": {
            "height": 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",
      "feature": "T>C",
      "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

More: Using JBrowse with AI agents.

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

jbrowse add-track-json '{
  "type": "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",
    "csi": true
  },
  "displayDefaults": {
    "variantLayout": "genomic",
    "legend": {
      "show": 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"
  ],
  "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
  "csi": true,
  "displays": [
    {
      "type": "LinearVariantDisplay",
      "variantLayout": "columns",
      "rows": "haplotype",
      "filter": [
        {
          "field": "minorAlleleFrequency",
          "gte": 0.35
        }
      ],
      "forceLoad": true,
      "height": 520,
      "connectors": {
        "height": 34
      }
    }
  ]
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-ncbiRefSeqCurated",
  "name": "NCBI RefSeq - RefSeq Curated",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "Gff3TabixAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 60,
    "filter": [
      "geneLike"
    ]
  }
}'

jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "hg38-clinvarMain",
  "name": "ClinVar Variants - ClinVar SNVs",
  "assemblyNames": [
    "hg38"
  ],
  "adapter": {
    "type": "BigBedAdapter",
    "uri": "YOUR_FILE"
  },
  "displayDefaults": {
    "height": 56,
    "filter": [
      {
        "field": "phenotypeList",
        "equal": "LACTASE PERSISTENCE"
      }
    ]
  }
}'

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

This view in a notebook, with jbrowse-anywidget. Swap a track's uri for your file.

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/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",
                "csi": True
            },
            "displayDefaults": {
                "variantLayout": "genomic",
                "legend": {
                    "show": True
                },
                "height": 360
            }
        },
        {
            "type": "VariantTrack",
            "trackId": "kgp_lct_haplotypes",
            "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
            "assemblyNames": [
                "hg38"
            ],
            "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
            "csi": True,
            "displays": [
                {
                    "type": "LinearVariantDisplay",
                    "variantLayout": "columns",
                    "rows": "haplotype",
                    "filter": [
                        {
                            "field": "minorAlleleFrequency",
                            "gte": 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",
                    "height": 60,
                    "filter": [
                        "geneLike"
                    ]
                },
                {
                    "trackId": "hg38-clinvarMain",
                    "height": 56,
                    "filter": [
                        {
                            "field": "phenotypeList",
                            "equal": "LACTASE PERSISTENCE"
                        }
                    ]
                },
                {
                    "trackId": "kgp_lct_ld",
                    "height": 260
                },
                {
                    "trackId": "kgp_lct_haplotypes",
                    "height": 520,
                    "connectors": {
                        "height": 34
                    },
                    "runClustering": True,
                    "clusterRegion": "chr2:135,787,850-135,876,467"
                }
            ]
        }
    ],
)
app  # display the widget

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

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

const configUrl = "https://jbrowse.org/ucsc/hg38/config.json"
const configPromise = fetch(configUrl)
  .then(res => res.json())
  .then(config => {
    addRelativeUris(config, new URL(configUrl))
    return config
  })

export default function Figure() {
  const config = use(configPromise)
  return (
    <JBrowse
      assemblies={config.assemblies}
      tracks={[...(config.tracks ?? []), ...[
          {
            "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",
              "csi": true
            },
            "displayDefaults": {
              "variantLayout": "genomic",
              "legend": {
                "show": true
              },
              "height": 360
            }
          },
          {
            "type": "VariantTrack",
            "trackId": "kgp_lct_haplotypes",
            "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
            "assemblyNames": [
              "hg38"
            ],
            "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
            "csi": true,
            "displays": [
              {
                "type": "LinearVariantDisplay",
                "variantLayout": "columns",
                "rows": "haplotype",
                "filter": [
                  {
                    "field": "minorAlleleFrequency",
                    "gte": 0.35
                  }
                ],
                "forceLoad": true,
                "height": 700
              }
            ]
          }
        ]]}
      aggregateTextSearchAdapters={config.aggregateTextSearchAdapters}
      configuration={config.configuration}
      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",
              "height": 60,
              "filter": [
                "geneLike"
              ]
            },
            {
              "trackId": "hg38-clinvarMain",
              "height": 56,
              "filter": [
                {
                  "field": "phenotypeList",
                  "equal": "LACTASE PERSISTENCE"
                }
              ]
            },
            {
              "trackId": "kgp_lct_ld",
              "height": 260
            },
            {
              "trackId": "kgp_lct_haplotypes",
              "height": 520,
              "connectors": {
                "height": 34
              },
              "runClustering": true,
              "clusterRegion": "chr2:135,787,850-135,876,467"
            }
          ]
        }
      ]}
    />
  )
}

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

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",
      "csi": true
    },
    "displayDefaults": {
      "variantLayout": "genomic",
      "legend": {
        "show": true
      },
      "height": 360
    }
  },
  {
    "type": "VariantTrack",
    "trackId": "kgp_lct_haplotypes",
    "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
    "assemblyNames": [
      "hg38"
    ],
    "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
    "csi": true,
    "displays": [
      {
        "type": "LinearVariantDisplay",
        "variantLayout": "columns",
        "rows": "haplotype",
        "filter": [
          {
            "field": "minorAlleleFrequency",
            "gte": 0.35
          }
        ],
        "forceLoad": true,
        "height": 700
      }
    ]
  }
]
JSON

npx @jbrowse/img --config https://jbrowse.org/ucsc/hg38/config.json \
  --trackConfigs tracks.json \
  --assembly hg38 --loc chr2:134,400,000-136,900,000 \
  --view '{"highlight":[{"refName":"chr2","start":135787850,"end":135876467,"assemblyName":"hg38"}]}' \
  --track hg38-ncbiRefSeqCurated '{"height":60,"filter":["geneLike"]}' \
  --track hg38-clinvarMain '{"height":56,"filter":[{"field":"phenotypeList","equal":"LACTASE PERSISTENCE"}]}' \
  --track kgp_lct_ld '{"height":260}' \
  --track kgp_lct_haplotypes '{"height":520,"connectors":{"height":34},"runClustering":true,"clusterRegion":"chr2:135,787,850-135,876,467"}' \
  --width 1500 --out figure.svg

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

The session spec behind the figure, over this config.

{
  "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",
        "csi": true
      },
      "displayDefaults": {
        "variantLayout": "genomic",
        "legend": {
          "show": true
        },
        "height": 360
      }
    },
    {
      "type": "VariantTrack",
      "trackId": "kgp_lct_haplotypes",
      "name": "1000 Genomes haplotypes across LCT (one row per haplotype)",
      "assemblyNames": [
        "hg38"
      ],
      "uri": "https://jbrowse.org/demos/popgen/lct_1kg38_chr2_6pop.vcf.gz",
      "csi": true,
      "displays": [
        {
          "type": "LinearVariantDisplay",
          "variantLayout": "columns",
          "rows": "haplotype",
          "filter": [
            {
              "field": "minorAlleleFrequency",
              "gte": 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",
          "height": 60,
          "filter": [
            "geneLike"
          ]
        },
        {
          "trackId": "hg38-clinvarMain",
          "height": 56,
          "filter": [
            {
              "field": "phenotypeList",
              "equal": "LACTASE PERSISTENCE"
            }
          ]
        },
        {
          "trackId": "kgp_lct_ld",
          "height": 260
        },
        {
          "trackId": "kgp_lct_haplotypes",
          "height": 520,
          "connectors": {
            "height": 34
          },
          "runClustering": true,
          "clusterRegion": "chr2:135,787,850-135,876,467"
        }
      ]
    }
  ]
}

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

Edits config.json in the current folder. See JBrowse CLI with Desktop.

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

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

encoding.color.field switches between two reads of the same block, r2 on a red ramp and dprime on a blue one unless encoding.color.scale.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

A threshold scale cuts the statistic into intervals, each one color. These are LocusZoom's r² bins, the ones a GWAS track colors its points by (GWAS track), so a triangle under a Manhattan plot shares its key:

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

{
  "trackId": "ld_plink_bins",
  "name": "Linkage disequilibrium, r² bins",
  "uri": "https://yourhost/study.ld.gz",
  "assemblyNames": ["hg38"],
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "r2",
        "scale": {
          "type": "threshold",
          "domain": ["0.2", "0.4", "0.6", "0.8"],
          "range": ["#357ebd", "#46b8da", "#5cb85c", "#eea236", "#d43f3a"]
        },
        "legend": { "descending": true }
      }
    }
  }
}

Edits config.json in the current folder. See JBrowse CLI with Desktop.

jbrowse add-track https://yourhost/study.ld.gz \
  --trackId ld_plink_bins \
  --name "Linkage disequilibrium, r² bins" \
  --assemblyNames hg38 \
  --displayDefaults '{"encoding":{"color":{"field":"r2","scale":{"type":"threshold","domain":["0.2","0.4","0.6","0.8"],"range":["#357ebd","#46b8da","#5cb85c","#eea236","#d43f3a"]},"legend":{"descending":true}}}}'

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_bins",
  "name": "Linkage disequilibrium, r² bins",
  "uri": "https://yourhost/study.ld.gz",
  "assemblyNames": ["hg38"],
  "displayDefaults": {
    "encoding": {
      "color": {
        "field": "r2",
        "scale": {
          "type": "threshold",
          "domain": ["0.2", "0.4", "0.6", "0.8"],
          "range": ["#357ebd", "#46b8da", "#5cb85c", "#eea236", "#d43f3a"]
        },
        "legend": { "descending": true }
      }
    }
  }
}

Clicking a cell makes its SNP the index SNP: its row and column of the triangle light up, its LD to every other variant. Click empty space, or use Clear index SNP in the track menu, to clear it.

Thinning is set by plink's --maf when the table is written, reducing the dense callset to the common, block-tagging variants. A --maf high enough to remove the tagging variants themselves makes the block fade. 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