alterlab-gwas

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

python scripts/query_gwas.py variant rs7903146                 # associations for a SNP (strongest first)
python scripts/query_gwas.py trait MONDO_0005148 --size 100    # associations for a trait
python scripts/query_gwas.py gene TCF7L2                       # associations mapped to a gene
python scripts/query_gwas.py find-trait "type 2 diabetes"      # free text -> efo_id
python scripts/query_gwas.py study GCST001795                  # study metadata (+ summary-stats FTP link)

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

Does NOT Trigger

Scenario	Use Instead
Target-disease association scores, L2G / colocalisation evidence for drug targets	alterlab-opentargets
Clinical pathogenicity of a variant (ACMG/AMP, review stars)	alterlab-clinvar
Population allele frequencies or gene constraint	alterlab-gnomad
Which gene/tissue a variant regulates (eQTL/sQTL)	alterlab-gtex
Variant consequence (VEP), coordinates, gene models	alterlab-ensembl

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 → ontology short-forms in efo_id (e.g., MONDO_0005148 = type 2 diabetes mellitus); genes use HGNC symbols (e.g., TCF7L2)

Trait-ID gotcha (verified 2026-09): many traits have been re-mapped to MONDO / current EFO short-forms, and a stale ID returns an empty page rather than an error — associations?efo_id=EFO_0001360 (legacy type 2 diabetes) gives 0 rows while efo_id=MONDO_0005148 gives thousands. Resolve free text first with GET /v2/efo-traits?efo_trait=type 2 diabetes and use the returned efo_id. Older papers and pipelines may still cite the legacy EFO ID.

APIs

• GWAS Catalog REST API v2 (released Aug 2025): https://www.ebi.ac.uk/gwas/rest/api/v2 — curated top associations, studies, SNPs, traits, genes, publications. Free, no key; throttled at 15 requests/second; default page size 20 (keep size ≤ 200 — larger pages time out). Interactive reference: https://www.ebi.ac.uk/gwas/rest/api/v2/docs
• Legacy v1 (/gwas/rest/api/singleNucleotidePolymorphisms/..., /efoTraits/..., camelCase fields) is deprecated and was scheduled for retirement by May 2026; it may still answer, but don't write new code against it.
• Summary Statistics API (/gwas/summary-statistics/api) is retired (HTTP 410); full summary statistics are served from the FTP site (see workflow step 6). EBI describes a replacement API as "coming soon".

Core v2 endpoints: /v2/associations (filters rs_id, efo_id, efo_trait, mapped_gene, accession_id, pubmed_id; sort=p_value&direction=asc), /v2/studies and /v2/studies/{accession_id}, /v2/single-nucleotide-polymorphisms (by rs_id, mapped_gene, or chromosome + bp_start/bp_end), /v2/efo-traits, /v2/genes/{gene_name}. Responses are HAL+JSON with snake_case fields: results under _embedded.<resource> (associations, studies, snps, efo_traits), paging under page (totalElements, totalPages, number), next pages in _links.next.

Core Workflow

1. Identify the entity — get the efo_id (trait; resolve free text via /v2/efo-traits?efo_trait=), rs ID (variant), GCST (study), or HGNC symbol (gene).
2. Query the matching endpoint — trait/variant/study/gene/region; iterate pages via page/size or follow _links.next.
3. Filter — by p-value (≤ 5×10⁻⁸ for genome-wide significance), ancestry, sample size, discovery/replication status.
4. Extract — rs IDs and effect alleles (snp_allele[]), effect sizes (or_per_copy_num or the beta text), p-values. p_value underflows to 0.0 for very strong signals (rs7903146 in type 2 diabetes reaches 3×10⁻¹³¹⁵), so rank and report with pvalue_mantissa / pvalue_exponent.
5. Cross-reference — Ensembl (consequences), gnomAD (frequencies), Open Targets, PGS Catalog.
6. For genome-wide analyses — find studies with /v2/studies?efo_id=...&full_pvalue_set=true; each study's full_summary_stats field gives its FTP directory. Harmonised files live at https://ftp.ebi.ac.uk/pub/databases/gwas/summary_statistics/GCST<range>/<GCST>/harmonised/<GCST>.h.tsv.gz (GWAS-SSF columns, tabix-indexed .tbi), so a region can be pulled remotely with tabix <url> 10:112900000-113200000 instead of downloading the whole file. Don't scrape the association endpoints for this — they hold only curated top hits.

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 v2 docs: https://www.ebi.ac.uk/gwas/rest/api/v2/docs (OpenAPI: https://www.ebi.ac.uk/gwas/rest/api/v2/rest-api-doc.yaml)

• Summary statistics access: https://www.ebi.ac.uk/gwas/docs/methods/summary-statistics

• FTP site: https://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]