gwas-catalog-region-fetch

Files (16)

• .gitignore
• LICENSE
• SKILL.md
• environment.yml
• default.json · examples/
• expected_output.md · examples/
• il6r_crp.yaml · examples/
• input.json · examples/
• run_example.sh · examples/
• sort1_cholesterol_vldl.json · examples/
• tcf7l2_hba1c.json · examples/
• gwas_catalog_region_fetch.py
• conftest.py · tests/
• test_gwas_catalog_region_fetch.py · tests/
• test_live_gwas_catalog_region_fetch.py · tests/
• test_reproducibility_bundle.py · tests/

SKILL.md (first lines)

# 🧬 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

```bash
# 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):

```json
{
  "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`:

```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):

```

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio