tooluniverse-gene-disease-association

What this skill does

# Gene-Disease Association Analysis

Systematically query and compare gene-disease associations across 6+ databases to produce a unified, evidence-graded report. Cross-references DisGeNET scores, OpenTargets evidence, Monarch Initiative cross-species data, OMIM Mendelian mappings, GenCC curated validity, and Orphanet rare disease links.

**IMPORTANT**: Always use English gene names and disease terms in tool calls. Respond in the user's language.

---

## LOOK UP, DON'T GUESS
When uncertain about any scientific fact, SEARCH databases first (PubMed, UniProt, ChEMBL, ClinVar, etc.) rather than reasoning from memory. A database-verified answer is always more reliable than a guess.

---

## Core Principles

1. **Report-first approach** - Create report file FIRST, then populate progressively
2. **Multi-database triangulation** - Query 4+ sources minimum, cross-validate
3. **Quantitative scoring** - Report numeric scores from each database
4. **Concordance analysis** - Count how many databases support each association and reason about independence
5. **Evidence reasoning** - Assess each association using evidence hierarchy, concordance, and mechanism plausibility
6. **Mendelian vs complex** - Distinguish monogenic (OMIM/Orphanet) from complex (GWAS/DisGeNET) associations
7. **Negative results documented** - "No association found in [database]" is informative

---

## Workflow Overview

```
Phase 1: Gene/Disease Identification & ID Resolution
  Resolve gene symbol to Ensembl ID, HGNC CURIE, MIM number
  OR resolve disease name to UMLS CUI, EFO ID, MONDO ID, ORPHA code
      |
Phase 2: DisGeNET Associations (scored, multi-evidence)
  Gene-disease association scores with evidence type filtering
      |
Phase 3: OpenTargets Associations (integrated evidence)
  Disease phenotypes and genetic associations from OpenTargets
      |
Phase 4: Monarch Initiative (cross-species evidence)
  Gene-disease associations integrating OMIM, ClinVar, model organisms
      |
Phase 5: Mendelian Disease Evidence (curated)
  OMIM gene-disease map, GenCC validity classifications, Orphanet rare diseases
      |
Phase 6: Variant-Disease Associations (optional, if gene query)
  DisGeNET variant-disease links, ClinVar pathogenic variants
      |
Phase 7: Evidence Synthesis
  Unified table, concordance scoring, confidence levels, final report
```

---

## Phase 1: Gene/Disease Identification & ID Resolution

```python
from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Gene query: resolve IDs
gene_info = tu.tools.MyGene_query_genes(query=f"symbol:{gene_symbol}", species="human",
    fields="symbol,ensembl.gene,entrezgene,name", size=5)  # -> ensembl_id
Monarch_search = tu.tools.MonarchV3_search(query=gene_symbol, category="biolink:Gene", limit=5)  # -> HGNC CURIE
omim_result = tu.tools.OMIM_search(query=gene_symbol, limit=5)  # -> MIM number
gene_summary = tu.tools.Harmonizome_get_gene(gene_symbol=gene_symbol)

# Disease query: resolve IDs
monarch_disease = tu.tools.MonarchV3_search(query=disease_name, category="biolink:Disease", limit=5)  # -> MONDO CURIE
mappings = tu.tools.MonarchV3_get_mappings(entity_id=mondo_id, limit=20)  # -> OMIM, ICD10, SNOMED, Orphanet
```

---

## Phase 2: DisGeNET Associations

> **API KEY REQUIRED**: DisGeNET tools require `DISGENET_API_KEY` environment variable. Without it, all DisGeNET calls will fail. Register at https://www.disgenet.org/api/#/Authorization for a free academic key.
> **Fallback if no key**: Skip this phase and rely on OpenTargets (Phase 3) + Monarch (Phase 4) which are free and cover much of the same data.

```python
# Gene -> diseases
disgenet_diseases = tu.tools.DisGeNET_search_gene(gene=gene_symbol, limit=20)
disgenet_gda = tu.tools.DisGeNET_get_gda(gene=gene_symbol, source="CURATED", min_score=0.3, limit=25)

# Disease -> genes (accepts name or UMLS CUI like "C0006142")
disgenet_genes = tu.tools.DisGeNET_search_disease(disease=disease_name, limit=20)
disgenet_ranked = tu.tools.DisGeNET_get_disease_genes(disease=disease_name, min_score=0.3, limit=50)
```

**Interpreting DisGeNET scores**: Higher scores reflect more evidence sources and stronger curation. Rather than memorizing cutoffs, ask: is this score driven by curated sources or text-mining? Use `source="CURATED"` to distinguish.

---

## Phase 3: OpenTargets Associations

```python
ot_diseases = tu.tools.OpenTargets_get_diseases_phenotypes_by_target_ensembl(ensemblId=ensembl_id)
ot_evidence = tu.tools.OpenTargets_target_disease_evidence(ensemblId=ensembl_id, efoId=efo_id)
# Both require pre-resolved Ensembl/EFO IDs. Use OpenTargets_multi_entity_search_by_query_string to discover IDs.
```

---

## Phase 4: Monarch Initiative Associations

```python
# Gene -> diseases (integrates OMIM, ClinVar, Orphanet, model organisms)
monarch_diseases = tu.tools.MonarchV3_get_associations(
    subject=hgnc_curie, category="biolink:CausalGeneToDiseaseAssociation", limit=20)
# Disease -> genes
monarch_genes = tu.tools.MonarchV3_get_associations(
    subject=mondo_id, category="biolink:CorrelatedGeneToDiseaseAssociation", limit=20)
histopheno = tu.tools.MonarchV3_get_histopheno(entity_id=mondo_id)  # phenotypes by body system
entity = tu.tools.MonarchV3_get_entity(entity_id=hgnc_curie)  # details, synonyms, xrefs
```

---

## Phase 5: Mendelian Disease Evidence

> **API KEY REQUIRED**: OMIM tools require `OMIM_API_KEY`. Register at https://omim.org/api for academic access.
> **Fallback if no key**: Use Monarch Initiative (`biolink:CausalGeneToDiseaseAssociation` from Phase 4) which includes OMIM data without requiring a key. Also use GenCC (below) which is fully open.

```python
# OMIM: Mendelian gene-disease mapping (use gene MIM number, not phenotype MIM)
omim_entry = tu.tools.OMIM_get_entry(mim_number=mim_number)
omim_gene_map = tu.tools.OMIM_get_gene_map(mim_number=mim_number)
omim_clinical = tu.tools.OMIM_get_clinical_synopsis(mim_number=phenotype_mim)

# GenCC: curated validity (Definitive/Strong/Moderate/Limited/Disputed/Refuted)
gencc_result = tu.tools.GenCC_search_gene(gene_symbol=gene_symbol)  # handles gene renames
gencc_disease = tu.tools.GenCC_search_disease(disease="Marfan syndrome")  # word-tokenized matching
gencc_classifications = tu.tools.GenCC_get_classifications(gene_symbol="BRCA1", disease="breast cancer")

# Orphanet: rare disease associations (filter results by exact gene.symbol match)
orphanet_result = tu.tools.Orphanet_get_gene_diseases(gene_name=gene_symbol)
```

---

## Phase 6: Variant-Disease Associations (Optional)

Run when the query is gene-based and variant-level evidence adds value.

```python
vda_result = tu.tools.DisGeNET_get_vda(gene=gene_symbol, limit=25)  # variant-disease links
clinvar_result = tu.tools.ClinVar_search_variants(gene=gene_symbol, max_results=20)
clinvar_detail = tu.tools.ClinVar_get_variant_details(variant_id="12345")  # detailed variant info
```

---

## Phase 7: Evidence Synthesis

### Unified Association Table

Compile all results into a single table per gene-disease pair:

```markdown
## Gene-Disease Associations for BRCA1

| Disease | DisGeNET Score | OpenTargets Score | Monarch | OMIM | GenCC | Orphanet | Sources |
|---------|---------------|-------------------|---------|------|-------|----------|---------|
| Breast cancer | 0.82 | 0.95 | Yes | #114480 | Definitive | ORPHA:227535 | 6/6 |
| Ovarian cancer | 0.78 | 0.91 | Yes | #604370 | Definitive | ORPHA:213500 | 6/6 |
| Pancreatic cancer | 0.35 | 0.42 | Yes | - | Moderate | - | 3/6 |
| Fanconi anemia | 0.45 | 0.38 | Yes | #605724 | Strong | ORPHA:84 | 5/6 |
```

### Reasoning Strategies for Evidence Evaluation

**Evidence strength reasoning**: A gene-disease association supported by multiple independent lines of evidence (genetic, functional, model organism) is stronger than one supported by a single study. Ask: how many independent sources support this link? Do they converge on the same mechanism?

**Genetic evidence hierarchy**: Mendelian segregation (gene m