mims-harvard/tooluniverse-gwas-trait-to-gene

GWAS Trait-to-Gene Discovery

Nearest gene is often wrong. Use L2G (locus-to-gene) scores from Open Targets which integrate eQTL, chromatin interaction, and distance data. L2G > 0.5 is a strong prediction; positional mapping alone should not be used to claim a causal gene. A single GWAS study with p < 5e-8 is suggestive — replication across independent cohorts is required for high confidence. GWAS hits are associations in the studied population; effect sizes and even the implicated gene can differ across ancestries due to differing LD patterns. Treat gene lists from GWAS as ranked candidates for validation, not confirmed causal genes.

LOOK UP DON'T GUESS: never assume trait-to-gene mappings or L2G scores — always call gwas_search_associations and OpenTargets_get_study_credible_sets to retrieve current data; associations are updated as new GWAS are published.

Discover genes associated with diseases and traits using genome-wide association studies (GWAS)

Overview

This skill enables systematic discovery of genes linked to diseases/traits by analyzing GWAS data from two major resources:

• GWAS Catalog (EBI/NHGRI): Curated catalog of published GWAS with >500,000 associations
• Open Targets Genetics: Fine-mapped GWAS signals with locus-to-gene (L2G) predictions

Use Cases

Clinical Research

• "What genes are associated with type 2 diabetes?"
• "Find genetic risk factors for coronary artery disease"
• "Which genes contribute to Alzheimer's disease susceptibility?"

Drug Target Discovery

• Identify genes with strong genetic evidence for disease causation
• Prioritize targets based on L2G scores and replication across studies
• Find genes with genome-wide significant associations (p < 5e-8)

Functional Genomics

• Map disease-associated variants to candidate genes
• Analyze genetic architecture of complex traits
• Understand polygenic disease mechanisms

Workflow

1. Trait Search → Search GWAS Catalog by disease/trait name
       ↓
2. SNP Aggregation → Collect genome-wide significant SNPs (p < 5e-8)
       ↓
3. Gene Mapping → Extract mapped genes from associations
       ↓
4. Evidence Ranking → Score by p-value, replication, fine-mapping
       ↓
5. Annotation (Optional) → Add L2G predictions from Open Targets

Key Concepts

Genome-wide Significance

• Standard threshold: p < 5×10⁻⁸
• Accounts for multiple testing burden across ~1M common variants
• Higher confidence: p < 5×10⁻¹⁰ or replicated across studies

Gene Mapping Methods

• Positional: Nearest gene to lead SNP
• Fine-mapping: Statistical refinement to credible variants
• Locus-to-Gene (L2G): Integrative score combining multiple evidence types

Evidence Confidence Levels

• High: L2G score > 0.5 OR multiple studies with p < 5e-10
• Medium: 2+ studies with p < 5e-8
• Low: Single study or marginal significance

Required ToolUniverse Tools

GWAS Catalog (11 tools)

• gwas_get_associations_for_trait - Get all associations for a trait (sorted by p-value). NOTE: This tool is BROKEN -- use gwas_search_associations(query=trait) as a working alternative
• gwas_search_snps - Search SNPs by gene mapping
• gwas_get_snp_by_id - Get SNP details (MAF, consequence, location)
• gwas_get_study_by_id - Get study metadata
• gwas_search_associations - Search associations with filters (RECOMMENDED for trait lookups)
• gwas_search_studies - Search studies by trait/cohort
• gwas_get_associations_for_snp - Get all associations for a SNP
• gwas_get_variants_for_trait - Get variants for a trait. Supports p_value_threshold parameter for server-side filtering (see notes below)
• gwas_get_studies_for_trait - Get studies for a trait
• gwas_get_snps_for_gene - Get SNPs mapped to a gene. Parameter is gene_symbol (NOT mapped_gene)
• gwas_get_associations_for_study - Get associations from a study

Open Targets Genetics (6 tools)

• OpenTargets_search_gwas_studies_by_disease - Search studies by disease ontology
• OpenTargets_get_study_credible_sets - Get fine-mapped loci for a study
• OpenTargets_get_variant_credible_sets - Get credible sets for a variant
• OpenTargets_get_variant_info - Get variant annotation (frequencies, consequences)
• OpenTargets_get_gwas_study - Get study metadata
• OpenTargets_get_credible_set_detail - Get detailed credible set information

Parameters

Required

• trait - Disease/trait name (e.g., "type 2 diabetes", "coronary artery disease")

Optional

• p_value_threshold - Significance threshold (default: 5e-8)
• min_evidence_count - Minimum number of studies (default: 1)
• max_results - Maximum genes to return (default: 100)
• use_fine_mapping - Include L2G predictions (default: true)
• disease_ontology_id - Disease ontology ID for Open Targets (e.g., "MONDO_0005148")

Output Schema

{
  "genes": [
    {
      "symbol": str,              # Gene symbol (e.g., "TCF7L2")
      "min_p_value": float,       # Most significant p-value
      "evidence_count": int,      # Number of independent studies
      "snps": [str],              # Associated SNP rs IDs
      "studies": [str],           # GWAS study accessions
      "l2g_score": float | null,  # Locus-to-gene score (0-1)
      "credible_sets": int,       # Number of credible sets
      "confidence_level": str     # "High", "Medium", or "Low"
    }
  ],
  "summary": {
    "trait": str,
    "total_associations": int,
    "significant_genes": int,
    "data_sources": ["GWAS Catalog", "Open Targets"]
  }
}

Example Results

Type 2 Diabetes

TCF7L2:  p=1.2e-98, 15 studies, L2G=0.82 → High confidence
KCNJ11:  p=3.4e-67, 12 studies, L2G=0.76 → High confidence
PPARG:   p=2.1e-45, 8 studies,  L2G=0.71 → High confidence
FTO:     p=5.6e-42, 10 studies, L2G=0.68 → High confidence
IRS1:    p=8.9e-38, 6 studies,  L2G=0.54 → High confidence

Alzheimer's Disease

APOE:    p=1.0e-450, 25 studies, L2G=0.95 → High confidence
BIN1:    p=2.3e-89,  18 studies, L2G=0.88 → High confidence
CLU:     p=4.5e-67,  16 studies, L2G=0.82 → High confidence
ABCA7:   p=6.7e-54,  14 studies, L2G=0.79 → High confidence
CR1:     p=8.9e-52,  13 studies, L2G=0.75 → High confidence

Best Practices

1. Use Disease Ontology IDs for Precision

# Instead of:
discover_gwas_genes("diabetes")  # Ambiguous

# Use:
discover_gwas_genes(
    "type 2 diabetes",
    disease_ontology_id="MONDO_0005148"  # Specific
)

2. Filter by Evidence Strength

# For drug targets, require strong evidence:
discover_gwas_genes(
    "coronary artery disease",
    p_value_threshold=5e-10,    # Stricter than GWAS threshold
    min_evidence_count=3,       # Multiple independent studies
    use_fine_mapping=True       # Include L2G predictions
)

3. Interpret Results Carefully

• Association ≠ Causation: GWAS identifies correlated variants, not necessarily causal genes
• Linkage Disequilibrium: Lead SNP may tag the true causal variant in a nearby gene
• Fine-mapping: L2G scores provide better causal gene evidence than positional mapping
• Functional Evidence: Validate with orthogonal data (eQTLs, knockout models, etc.)

Tool-Specific Notes (Updated)

gwas_get_variants_for_trait -- p-value Filtering

This tool now accepts an optional p_value_threshold parameter for server-side p-value filtering. When provided, the GWAS Catalog API filters variants to only return those below the specified threshold.

# Server-side filtering (preferred -- reduces data transfer)
result = tu.tools.gwas_get_variants_for_trait(
    trait="type 2 diabetes",
    p_value_threshold=5e-8
)

Client-side fallback: When the API returns unfiltered results (some trait queries ignore the threshold parameter), the tool also applies client-side p-value filtering. This means you may see fewer results than expected if the API returned pre-filtered data and the client filter applies again. Always check the actual p-values in the returned data.

gwas_get_associations_for_trait -- BROKEN

This tool returns errors for most queries. Use gwas_search_associations(query=<trait>) as a reliable alternative. The response format is {data: [{...}], metadata: {...}}.

gwas_get_snps_for_gene -- Parameter Rename

The parameter was renamed from mapped_gene to gene_symbol for clarity. Use:

result = tu.tools.gwas_get_snps_for_gene(gene_symbol="TCF7L2")

---

Programmatic Access (Beyond Tools)

When ToolUniverse tools return limited results or you need the full GWAS Catalog:

import requests, pandas as pd

# Download full GWAS Catalog (all associations, ~37MB TSV)
url = "https://www.ebi.ac.uk/gwas/api/search/downloads/alternative"
df = pd.read_csv(url, sep="\t")
# Filter locally by trait or gene
hits = df[df["DISEASE/TRAIT"].str.contains("type 2 diabetes", case=False, na=False)]
gene_hits = df[df["MAPPED_GENE"].str.contains("TCF7L2", na=False)]

# Per-study associations via REST
study_id = "GCST001234"
assocs = requests.get(f"https://www.ebi.ac.uk/gwas/rest/api/studies/{study_id}/associations").json()

# Summary statistics (when available)
# Check study page for fullPvalueSet=true, then download from linked FTP

See tooluniverse-data-wrangling skill for pagination, bulk download, and format parsing patterns.

---

Limitations

1. Gene Mapping Uncertainty

   • Positional mapping assigns SNPs to nearest gene (may be incorrect)
   • Fine-mapping available for only a subset of studies
   • Intergenic variants difficult to map

2. Population Bias

   • Most GWAS in European populations
   • Effect sizes may differ across ancestries
   • Rare variants often under-represented

3. Sample Size Dependence

   • Larger studies detect more associations
   • Older small studies may have false negatives
   • p-values alone don't indicate effect size

4. Validation Bug

   • Some ToolUniverse tools have oneOf validation issues
   • Use validate=False parameter if needed
   • This is automatically handled in the Python implementation

Related Skills

• Variant-to-Disease Association: Look up specific SNPs (e.g., rs7903146 → T2D)
• Gene-to-Disease Links: Find diseases associated with known genes
• Drug Target Prioritization: Rank targets by genetic evidence
• Population Genetics Analysis: Compare allele frequencies across populations

Data Sources

GWAS Catalog

• Curator: EBI and NHGRI
• URL: https://www.ebi.ac.uk/gwas/
• Coverage: 100,000+ publications, 500,000+ associations
• Update Frequency: Weekly

Open Targets Genetics

• Curator: Open Targets consortium
• URL: https://genetics.opentargets.org/
• Coverage: Fine-mapped GWAS, L2G predictions, QTL colocalization
• Update Frequency: Quarterly

Citation

If you use this skill in research, please cite:

Buniello A, et al. (2019) The NHGRI-EBI GWAS Catalog of published genome-wide
association studies. Nucleic Acids Research, 47(D1):D1005-D1012.

Mountjoy E, et al. (2021) An open approach to systematically prioritize causal
variants and genes at all published human GWAS trait-associated loci.
Nature Genetics, 53:1527-1533.

Support

For issues with:

• Skill functionality: Open issue at tooluniverse/skills
• GWAS data: Contact GWAS Catalog or Open Targets support
• Tool errors: Check ToolUniverse tool status