@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/tooluniverse-gwas-study-explorer/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: tooluniverse-gwas-study-explorer
+description: Compare GWAS studies, perform meta-analyses, and assess replication across cohorts. Integrates NHGRI-EBI GWAS Catalog and Open Targets Genetics to compare study designs, effect sizes, ancestry diversity, and heterogeneity statistics. Use when comparing GWAS studies for a trait, performing meta-analysis of genetic loci, assessing replication across cohorts, or exploring the genetic architecture of complex diseases.
+---
+
+
+# GWAS Study Deep Dive & Meta-Analysis
+
+**Compare GWAS studies, perform meta-analyses, and assess replication across cohorts**
+
+---
+
+## Overview
+
+The GWAS Study Deep Dive & Meta-Analysis skill enables comprehensive comparison of genome-wide association studies (GWAS) for the same trait, meta-analysis of genetic loci across studies, and systematic assessment of replication and study quality. It integrates data from the NHGRI-EBI GWAS Catalog and Open Targets Genetics to provide a complete picture of the genetic architecture of complex traits.
+
+### Key Capabilities
+
+1. **Study Comparison**: Compare all GWAS studies for a trait, assessing sample sizes, ancestries, and platforms
+2. **Meta-Analysis**: Aggregate effect sizes across studies and calculate heterogeneity statistics
+3. **Replication Assessment**: Identify replicated vs novel findings across discovery and replication cohorts
+4. **Quality Evaluation**: Assess statistical power, ancestry diversity, and data availability
+
+---
+
+## Use Cases
+
+### 1. Comprehensive Trait Analysis
+**Scenario**: "I want to understand all available GWAS data for type 2 diabetes"
+
+**Workflow**:
+- Search for all T2D studies in GWAS Catalog
+- Filter by sample size and ancestry
+- Extract top associations from each study
+- Identify consistently replicated loci
+- Assess ancestry-specific effects
+
+**Outcome**: Complete landscape of T2D genetics with replicated findings and population-specific signals
+
+### 2. Locus-Specific Meta-Analysis
+**Scenario**: "Is the TCF7L2 association with T2D consistent across all studies?"
+
+**Workflow**:
+- Retrieve all TCF7L2 (rs7903146) associations for T2D
+- Calculate combined effect size and p-value
+- Assess heterogeneity (I² statistic)
+- Generate forest plot data
+- Interpret heterogeneity level
+
+**Outcome**: Quantitative assessment of effect size consistency with heterogeneity interpretation
+
+### 3. Replication Analysis
+**Scenario**: "Which findings from the discovery cohort replicated in the independent sample?"
+
+**Workflow**:
+- Get top hits from discovery study
+- Check for presence and significance in replication study
+- Assess direction consistency
+- Calculate replication rate
+- Identify novel vs failed replication
+
+**Outcome**: Systematic replication report with success rates and failed findings
+
+### 4. Multi-Ancestry Comparison
+**Scenario**: "Are T2D loci consistent across European and East Asian populations?"
+
+**Workflow**:
+- Filter studies by ancestry
+- Compare top associations between populations
+- Identify shared vs population-specific loci
+- Assess allele frequency differences
+- Evaluate transferability of genetic risk scores
+
+**Outcome**: Ancestry-specific genetic architecture with transferability assessment
+
+---
+
+## Statistical Methods
+
+### Meta-Analysis Approach
+
+This skill implements standard GWAS meta-analysis methods:
+
+**Fixed-Effects Model**:
+- Used when heterogeneity is low (I² < 25%)
+- Weights studies by inverse variance
+- Assumes true effect size is the same across studies
+
+**Random-Effects Model** (recommended when I² > 50%):
+- Accounts for between-study variation
+- More conservative than fixed-effects
+- Better for diverse ancestries or methodologies
+
+**Heterogeneity Assessment**:
+
+The **I² statistic** measures the percentage of variance due to between-study heterogeneity:
+
+```
+I² = [(Q - df) / Q] × 100%
+
+where Q = Cochran's Q statistic
+      df = degrees of freedom (n_studies - 1)
+```
+
+**Interpretation Guidelines**:
+- **I² < 25%**: Low heterogeneity → fixed-effects appropriate
+- **I² = 25-50%**: Moderate heterogeneity → investigate sources
+- **I² = 50-75%**: Substantial heterogeneity → random-effects preferred
+- **I² > 75%**: Considerable heterogeneity → meta-analysis may not be appropriate
+
+### Sources of Heterogeneity
+
+Common reasons for high I²:
+
+1. **Ancestry differences**: Different allele frequencies and LD structure
+2. **Phenotype heterogeneity**: Trait definition varies across studies
+3. **Platform differences**: Imputation quality and coverage
+4. **Winner's curse**: Discovery studies overestimate effect sizes
+5. **Cohort characteristics**: Age, sex, environmental factors
+
+**Recommendations**:
+- Perform subgroup analysis by ancestry
+- Use meta-regression to investigate sources
+- Consider excluding outlier studies
+- Apply genomic control correction
+
+---
+
+## Study Quality Assessment
+
+### Quality Metrics
+
+The skill evaluates studies based on:
+
+**1. Sample Size**:
+- Power to detect associations (80% power requires n > 10,000 for OR=1.2)
+- Precision of effect size estimates
+- Ability to detect modest effects
+
+**2. Ancestry Diversity**:
+- Single-ancestry vs multi-ancestry
+- Population stratification control
+- Transferability of findings
+
+**3. Data Availability**:
+- Summary statistics available for meta-analysis
+- Individual-level data vs summary-level
+- Imputation quality scores
+
+**4. Genotyping Quality**:
+- Platform density and coverage
+- Imputation reference panel
+- Quality control measures
+
+**5. Statistical Rigor**:
+- Genome-wide significance threshold (p < 5×10⁻⁸)
+- Multiple testing correction
+- Replication in independent cohort
+
+### Quality Tiers
+
+**Tier 1 (High Quality)**:
+- n ≥ 50,000
+- Summary statistics available
+- Multi-ancestry or large single-ancestry
+- Imputed to high-quality reference
+- Independent replication
+
+**Tier 2 (Moderate Quality)**:
+- n ≥ 10,000
+- Standard GWAS platform
+- Adequate power for common variants
+- Some data availability
+
+**Tier 3 (Limited)**:
+- n < 10,000
+- Limited power
+- May miss modest effects
+- Use with caution
+
+---
+
+## Best Practices
+
+### Before Meta-Analysis
+
+1. **Check phenotype consistency**: Ensure studies measure the same trait
+2. **Verify ancestry overlap**: High heterogeneity expected if ancestries differ
+3. **Harmonize alleles**: Align effect alleles across studies
+4. **Quality control**: Exclude low-quality studies or associations
+
+### Interpreting Results
+
+1. **Genome-wide significance**: p < 5×10⁻⁸ (Bonferroni for ~1M independent tests)
+2. **Replication threshold**: p < 0.05 in independent cohort
+3. **Direction consistency**: Effect should be same direction across studies
+4. **Heterogeneity**: I² > 50% suggests caution in interpretation
+
+### Common Pitfalls
+
+❌ **Don't**:
+- Meta-analyze without checking heterogeneity
+- Ignore ancestry differences
+- Over-interpret nominal p-values
+- Assume replication failure means false positive
+
+✅ **Do**:
+- Always report I² statistic
+- Perform sensitivity analyses
+- Consider ancestry-stratified analysis
+- Account for winner's curse in discovery studies
+
+---
+
+## Limitations & Caveats
+
+### Data Limitations
+
+1. **Incomplete Overlap**: Studies may analyze different SNPs
+2. **Cohort Overlap**: Some cohorts participate in multiple studies (inflates significance)
+3. **Publication Bias**: Significant findings more likely to be published
+4. **Winner's Curse**: Discovery studies overestimate effect sizes
+5. **Imputation Quality**: Varies across studies and populations
+
+### Statistical Limitations
+
+1. **Heterogeneity**: High I² may preclude meaningful meta-analysis
+2. **Sample Size Differences**: Large studies dominate fixed-effects models
+3. **Allele Frequency Differences**: Same variant has different effects across ancestries
+4. **Linkage Disequilibrium**: Fine-mapping needed to identify causal variants
+5. **Gene-Environment Interactions**: Not captured in standard meta-analysis
+
+### Interpretation Guidelines
+
+**When I² > 75%**:
+- Meta-analysis results should be interpreted with extreme caution
+- Investigate sources of heterogeneity systematically
+- Consider ancestry-specific or subgroup analyses
+- Descriptive comparison may be more appropriate than meta-analysis
+
+**When Studies Conflict**:
+- Check for methodological differences
+- Verify phenotype definitions match
+- Investigate population stratification
+- Consider conditional analysis
+
+---
+
+## Scientific References
+
+### Key Publications
+
+1. **GWAS Best Practices**:
+   - Visscher et al. (2017). "10 Years of GWAS Discovery" *American Journal of Human Genetics* 101(1): 5-22
+   - PMID: 28686856
+   - DOI: 10.1016/j.ajhg.2017.06.005
+
+2. **Meta-Analysis Methods**:
+   - Evangelou & Ioannidis (2013). "Meta-analysis methods for genome-wide association studies and beyond" *Nature Reviews Genetics* 14: 379-389
+   - PMID: 23657481
+
+3. **Heterogeneity Interpretation**:
+   - Higgins et al. (2003). "Measuring inconsistency in meta-analyses" *BMJ* 327: 557-560
+   - PMID: 12958120
+
+4. **Multi-Ancestry GWAS**:
+   - Peterson et al. (2019). "Genome-wide Association Studies in Ancestrally Diverse Populations" *Nature Reviews Genetics* 20: 409-422
+   - PMID: 30926972
+
+5. **Replication Standards**:
+   - Chanock et al. (2007). "Replicating genotype-phenotype associations" *Nature* 447: 655-660
+   - PMID: 17554299
+
+---
+
+## Tools Used
+
+### GWAS Catalog API
+- `gwas_search_studies`: Find studies by trait
+- `gwas_get_study_by_id`: Get detailed study metadata
+- `gwas_get_associations_for_study`: Retrieve study associations
+- `gwas_get_associations_for_snp`: Get SNP associations across studies
+- `gwas_search_associations`: Search associations by trait
+
+### Open Targets Genetics GraphQL API
+- `OpenTargets_search_gwas_studies_by_disease`: Disease-based study search
+- `OpenTargets_get_gwas_study`: Detailed study information with LD populations
+- `OpenTargets_get_variant_credible_sets`: Fine-mapped loci for variant
+- `OpenTargets_get_study_credible_sets`: All credible sets for study
+- `OpenTargets_get_variant_info`: Variant annotation and allele frequencies
+
+---
+
+## Glossary
+
+**Association**: Statistical relationship between a genetic variant and a trait
+
+**Credible Set**: Set of variants likely to contain the causal variant (from fine-mapping)
+
+**Effect Size**: Magnitude of genetic association (beta coefficient or odds ratio)
+
+**Fine-Mapping**: Statistical method to identify causal variants within a locus
+
+**Genome-Wide Significance**: p < 5×10⁻⁸, accounting for ~1M independent tests
+
+**Heterogeneity (I²)**: Percentage of variance due to between-study differences
+
+**L2G (Locus-to-Gene)**: Score predicting which gene is affected by a GWAS locus
+
+**LD (Linkage Disequilibrium)**: Non-random association of alleles at different loci
+
+**Meta-Analysis**: Statistical combination of results from multiple studies
+
+**Replication**: Independent confirmation of an association in a new cohort
+
+**Summary Statistics**: Per-SNP statistics (p-value, beta, SE) from GWAS
+
+**Winner's Curse**: Overestimation of effect size in discovery studies
+
+---
+
+## Next Steps
+
+After running this skill, consider:
+
+1. **Fine-Mapping**: Use credible sets from Open Targets to identify causal variants
+2. **Functional Follow-Up**: Investigate biological mechanisms of replicated loci
+3. **Genetic Risk Scores**: Calculate polygenic risk scores using validated loci
+4. **Drug Target Identification**: Use L2G scores to prioritize therapeutic targets
+5. **Cross-Trait Analysis**: Look for pleiotropy with related traits
+
+---
+
+## Version History
+
+- **v1.0** (2026-02-13): Initial release with study comparison, meta-analysis, and replication assessment
+
+---
+
+**Created by**: ToolUniverse GWAS Analysis Team
+**Last Updated**: 2026-02-13
+**License**: Open source (MIT)

package/data/skills/tooluniverse-gwas-trait-to-gene/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: tooluniverse-gwas-trait-to-gene
+description: Discover genes associated with diseases and traits using GWAS data from the GWAS Catalog (500,000+ associations) and Open Targets Genetics (L2G predictions). Identifies genetic risk factors, prioritizes causal genes via locus-to-gene scoring, and assesses druggability. Use when asked to find genes associated with a disease or trait, discover genetic risk factors, translate GWAS signals to gene targets, or answer questions like "What genes are associated with type 2 diabetes?"
+---
+
+# GWAS Trait-to-Gene Discovery
+
+**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)
+- `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
+- `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
+- `gwas_get_studies_for_trait` - Get studies for a trait
+- `gwas_get_snps_for_gene` - Get SNPs mapped to a 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
+
+```python
+{
+  "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.)
+
+## 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