tooluniverse-rare-disease-genomics

What this skill does

## COMPUTE, DON'T DESCRIBE
When analysis requires computation (statistics, data processing, scoring, enrichment), write and run Python code via Bash. Don't describe what you would do — execute it and report actual results. Use ToolUniverse tools to retrieve data, then Python (pandas, scipy, statsmodels, matplotlib) to analyze it.

# Rare Disease Genomics Research

## Rare Disease Investigation Strategy

The order of investigation matters: **phenotype -> disease -> gene -> variant**, not the reverse. When starting from a gene, reverse it: gene -> diseases -> expected phenotypes -> does the patient match?

Resist the urge to skip to ClinVar immediately. A "Pathogenic" ClinVar entry is only meaningful if the gene is actually causative for the disease in question with the right inheritance mode.

## Variant Prioritization Reasoning (CRITICAL)

**LOOK UP DON'T GUESS** -- when uncertain about any gene, variant, or disease association, search the database. Do not rely on memory.

### How to filter thousands of variants down to one causal variant

1. **Inheritance pattern first** -- Check Orphanet_get_natural_history for inheritance mode. This determines your filtering strategy:
   - Autosomal dominant: look for heterozygous variants in ONE copy; de novo if unaffected parents
   - Autosomal recessive: need TWO hits (homozygous or compound heterozygous); check carrier parents
   - X-linked recessive: hemizygous males affected; carrier females usually unaffected
   - Mitochondrial: maternal inheritance only; heteroplasmy complicates penetrance

2. **Allele frequency filter** -- Rare disease variants should be RARE in population:
   - Dominant diseases: allele frequency < 0.001 (1 in 1,000) in gnomAD
   - Recessive diseases: allele frequency < 0.01 (1 in 100) for carriers
   - Use gnomAD via Ensembl VEP annotation or OpenTargets variant info to check frequency
   - **LOOK UP** the actual frequency -- do not assume a variant is rare

3. **Consequence hierarchy** -- Prioritize by predicted impact:
   - Loss-of-function (frameshift, nonsense, splice-site): strongest candidates
   - Missense in conserved domain: strong if in known functional domain
   - Synonymous / intronic: usually benign unless at splice junction

4. **ClinVar vs OMIM vs gnomAD -- when to check each**:
   - **ClinVar**: "Is this specific variant known to be pathogenic?" Check review stars (>=2 stars = reliable)
   - **OMIM** (via Orphanet/GenCC): "Is this gene known to cause this disease?" Check BEFORE ClinVar
   - **gnomAD** (via VEP/OpenTargets): "Is this variant too common to cause a rare disease?" Check allele frequency

5. **Phenotype-genotype correlation** -- After identifying a candidate gene:
   - Get HPO phenotypes for the associated disease (Orphanet_get_phenotypes)
   - Check: do the patient's features match the "Very frequent" phenotypes?
   - Mismatches in core features argue AGAINST the gene being causative
   - GenCC validity level tells you how strong the gene-disease link is overall

## When to Use

- "What is the genetic cause of Marfan syndrome?"
- "Find HPO phenotypes associated with cystic fibrosis"
- "What is the prevalence of Ehlers-Danlos syndrome?"
- "Which genes are linked to this rare disease?"
- "Is FBN1 definitively associated with Marfan syndrome?"
- "Find pathogenic variants in CFTR"
- "Are there clinical trials for Gaucher disease?"
- "What diseases are associated with gene FBN1?"

## NOT for (use other skills instead)

- Common disease genomics (type 2 diabetes, hypertension) -> Use `tooluniverse-disease-research`
- Cancer variant interpretation -> Use `tooluniverse-cancer-variant-interpretation`
- GWAS-based variant interpretation -> Use `tooluniverse-gwas-snp-interpretation`
- Pharmacogenomics / drug-gene interactions -> Use `tooluniverse-pharmacogenomics`
- Differential diagnosis from symptoms -> Use `tooluniverse-rare-disease-diagnosis`

---

## Workflow Overview

Phase 0: Disambiguation (resolve to ORPHA code / HGNC symbol) -> Phase 1: Disease Characterization -> Phase 2: Phenotype Mapping (HPO) -> Phase 3: Causative Genes -> Phase 4: Gene-Disease Validity (GenCC) -> Phase 5: Pathogenic Variants (ClinVar) -> Phase 6: Epidemiology -> Phase 7: Clinical Trials -> Phase 8: Literature -> Phase 9: Report

---

## Phase 0: Disambiguation

Resolve user input to canonical Orphanet identifiers before doing anything else. Many disease names have subtypes or umbrella syndromes that will produce misleading results if you pick the wrong one.

**Orphanet_search_diseases**: `name` (string REQUIRED, e.g., "Marfan syndrome"), `exact` (bool, default False), `lang` (string, default "en"). Primary tool for name-to-ORPHA-code resolution. The parameter is `name` (NOT `query`). Returns multiple matches — select the exact disease, not subtypes or umbrella syndromes. "Marfan syndrome" should resolve to ORPHAcode 558, not 284993 ("Marfan syndrome and Marfan-related disorders").

**Orphanet_search_diseases**: `query` (string REQUIRED). Fallback if the primary tool returns no results.

**Orphanet_get_gene_diseases**: `gene_symbol` (string REQUIRED, e.g., "FBN1"). Use when starting from a gene. Returns all diseases associated with the gene, including association type.

Key identifier formats: disease codes are ORPHAcode integers (e.g., 558 for Marfan syndrome); gene identifiers are HGNC symbols (e.g., FBN1); phenotypes use HPO CURIE format (e.g., HP:0001519).

---

## Phase 1: Disease Characterization

**Orphanet_get_disease**: `orpha_code` (string REQUIRED, e.g., "558"). Returns the official Orphanet definition and synonym list.

**Orphanet_get_classification**: `orpha_code` (string REQUIRED). Shows which disease hierarchies include this condition (e.g., "rare genetic diseases", "rare ophthalmic disorders"). Useful for understanding what kind of rare disease this is.

**Orphanet_get_natural_history**: `orpha_code` (string REQUIRED). Returns `average_age_of_onset` and `type_of_inheritance`. Inheritance mode (autosomal dominant, X-linked recessive, etc.) is critical context for interpreting variant pathogenicity and family risk.

**Orphanet_get_icd_mapping**: `orpha_code` (string REQUIRED). Maps to ICD-10/ICD-11 for clinical coding contexts.

---

## Phase 2: Phenotype Mapping (HPO)

**Orphanet_get_phenotypes**: `orpha_code` (string REQUIRED). Returns HPO phenotypes with frequency labels and whether each is a formal diagnostic criterion.

Frequency should guide your interpretation: phenotypes marked "Very frequent (99-80%)" are core features present in nearly all patients and should be weighted heavily in differential diagnosis. "Frequent (79-30%)" are supporting features. "Occasional (29-5%)" reflect variable presentations. "Excluded (0%)" are active rule-out criteria — their presence argues against the diagnosis.

When a phenotype is marked `diagnostic_criteria: "Diagnostic criterion"`, it belongs to the formal diagnostic framework for that disease, not just a statistical association.

### OLS for ontology lookups

When you need to look up an HPO term by description or resolve a CURIE to a label, use the OLS tools. Pass `ontology="hp"` to scope to HPO, `ontology="ordo"` for Orphanet terms, `ontology="mondo"` for MONDO disease terms.

**ols_search_terms**: `query` (string REQUIRED), `ontology` (string, optional), `rows` (int, alias `size`, default 10), `exact_match` (bool, default False).

**ols_get_term_info**: `term_id` (CURIE e.g., "HP:0001519") OR `term_iri`. Prefix-based ontology inference works automatically — "HP:" routes to hp, "MONDO:" to mondo, "ORDO:" to ordo.

**ols_get_term_children** / **ols_get_term_ancestors**: `term_id` or `term_iri`, `ontology` (optional). Useful for finding parent HPO categories or broadening/narrowing a phenotype search.

---

## Phase 3: Causative Gene Discovery

**Orphanet_get_genes**: `orpha_code` (string REQUIRED, alias: `disease_id`). Returns genes with their association types and loci.

The association type is crucial. "Disease-causing germli