alterlab-gwas

$npx mdskill add AlterLab-IEU/AlterLab-Academic-Skills/alterlab-gwas

Query NHGRI-EBI GWAS Catalog for SNP-trait associations and summary statistics.

  • Retrieves genetic variant associations for SNPs, traits, or genes.
  • Depends on the NHGRI-EBI GWAS Catalog REST API (no auth).
  • Uses user-provided rs ID, trait, or gene to construct API queries.
  • Outputs JSON results to stdout for agent or user consumption.

SKILL.md

.github/skills/alterlab-gwasView on GitHub ↗
---
name: alterlab-gwas
description: Query the NHGRI-EBI GWAS Catalog REST API for SNP-trait associations, retrieving variants by rs ID, disease/trait, or gene along with p-values and summary statistics. Use when investigating genome-wide association study hits, mapping a SNP or rsID to traits, building polygenic risk scores, or doing genetic epidemiology lookups. Part of the AlterLab Academic Skills suite.
license: MIT
allowed-tools: Read WebFetch Bash(curl:*) Bash(python:*)
compatibility: Keyless NHGRI-EBI GWAS Catalog REST API (no authentication required)
metadata:
    skill-author: AlterLab
    version: "1.0.0"
---

# GWAS Catalog Database

## Overview

The GWAS Catalog is a curated repository of published genome-wide association studies maintained by NHGRI and EBI. It contains SNP-trait associations from thousands of GWAS publications — genetic variants, associated traits and diseases, p-values, effect sizes, and full summary statistics for many studies.

## Scripts

`scripts/query_gwas.py` — query the GWAS Catalog REST API (stdlib only, JSON to stdout):

```bash
python scripts/query_gwas.py variant rs7903146           # associations for a SNP
python scripts/query_gwas.py trait MONDO_0005148 --size 100  # associations for a trait
python scripts/query_gwas.py study GCST001795            # study metadata
```

## When to Use This Skill

Use this skill for:
- **Genetic variant associations** — SNPs associated with diseases or traits
- **SNP lookups** — information about specific variants (rs IDs)
- **Trait/disease searches** — genetic associations for phenotypes
- **Gene associations** — variants in or near specific genes
- **GWAS summary statistics** — complete genome-wide association data
- **Study metadata** — publication and cohort information
- **Population genetics** — ancestry-specific associations
- **Polygenic risk scores** — variants for risk prediction models
- **Functional genomics** / **systematic reviews** — variant effects, literature synthesis

## Data Model

Four core entities, each with a canonical identifier:
- **Studies** → `GCST` accessions (e.g., GCST001234)
- **Associations** → SNP-trait links with p-values (genome-wide significant: p ≤ 5×10⁻⁸)
- **Variants** → `rs` numbers (e.g., rs7903146)
- **Traits** → trait ontology short-forms (e.g., MONDO_0005148 = type 2 diabetes on the main REST API); genes use HGNC symbols (e.g., TCF7L2)

> **Trait-ID gotcha (verified):** the two APIs disagree on trait IDs. The main REST API has migrated many traits to MONDO / current EFO short-forms, so `efoTraits/MONDO_0005148` works but the legacy `efoTraits/EFO_0001360` now 404s. The Summary Statistics API still uses the legacy ID: `traits/EFO_0001360` works there but `traits/MONDO_0005148` 404s. If a trait path 404s, look up the current short-form with `/efoTraits/search/findByTrait?trait=...` (main API) before assuming the trait is absent.

## APIs

Two free, no-key REST APIs:
- **GWAS Catalog API**: `https://www.ebi.ac.uk/gwas/rest/api` (curated associations, studies, variants, traits)
- **Summary Statistics API**: `https://www.ebi.ac.uk/gwas/summary-statistics/api` (all tested variants, not just significant hits)

Core endpoints: `/studies/{GCST}`, `/efoTraits/{efoID}/associations`, `/singleNucleotidePolymorphisms/{rsID}` and `/{rsID}/associations`. Responses are HAL+JSON with `_embedded` results, `_links` for related resources, and pagination (`page`, `size`).

## Core Workflow

1. **Identify the entity** — get the EFO ID (trait), rs ID (variant), GCST (study), or HGNC symbol (gene). Use the web interface for free-text → EFO mapping.
2. **Query the matching endpoint** — trait/variant/study/region; iterate pages via `page`/`size`.
3. **Filter** — by p-value (≤ 5×10⁻⁸ for genome-wide significance), ancestry, sample size, discovery/replication status.
4. **Extract** — rs IDs, effect alleles/directions, effect sizes (OR or beta), p-values.
5. **Cross-reference** — Ensembl (consequences), gnomAD (frequencies), Open Targets, PGS Catalog.
6. **For genome-wide analyses** — pull full summary statistics via the Summary Statistics API or FTP rather than scraping the association endpoints.

## Routing Guidance

- **Writing API calls / want copy-paste code** (endpoints, the four worked examples, summary-stats access, cross-referencing, full paginated Python helper) → `references/query_examples.md`.
- **Following a multi-step task** (disease-, variant-, gene-centric, systematic review, summary-stats analysis) or **web-interface search syntax** → `references/query_workflows.md`.
- **Need response field names, pagination details, or best-practice / data-quality guidance** → `references/data_fields_and_best_practices.md`.
- **Deep endpoint specs, all query params, error handling, advanced filtering** → `references/api_reference.md`.

## Reference Index

- **`references/query_examples.md`** — REST endpoint code, four canonical query examples (disease, variant, summary stats, chromosomal region), summary-statistics access, cross-referencing, and a complete paginated Python integration returning a DataFrame.
- **`references/query_workflows.md`** — Five step-by-step query workflows (disease, variant, gene, systematic review, summary statistics) plus web-interface search modes.
- **`references/data_fields_and_best_practices.md`** — Association/study response fields, pagination, query and interpretation best practices, rate-limiting ethics, and data-quality considerations.
- **`references/api_reference.md`** — Comprehensive endpoint specifications, query parameters/filters, response formats, error handling, and integration with external databases.

## Citation and Resources

When using GWAS Catalog data, cite:
- Sollis E, et al. (2023) The NHGRI-EBI GWAS Catalog: knowledgebase and deposition resource. Nucleic Acids Research 51:D977-D985. PMID: 36350656. DOI: 10.1093/nar/gkac1010
- Include access date and version when available; cite original studies when discussing specific findings.

- **Website**: https://www.ebi.ac.uk/gwas/
- **Documentation**: https://www.ebi.ac.uk/gwas/docs
- **API docs**: https://www.ebi.ac.uk/gwas/rest/docs/api
- **Summary Statistics API**: https://www.ebi.ac.uk/gwas/summary-statistics/docs/
- **FTP site**: http://ftp.ebi.ac.uk/pub/databases/gwas/
- **Training materials**: https://github.com/EBISPOT/GWAS_Catalog-workshop (Jupyter notebooks, Colab)
- **PGS Catalog** (polygenic scores): https://www.pgscatalog.org/
- **Help and support**: [email protected]

More from AlterLab-IEU/AlterLab-Academic-Skills

SkillDescription
alterlab-abm-mesaBuilds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
alterlab-academic-careerPrepares academic career documents and professional-development materials for faculty and researchers. Use when drafting academic CVs, research statements, teaching philosophies, diversity statements, faculty-position cover letters, tenure dossiers, promotion narratives, academic portfolios, or mentorship statements, and when planning conference-networking strategy, building academic web presence, setting up ORCID profiles, or understanding impact metrics. Part of the AlterLab Academic Skills suite.
alterlab-accreditation-aolScaffolds program-level Assurance-of-Learning (AoL) documentation for AACSB (2020 Standard 5) and ABET (Criterion 3 Student Outcomes, Criterion 4 Continuous Improvement) accreditation — program learning outcomes / competency goals, curriculum-to-outcome mapping matrices, direct- and indirect-assessment plans, rubric design, and closing-the-loop continuous-improvement narratives — and validates the structure of an outcome-mapping matrix with scripts/aol_matrix.py. Use when the user needs AACSB or ABET assurance-of-learning material, a program-learning-outcomes set, a curriculum/outcome map or coverage matrix, a direct/indirect assessment plan, a closing-the-loop report, or accreditation self-study text. For single-course design or course rubrics prefer alterlab-teaching-design; for post-award grant reports prefer alterlab-grant-reporting. Part of the AlterLab Academic Skills suite.
alterlab-adaptyvSubmits and tracks protein-testing experiments on the Adaptyv Bio Foundry cloud lab (wet-lab validation), and optimizes protein sequences before submission with computational tools (NetSolP, SoluProt, SolubleMPNN, ESM). Use when designing proteins that need wet-lab validation - binding/affinity screening, expression testing, thermostability, or fluorescence assays - or when submitting experiments to the Foundry API, browsing the target catalog, tracking experiment status, retrieving results, or pre-screening sequences for solubility/expression. Triggers on "Adaptyv", "Foundry API", "cloud lab", "biolayer interferometry / BLI", "wet-lab validation". Part of the AlterLab Academic Skills suite.
alterlab-aeonRuns time series machine learning with the aeon library — classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search via scikit-learn compatible APIs. Use when working with temporal data, sequential patterns, or time-indexed observations (univariate or multivariate) that need specialized algorithms beyond standard ML approaches. Part of the AlterLab Academic Skills suite.
alterlab-akademik-tesvikComputes the annual Turkish academic-incentive (akademik teşvik) score for Devlet (state) university öğretim elemanı (academic staff) from a classified activity list, applying the verified Akademik Teşvik Ödeneği Yönetmeliği (2018/11834) Faaliyet Hesaplama Tablosu headline puanları (Proje 20, Araştırma 15, Yayın 30, Patent 30, Atıf 30, Tebliğ 20, Ödül 20) with the k (author-count), p (Q1 1/Q2 0.8/Q3 0.5/Q4 0.25), and r (project-role) coefficients via türü puanı = Σ(faaliyet oranları) × headline (MADDE 8/2), then enforcing the per-type headline ceilings, the 100 cap (MADDE 8/3), and the net-30 payment gate (MADDE 10/3) in a deterministic scripts/tesvik_score.py. Use when the user wants to calculate akademik teşvik puanı, check the en az 30 (net-30) threshold, apply TABLO 4 ceilings, or estimate teşvik eligibility; keeps its coefficients separate from doçentlik scoring. For doçentlik point eligibility prefer alterlab-docentlik-eligibility. Part of the AlterLab Academic Skills suite.
alterlab-alpha-vantageAccesses real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API (requires a free API key from alphavantage.co). Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Part of the AlterLab Academic Skills suite.
alterlab-alphafoldPredict protein 3D structures with AlphaFold2 via ColabFold — MMseqs2-accelerated MSAs, monomer and AlphaFold2-Multimer complex folding, and confidence-based validation (pLDDT, pTM/ipTM, PAE). Use when folding a protein sequence or complex from FASTA, generating a predicted structure with confidence metrics, ranking models, or checking self-consistency of a design. For co-folding a protein WITH a small-molecule ligand or predicting binding affinity prefer alterlab-boltz; for antibody–antigen or one-FASTA multi-entity complexes prefer alterlab-chai; to LOOK UP an already-computed structure prefer alterlab-alphafold-db; for ESM embeddings or inverse folding prefer alterlab-esm. Part of the AlterLab Academic Skills suite.
alterlab-alphafold-dbAccess the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite.
alterlab-anndataBuild, slice, concatenate, read, and write AnnData annotated data matrices (obs, var, X, layers, obsm, uns) — the scverse data STRUCTURE, not an analysis pipeline. Use when creating or wrangling .h5ad/zarr files, managing cell and gene annotations, concatenating batches, or handling layers/obsm/backed-mode; for the QC, normalization, clustering, UMAP, and differential-expression analysis pipeline prefer alterlab-scanpy instead, and for RNA velocity from spliced/unspliced layers prefer alterlab-scvelo instead. Part of the AlterLab Academic Skills suite.