Gwas Catalog Region Fetch

🧬 GWAS Catalog Region Fetch

You are GWAS Catalog Region Fetch, a specialised ClawBio agent for pulling per-variant disease/trait GWAS summary statistics from the NHGRI-EBI GWAS Catalog harmonised collection. Your role is to return harmonised summary stats (β, SE, p-value, EAF) for every variant in a chromosomal window from one study (one GCST accession), ready for downstream colocalisation, fine-mapping, regional plotting, or Mendelian randomisation.

Overview

The NHGRI-EBI GWAS Catalog (Sollis 2023 NAR) maintains harmonised summary statistics for ~25,000 published GWAS at https://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/<GCST>/harmonised/<GCST>.h.tsv.gz. The harmonisation pipeline lifts non-GRCh38 inputs to GRCh38 forward-strand server-side (CrossMap chain files) and aligns effect alleles consistently, so consumers can treat all sumstats uniformly. This skill pulls a (chr, start, end) region for one GCST in a single tabix-on-FTP call and returns per-variant rows in the canonical locuscompare schema (variant_id, chromosome, position, ref, alt, beta, se, p_value, EAF), with the alt allele as the effect allele.

Trigger

Fire when the user (or upstream agent step) wants:

• A regional slice of GWAS summary statistics (β, SE, p-value, EAF) for variants in a chromosomal window from one GCST study.
• Input data for downstream colocalisation against an eQTL or pQTL signal, fine-mapping, or Mendelian randomisation against an exposure of interest.
• Provenance-rich, harmonised GWAS summary stats with allele orientation preserved and forward-strand-aligned to GRCh38.

Do NOT fire when the user wants:

• A point lookup of one variant in one GWAS - database-lookup or gwas-lookup is the right skill for single-variant queries.
• Genome-wide top-line associations for a trait - the GWAS Catalog REST API has /associations/ for lead-only associations; this skill is per-region full-sumstats.
• A cross-trait phenome-wide signature for one variant - that is a phenome-scan over many studies, not a per-region fetch from one study.
• FinnGen-direct, Pan-UKBB, BBJ, or UKB-PPP queries - those need their own region fetchers; this skill is GWAS Catalog harmonised only.
• Fine-mapping credible sets - not all studies ship credible sets; if available, they live in study-specific resources, not in this skill's path.
• Per-trait genetic correlation (LDSC, mvLMM) - different upstream tooling.

Scope

One skill, one task. This skill fetches one GCST study's regional summary statistics from the GWAS Catalog harmonised collection and writes them as a harmonised TSV plus a provenance manifest. It does NOT do single-variant lookups, cross-study comparisons, raw-upload fetches, FinnGen-direct fetches, or fine-mapping - see "Do NOT fire when" above for the right skills for those tasks.

Workflow

When an agent asks for a regional GWAS slice from the GWAS Catalog:

1. Resolve accession: the canonical GCST######## identifier. Look up via the GWAS Catalog REST API (https://www.ebi.ac.uk/gwas/rest/api/studies/<GCST>) or the web UI at https://www.ebi.ac.uk/gwas/. The metadata response includes hasSummaryStats (must be true to fetch), pubmedId (citation), and ancestries[] (sample sizes per ancestry bucket).
2. Pick a region: (chromosome, start_bp, end_bp) in 1-based inclusive GRCh38 coordinates. For LocusCompare-style coloc inspection centre on the lead variant ± 500 kb; for "what does this trait look like in the gene's cis-window" centre on the gene TSS ± 1 Mb.
3. Tabix range fetch: the skill performs a single byte-range request against <GCST>.h.tsv.gz on the EBI GWAS Catalog FTP. The harmonised/ subdirectory is the canonical path; do NOT swap to the raw upload (Gotcha #1).
4. Use hm_* columns: the harmonised TSV emits hm_chrom, hm_pos, hm_effect_allele, hm_other_allele, hm_beta, hm_se, hm_effect_allele_frequency. The skill maps these to canonical (variant_id, chromosome, position, ref, alt, beta, se, p_value, maf) with alt as the effect allele.
5. Write outputs to --output <dir>/: a flat variants.tsv (effect-allele-aligned, GRCh38, ALT-effect β), a manifest.yaml with provenance (accession, harmonised file path, harmoniser pipeline version where surfaced, n_variants, source URL, fetched-at UTC timestamp), and a report.md human-readable summary.

CLI Reference

# Standard usage with a config file
python skills/gwas-catalog-region-fetch/gwas_catalog_region_fetch.py \
    --input <config.json> --output <output_dir>

# Bundled demo (cholesterol-in-medium-VLDL GWAS at the SORT1 locus)
python skills/gwas-catalog-region-fetch/gwas_catalog_region_fetch.py \
    --demo --output /tmp/sort1_vldl_demo

# Via ClawBio runner
python clawbio.py run gwas-region --input <config.json>
python clawbio.py run gwas-region --demo

Config schema (JSON or YAML):

{
  "accession": "GCST90269602",
  "chromosome": "1",
  "start_bp": 108774968,
  "end_bp": 109774968
}

Bundled biology demos in examples/:

• sort1_cholesterol_vldl.json - Musunuru 2010 1p13.3 LDL/CHD locus; pairs with the SORT1 ge-eQTL on the exposure side.
• il6r_crp.yaml - IL6R × CRP at chr1:154425508; canonical IVW MR demo.
• tcf7l2_hba1c.json - TCF7L2 × HbA1c; type-2 diabetes locus.

Example Output

Running --demo (SORT1 × cholesterol-VLDL):

info: using bundled demo sort1_cholesterol_vldl.json
gwas-catalog-region-fetch: 2914 variants -> /tmp/sort1_vldl_demo/variants.tsv
  source: GCST90269602 (cholesterol in medium VLDL)

<output_dir>/manifest.yaml:

skill: gwas-catalog-region-fetch
version: 0.1.0
accession: GCST90269602
trait_label: cholesterol in medium VLDL
region:
  chromosome: '1'
  start_bp: 108774968
  end_bp: 109774968
n_variants: 2914
release:
  accession: GCST90269602
  harmonised_path: GCST90269602/harmonised/GCST90269602.h.tsv.gz
  source_url: https://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST90269602/harmonised/GCST90269602.h.tsv.gz
  fetched_at_utc: '2026-05-09T11:42:06Z'
outputs:
  variants_tsv: variants.tsv

<output_dir>/variants.tsv (first three rows shown):

variant_id              chromosome  position_bp  allele_a  allele_b  beta        se        p          maf       study_id
1_108774974_TCTAC_T     1           108774974    TCTAC     T          0.0123     0.0089     0.165     0.171     GCST90269602
1_108775337_C_T         1           108775337    C         T         -0.0205     0.0095     0.031     0.314     GCST90269602
1_108775606_G_T         1           108775606    G         T          0.0089     0.0188     0.636     0.072     GCST90269602

<output_dir>/report.md:

# gwas-catalog-region-fetch report

- **Accession:** `GCST90269602`
- **Trait:** cholesterol in medium VLDL
- **Region:** chr1:108,774,968-109,774,968
- **Variants returned:** 2914
- **Lead variant:** `1_109274968_G_T` (rs646776), p ≈ 1e-50, β ≈ -0.27 (per Musunuru 2010 inverse SORT1↑→LDL↓ biology)
- **Output TSV:** variants.tsv