Skip to main content

GWAS track

A GWASTrack renders association results as a Manhattan plot. The main work is prep: a bgzipped, tabix-indexed BED-like file whose score column is in -log₁₀(p) units (or set scoreTransform to convert). Add a PLINK .ld file to color points by linkage disequilibrium to an index SNP. The plot is a mark display whose default plot is a point per SNP at its score, so its marks, scales, facets and rows all apply, and any FeatureTrack can draw the same plot from one of its numeric columns — see any scored feature file.

A GWAS track rendered as a Manhattan plot: each point is a variant, plotted by genomic position (X) and -log₁₀(p-value) (Y), so association peaks rise above the background.
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=test_data%2Fconfig_gwas.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22hg19%22%2C%22loc%22%3A%222%22%2C%22tracks%22%3A%5B%7B%22trackId%22%3A%22gwas_track%22%2C%22type%22%3A%22LinearManhattanDisplay%22%2C%22height%22%3A250%7D%5D%7D%5D%7D&sessionName=JBrowse+docs%3A+gwas%2Fmanhattan

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 hg19, loaded from a bgzip-compressed FASTA (.fa.gz + .fai + .gzi).
  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 figure uses “GWAS”.
  3. Type your region of interest into the location box and press Enter.This figure is at 2.

This session spec draws the figure. It goes after &session=spec- on a JBrowse Web link that loads https://jbrowse.org/code/jb2/main/test_data/config_gwas.json, which is what the Web button above opens.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "2",
      "tracks": [
        {
          "trackId": "gwas_track",
          "type": "LinearManhattanDisplay",
          "height": 250
        }
      ]
    }
  ]
}

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/code/jb2/main/test_data/config_gwas.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "hg19",
            "loc": "2",
            "tracks": [
                {
                    "trackId": "gwas_track",
                    "type": "LinearManhattanDisplay",
                    "height": 250
                }
            ]
        }
    ],
)
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.

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/config_gwas.json \
  --assembly hg19 --loc 2 \
  --track gwas_track display:LinearManhattanDisplay '{"height":250}' \
  --width 1500 --out figure.svg

--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'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "hg19",
      "loc": "2",
      "tracks": [
        {
          "trackId": "gwas_track",
          "type": "LinearManhattanDisplay",
          "height": 250
        }
      ]
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/config_gwas.json \
  --width 1500 --height 470 \
  --timeout 90000 \
  --spec 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.

Preparing the GWAS file

GWASAdapter reads a bgzipped, tabix-indexed BED-like file with a #-prefixed header row whose score column is in -log₁₀(p) units. scoreTransform converts a raw p-value column (negLog10) or a natural-log one (negLog10FromLn, a Pan-UKBB ln P column) at read time. The name column (4th BED field) is the SNP id LD lookups key on; without it they fall back to chr:bp (1-based).

#chrom  chromStart  chromEnd  name      neg_log_pvalue
chr1    109817590   109817591 rs4970383 1.234
chr1    110162459   110162460 rs4971059 7.891

Prefix the header so tabix skips it, then sort, bgzip and index:

sed '1s/^/#/' results.tsv | jbrowse sort-bed | bgzip > results.sorted.txt.gz
tabix -p bed results.sorted.txt.gz

jbrowse sort-bed is sort -k1,1 -k2,2n under LC_ALL=C with every # line kept on top. A .txt.gz auto-detects as GWASAdapter in the Add track dialog; another extension such as .bed.gz needs the adapter picked by hand.

Preparing the LD file

LD data is PLINK's --r2 table, from a binary fileset (--bfile study) or a VCF (--vcf study.vcf.gz):

# "dprime" adds the D' column (DP)
plink --bfile study --r2 dprime with-freqs \
  --ld-window 99999 --ld-window-kb 1000 --ld-window-r2 0 \
  --out study
  • --ld-window-r2 0 keeps every pair; PLINK otherwise drops pairs below r²=0.2. The --ld-window* flags bound how far apart paired SNPs may be, so tune them to the span you want drawn
  • dprime also switches r² to the haplotype-frequency estimate, so the R2 column of a run with it and a run without it are two different statistics
  • This is PLINK 1.9; plink2 replaced --r2 with --r2-phased and --r2-unphased

A regional study.ld loads as-is with PlinkLDAdapter. For chromosome-scale or genome-wide LD, bgzip and tabix it and use PlinkLDTabixAdapter, which fetches only the pairs in view; its page has the retab, sort-bed and tabix commands and why the header is commented with #.

Example

A plot naming r2 or ld_role joins each SNP's r² to the index SNP from the GWASAdapter's ldAdapter; swap in PlinkLDTabixAdapter for an indexed .ld.gz. The first mark below colors every other point by r² in LocusZoom's five bins, and the second draws the index SNP alone as a pink diamond on top. The track menu's LD → Color by LD to index SNP makes the same pair of each point mark of the plot, keeping its size, steps and the other marks, and right-clicking a point pins it as the index (LinearManhattanDisplay):

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

{
  "type": "GWASTrack",
  "trackId": "sle_gwas",
  "name": "SLE GWAS",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "GWASAdapter",
    "uri": "https://yourhost/sle.bed.gz",
    "scoreColumn": "neg_log_pvalue",
    "ldAdapter": {
      "type": "PlinkLDAdapter",
      "uri": "https://yourhost/sle.ld"
    }
  },
  "displayDefaults": {
    "marks": [
      {
        "mark": "point",
        "transform": [
          { "type": "filter", "expr": "jexl:feature.ld_role != 'index'" }
        ],
        "encoding": {
          "y": "score",
          "color": {
            "field": "r2",
            "scale": "threshold",
            "domain": [0.2, 0.4, 0.6, 0.8],
            "range": ["#357ebd", "#46b8da", "#5cb85c", "#eea236", "#d43f3a"],
            "title": "r² to index SNP",
            "descending": true,
            "missingLabel": "No LD data"
          }
        }
      },
      {
        "mark": "point",
        "transform": [
          { "type": "filter", "expr": "jexl:feature.ld_role == 'index'" }
        ],
        "encoding": {
          "y": "score",
          "color": { "value": "#c951c9" },
          "shape": {
            "field": "ld_role",
            "domain": ["index"],
            "range": ["diamond"],
            "labels": ["Index SNP"],
            "title": ""
          }
        }
      }
    ]
  }
}
jbrowse add-track-json '{
  "type": "GWASTrack",
  "trackId": "sle_gwas",
  "name": "SLE GWAS",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "GWASAdapter",
    "uri": "https://yourhost/sle.bed.gz",
    "scoreColumn": "neg_log_pvalue",
    "ldAdapter": {
      "type": "PlinkLDAdapter",
      "uri": "https://yourhost/sle.ld"
    }
  },
  "displayDefaults": {
    "marks": [
      {
        "mark": "point",
        "transform": [
          { "type": "filter", "expr": "jexl:feature.ld_role != '\''index'\''" }
        ],
        "encoding": {
          "y": "score",
          "color": {
            "field": "r2",
            "scale": "threshold",
            "domain": [0.2, 0.4, 0.6, 0.8],
            "range": ["#357ebd", "#46b8da", "#5cb85c", "#eea236", "#d43f3a"],
            "title": "r² to index SNP",
            "descending": true,
            "missingLabel": "No LD data"
          }
        }
      },
      {
        "mark": "point",
        "transform": [
          { "type": "filter", "expr": "jexl:feature.ld_role == '\''index'\''" }
        ],
        "encoding": {
          "y": "score",
          "color": { "value": "#c951c9" },
          "shape": {
            "field": "ld_role",
            "domain": ["index"],
            "range": ["diamond"],
            "labels": ["Index SNP"],
            "title": ""
          }
        }
      }
    ]
  }
}'

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": "GWASTrack",
  "trackId": "sle_gwas",
  "name": "SLE GWAS",
  "assemblyNames": ["hg19"],
  "adapter": {
    "type": "GWASAdapter",
    "uri": "https://yourhost/sle.bed.gz",
    "scoreColumn": "neg_log_pvalue",
    "ldAdapter": {
      "type": "PlinkLDAdapter",
      "uri": "https://yourhost/sle.ld"
    }
  },
  "displayDefaults": {
    "marks": [
      {
        "mark": "point",
        "transform": [
          { "type": "filter", "expr": "jexl:feature.ld_role != 'index'" }
        ],
        "encoding": {
          "y": "score",
          "color": {
            "field": "r2",
            "scale": "threshold",
            "domain": [0.2, 0.4, 0.6, 0.8],
            "range": ["#357ebd", "#46b8da", "#5cb85c", "#eea236", "#d43f3a"],
            "title": "r² to index SNP",
            "descending": true,
            "missingLabel": "No LD data"
          }
        }
      },
      {
        "mark": "point",
        "transform": [
          { "type": "filter", "expr": "jexl:feature.ld_role == 'index'" }
        ],
        "encoding": {
          "y": "score",
          "color": { "value": "#c951c9" },
          "shape": {
            "field": "ld_role",
            "domain": ["index"],
            "range": ["diamond"],
            "labels": ["Index SNP"],
            "title": ""
          }
        }
      }
    ]
  }
}

Any scored feature file

LinearManhattanDisplay is also a display of FeatureTrack, so a selection scan, a QTL table or any BED-like file with a numeric column draws as a Manhattan plot without a GWASTrack or a GWASAdapter. Name the display in the track's displays (it is also offered under the track menu's Display types), and its point mark chooses what it reads:

  • encoding.y — the column plotted as y. The default score is the BED score column (or what the adapter's scoreColumn rewrote it to); an explicit name reaches a raw column of the file. A feature with no finite value there is skipped.
  • encoding.color: { "field": "population" } — gives each distinct value of a column its own color and draws a key of the values met. A value takes the same color in every region and session. Its domain is the order those values take, in the key and in the colors: the values it lists come first, in that order, and the rest follow sorted, and range hands them colors.

The track menu's Edit plot... edits both, and encoding.size is the point diameter in px. A point stands at the middle of its window; "mark": "rule" draws the window across its extent, encoding.size px thick.

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

{
  "type": "FeatureTrack",
  "trackId": "fst_scan",
  "name": "Fst scan",
  "uri": "https://yourhost/fst.bed.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearManhattanDisplay",
      "marks": [
        {
          "mark": "point",
          "encoding": { "y": "fst", "color": { "field": "population" } }
        }
      ],
      "scales": { "y": { "rules": [0.25] } }
    }
  ]
}
jbrowse add-track-json '{
  "type": "FeatureTrack",
  "trackId": "fst_scan",
  "name": "Fst scan",
  "uri": "https://yourhost/fst.bed.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearManhattanDisplay",
      "marks": [
        {
          "mark": "point",
          "encoding": { "y": "fst", "color": { "field": "population" } }
        }
      ],
      "scales": { "y": { "rules": [0.25] } }
    }
  ]
}'

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": "FeatureTrack",
  "trackId": "fst_scan",
  "name": "Fst scan",
  "uri": "https://yourhost/fst.bed.gz",
  "assemblyNames": ["hg38"],
  "displays": [
    {
      "type": "LinearManhattanDisplay",
      "marks": [
        {
          "mark": "point",
          "encoding": { "y": "fst", "color": { "field": "population" } }
        }
      ],
      "scales": { "y": { "rules": [0.25] } }
    }
  ]
}

See also