/gwas-catalog-region-fetch

name: gwas-catalog-region-fetch
description: |
  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: MIT
metadata:
  skill-author: Aviv Madar
  version: 0.1.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, 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 (`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_othe