gwas-catalog-region-fetch

name: gwas-catalog-region-fetchdescription: |  Fetch a region of GWAS summary statistics from the NHGRI-EBI GWAS Catalog  harmonised collection via tabix-on-FTP. Use when an agent needs GWAS beta /  SE / p-value for every variant in a window for one specific study (GCST  accession). Input: accession, chromosome, start, end. Output: harmonised  TSV slice in canonical format.license: MITmetadata:   skill-author: Aviv Madar  version: 0.2.0  domain: bioinformatics  tags:     - gwas    - gwas-catalog    - region-fetch    - tabix    - summary-statistics    - harmonised  inputs:     - name: accession      type: string      description: GWAS Catalog study accession (e.g. GCST90269602 for cholesterol-VLDL).      required: true    - name: chromosome      type: string      description: Chromosome name without `chr` prefix.      required: true    - name: start_bp      type: integer      description: Region start, 1-based GRCh38.      required: true    - name: end_bp      type: integer      description: Region end, 1-based GRCh38 (inclusive).      required: true  outputs:     - name: variants      type: list      description: Per-variant rows with variant_id, chromosome, position, ref, alt, beta, se, p_value, odds_ratio with its ci_lower / ci_upper, allele frequencies.    - name: release      type: object      description: GWASCatalogRelease with accession, harmonised file path, fetched_at_utc.  dependencies:     - python>=3.10    - pysam>=0.22    - pandas>=2.0    - requests>=2.28  demo_data:     - examples/input.json  endpoints:     - https://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/    # tabix-on-FTP harmonised  openclaw:     requires:       bins:         - python3        - tabix      env:       config:     always: false    emoji: "🧬"    homepage: https://github.com/ClawBio/ClawBio    os:       - darwin      - linux    install: |      pip install pysam pandas requests    trigger_keywords:       - gwas region fetch      - gwas catalog region      - gwas sumstats slice      - GCST harmonised tabix      - GWAS catalog tabix

🧬 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 v2 (https://www.ebi.ac.uk/gwas/rest/api/v2/studies/<GCST>; the legacy v1 /gwas/rest/api/studies/ path is retired and returns HTTP 410) or the web UI at https://www.ebi.ac.uk/gwas/. The v2 metadata response includes full_summary_stats_available (must be true to fetch), pubmed_id (citation), and discovery_ancestry[] / initial_sample_size (sample sizes per ancestry); per-ancestry records are at /v2/studies/<GCST>/ancestries.
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.

Output Structure

<output_dir>/
├── report.md
├── variants.tsv
├── manifest.yaml            # manifest.json if PyYAML is missing
└── reproducibility/
    ├── commands.sh
    ├── environment.yml
    └── checksums.sha256     # verify: cd <output_dir> && sha256sum -c reproducibility/checksums.sha256

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.2.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

Gotchas

1. Use the harmonised/ subdirectory, not the raw upload path. <GCST>/harmonised/<GCST>.h.tsv.gz is forward-strand-aligned to GRCh38 with consistent allele orientation. The raw upload (one directory up) can be on GRCh37 with study-specific allele conventions, and is NOT what this skill fetches. Do NOT swap to the raw path.

2. hm_* columns are the canonical fields. The harmoniser emits hm_chrom, hm_pos, hm_effect_allele, hm_other_allele, hm_beta, hm_se, hm_effect_allele_frequency. Use these, not the raw-upload columns. The skill's manifest preserves both for traceability.

3. Per-study release lag. GWAS Catalog mirrors a study some time after the upstream release: typically 2-6 months for FinnGen R12 phenotypes; longer for studies that go through deposit-and-curate. If the user references a phenotype that should be in OT, verify presence via the GWAS Catalog API metadata before assuming an arbitrary GCST is fetchable.

4. Some studies do not have summary statistics deposited at all. Older or smaller GWAS may have only top-line lead associations but no full sumstats. The GWAS Catalog API exposes hasSummaryStats per study; check it before invoking. The fetcher raises GWASCatalogFetchError when the harmonised TSV or its .tbi is missing on FTP; caller decides whether to fall back (e.g. download the whole file + tabix-index locally - see references/harmonised_pipeline.md).

5. Palindromic SNPs at MAF near 0.5 are dropped by the harmoniser. A/T and G/C variants with EAF in [0.45, 0.55] cannot be reliably oriented across studies, so the harmoniser excludes them. Expect some variants present in OT credible sets to be missing from the harmonised file. Surface the count to the user when it materially affects the analysis.

6. β is reported on the ALT allele. Do NOT compare effect sizes across studies without explicit allele harmonisation. The skill preserves ref / alt columns; downstream tools (e.g., TwoSampleMR harmonise_data) flip signs when alleles are swapped. Cross-study sign-flip risk is real (references/effect_allele_harmonisation.md).

Safety

Not for clinical decisions. This skill returns research-grade GWAS summary statistics from public databases. Do not use the output for direct clinical decision-making, diagnosis, or treatment selection without independent validation by a qualified clinician.

Effect sizes can include winner's-curse bias. Variants discovered in the same GWAS that produced the summary stats have inflated effect-size estimates. Downstream causal-effect estimation (Mendelian randomisation) should use independent instruments or apply winner's-curse correction.

Effect estimates may not generalise across ancestries. The GWAS Catalog records each study's primary ancestry (ancestries[] block in the REST metadata); effect sizes from a single-ancestry cohort should not be assumed to apply trans-ancestrally without explicit harmonisation and validation.

Agent Boundary

The skill returns harmonised GWAS summary statistics (β, SE, p-value, EAF) for variants in a chromosomal window from one GCST study. The agent should:

• Use the output as input to colocalisation, fine-mapping, or Mendelian randomisation tooling. These are the appropriate downstream methods for inferring causal effects.
• NOT make causal claims directly from a single GWAS p-value. Association is not causation. Causal interpretation requires colocalisation or MR analysis with proper instrumental-variable assumptions.
• NOT cherry-pick variants by p-value alone. Statistical inference requires the full window context (credible set, posterior inclusion probabilities, joint conditional analyses).
• NOT compare effect sizes across studies without harmonising effect alleles. Cross-study comparison requires a step like TwoSampleMR's harmonise_data. Sign-flip risk is real for swapped alleles and palindromic ambiguity.
• Surface the GCST id, trait label, sample size (cases / controls if binary, total N if continuous), ancestry, and consortium (when present) alongside any β / p-value the agent quotes. Per the user-friendly enum-expansion rule (AGENTS.md), expand each field: study GCST90269602; trait cholesterol in medium VLDL; ancestry European; N=44,000 (not just GCST90269602).
• NOT report a binary-trait OR (odds ratio) as if it were a continuous-trait β. A binary-trait study may publish an odds ratio and its 95% CI with no hm_beta at all; each RegionVariant then carries odds_ratio, ci_lower and ci_upper with beta and se empty. The fetcher passes these through as published and does not convert them: a consumer that needs an effect size derives log(OR) itself (β = ln(OR), with the SE taken from the CI, or from the p-value when no CI is published). The manifest does not record the trait type, so check the study's metadata before reading a published hm_beta as log(OR).

Citations

• Sollis et al. (2023). The NHGRI-EBI GWAS Catalog: knowledgebase and deposition resource. Nucleic Acids Res 51, D977-D985. doi:10.1093/nar/gkac1010
• Per-study original GWAS publication (cited from the GWAS Catalog metadata pubmedId field).