Tooluniverse Rare Disease Diagnosis

Rare Disease Diagnosis Advisor

Systematic diagnosis support for rare diseases using phenotype matching, gene panel prioritization, and variant interpretation across Orphanet, OMIM, HPO, ClinVar, and structure-based analysis.

KEY PRINCIPLES: 1. Report-first - Create report file FIRST, update progressively 2. Phenotype-driven - Convert symptoms to HPO terms before searching 3. Multi-database triangulation - Cross-reference Orphanet, OMIM, OpenTargets 4. Evidence grading - Grade diagnoses by supporting evidence strength 5. English-first queries - Always use English terms in tool calls

LOOK UP, DON'T GUESS

When uncertain about any scientific fact, SEARCH databases first rather than reasoning from memory.

---

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.

Clinical Reasoning Framework (BEFORE Tools)

Apply these strategies to form a 3-5 candidate differential, then use tools to confirm/refute:

1. Multi-system involvement - Symptoms spanning 2+ organ systems = strongest rare disease signal. Ask: what single pathway explains ALL features? 2. Regression question - Losing abilities vs never acquired? Regression = neurodegenerative/metabolic storage. Stable = developmental/structural. 3. Trigger question - Episodic/triggered (fasting, illness, exercise) = metabolic disorder (often treatable). Constitutive = structural/degenerative. 4. Rarest feature first - Build differential from most specific finding, not most prominent. Check remaining features for consistency. 5. Treatable-first - Move treatable conditions to top for urgent workup (enzyme replacement, dietary, chelation, vitamin-responsive). 6. Occupational/environmental exposure - Latency up to 50 years. Asbestos/silica/heavy metals/solvents/farming. Always ask about PAST jobs. 7. Autoimmune differential - Which joints? Symmetric? Extra-articular? Serologic pattern? Organ under attack? 8. Rare syndrome signals - Named triads, common diagnoses failing to explain ALL findings, failed standard treatment, unusual lab findings. 9. Tools verify, not generate - Form hypothesis first, then use databases to confirm.

Common pitfalls: Felty's (RA+splenomegaly+neutropenia) mimics infection; SLE nephritis mimics PSGN (check ASO); occupational exposures trigger autoimmunity (silica→scleroderma/RA/SLE).

---

Tool Parameter Corrections

---

Workflow

Phase 0: Clinical Reasoning → 3-5 candidate differential
Phase 1: Phenotype → HPO terms (HPO_search_terms), core vs variable, onset, family history
Phase 2: Disease Matching → Orphanet_search_diseases, OMIM_search, DisGeNET_search_gene
Phase 3: Gene Panel → MARRVEL_get_gene (aggregated IDs) + MARRVEL_get_omim_phenotypes (OMIM disease+inheritance), ClinGen validation, GTEx expression, prioritization scoring
Phase 3.5: Expression Context → CELLxGENE, ChIPAtlas for tissue/cell-type confirmation
Phase 3.6: Pathway Analysis → KEGG, IntAct for convergent pathways
Phase 4: Variant Interpretation → FAVOR_annotate_variant (one-call: freq + CADD/SIFT/PolyPhen/AlphaMissense + ClinVar + conservation), then ClinVar, gnomAD frequency, EVE/SpliceAI, ACMG criteria
Phase 5: Structure Analysis → AlphaFold2, InterPro domains (for VUS)
Phase 6: Literature → PubMed, BioRxiv/MedRxiv, OpenAlex
Phase 7: Report Synthesis → Prioritized differential with next steps

Key Phase Details

Phase 2 - Disease Matching: Orphanet_search_diseases(operation="search_diseases", query=keyword) then Orphanet_get_genes(operation="get_genes", orpha_code=code). Score overlap: Excellent >80%, Good 60-80%, Possible 40-60%.

Phase 3 - Gene Panel: For each candidate gene, MARRVEL_get_gene(symbol) resolves OMIM/HGNC/Ensembl/Entrez/UniProt IDs in one call, and MARRVEL_get_omim_phenotypes(symbol) lists the Mendelian diseases linked to the gene with mode of inheritance — use the inheritance pattern to filter candidates against the pedigree (e.g. drop AR genes for a clearly dominant pedigree). Then ClinGen classification drives inclusion (Definitive/Strong/Moderate = include; Limited = flag; Disputed/Refuted = exclude). Scoring: Tier 1 (top disease gene +5), Tier 2 (multi-disease +3), Tier 3 (ClinGen Definitive +3), Tier 4 (tissue expression +2), Tier 5 (pLI >0.9 +1).

Phase 4 - Variants: Start with FAVOR_annotate_variant("chr-pos-ref-alt") (GRCh38) for a single-call snapshot — population frequencies (gnomAD by ancestry, BRAVO), GENCODE consequence, CADD/SIFT/PolyPhen-2/AlphaMissense scores, conservation, and ClinVar significance — then drill into ClinVar/gnomAD/EVE/SpliceAI for detail. gnomAD frequency classes: ultra-rare <0.00001, rare <0.0001, low-freq <0.01. ACMG: PVS1 (null), PS1 (same AA), PM2 (absent pop), PP3 (computational), BA1 (>5% AF). 2+ concordant predictors strengthen PP3.

---

Evidence Grading

---

Fallback Chains

---

Reference Files

• DIAGNOSTIC_WORKFLOW.md - Code examples and algorithms per phase
• REPORT_TEMPLATE.md - Report template and examples
• CHECKLIST.md - Interactive completeness checklist
• scripts/clinical_patterns.py - Clinical pattern lookup (syndromes, differentials, red flags, occupational exposures)

Rare Disease Diagnosis Checklist

Pre-delivery verification checklist for rare disease diagnostic reports.

Report Quality Checklist

Structure & Format

• [ ] Report file created: [PATIENT_ID]_rare_disease_report.md
• [ ] All 8 main sections present
• [ ] Executive summary completed (not [Researching...])
• [ ] Data sources section populated

Phase 1: Phenotype Standardization

• [ ] All clinical features converted to HPO terms
• [ ] HPO IDs provided for each term
• [ ] Core features distinguished from variable
• [ ] Age of onset documented
• [ ] Family history recorded (or "Unknown")
• [ ] Inheritance pattern suspected (AD/AR/XL/Unknown)

Phase 2: Disease Matching

• [ ] ≥5 candidate diseases identified (or all if fewer match)
• [ ] Each disease has ORPHA ID
• [ ] Each disease has OMIM ID (if available)
• [ ] Phenotype match % calculated for each
• [ ] Diseases ranked by match score
• [ ] Inheritance pattern for each disease
• [ ] Causative genes listed for each disease
• [ ] Top 3 diseases have detailed feature comparison

Phase 3: Gene Panel

• [ ] ≥5 genes in recommended panel (or all from top diseases)
• [ ] Each gene has evidence level (ClinGen: Definitive/Strong/Moderate)
• [ ] Constraint scores (pLI) provided
• [ ] Expression validation for relevant tissue
• [ ] Genes prioritized by tier (★★★/★★☆/★☆☆)
• [ ] Testing strategy recommended (single gene vs panel vs WES)
• [ ] Cost-effectiveness considered

Phase 4: Variant Interpretation (if variants provided)

• [ ] ClinVar ID and classification retrieved
• [ ] gnomAD allele frequency checked
• [ ] Population-specific frequencies noted
• [ ] CADD/REVEL scores obtained
• [ ] ACMG criteria systematically applied
• [ ] Each criterion has evidence documented
• [ ] Preliminary classification stated
• [ ] Confidence in classification noted

Phase 5: Structure Analysis (if VUS)

• [ ] NVIDIA_API_KEY availability documented
• [ ] Structure prediction method stated
• [ ] pLDDT confidence at variant position reported
• [ ] Domain location assessed
• [ ] Conservation data included
• [ ] Nearby pathogenic variants noted
• [ ] Structural evidence summarized
• [ ] Impact on ACMG classification stated

Phase 6: Recommendations

• [ ] ≥3 specific next steps listed
• [ ] Priority order for actions
• [ ] Specialist referrals suggested (genetics, cardiology, etc.)
• [ ] Family screening recommendations
• [ ] Follow-up timeline suggested
• [ ] Genetic counseling mentioned

Phase 7: Data Gaps

• [ ] All gaps aggregated in one section
• [ ] Reason for each gap documented
• [ ] Alternative approaches suggested

---

Citation Requirements

Every Section Must Include

• [ ] Source database name
• [ ] Tool used (in backticks)
• [ ] Specific identifiers (ORPHA, OMIM, HP, etc.)

Format Examples

*Source: Orphanet via `Orphanet_558` (ORPHA:558)*
*Source: OMIM via `OMIM_get_entry` (MIM:154700)*
*Source: HPO via `HPO_search_terms` (HP:0001166)*
*Source: ClinVar via `ClinVar_get_variant_details` (VCV000012345)*
*Source: gnomAD via `gnomad_get_variant` (AF: 0.00001)*
*Source: NVIDIA NIM via `NvidiaNIM_alphafold2` (pLDDT: 85.3)*

---

Evidence Grading

All Diagnoses Must Have

• [ ] Evidence tier assigned (★★★ to ☆☆☆)
• [ ] Phenotype match % documented
• [ ] Genetic evidence level (if variant found)

Tier Definitions

---

Quantified Minimums

---

Phenotype-Specific Checks

Connective Tissue Phenotypes

• [ ] Cardiac features assessed (aortic root, mitral valve)
• [ ] Skeletal features documented (height, proportions)
• [ ] Ocular features checked (lens, myopia)
• [ ] Skin findings noted (striae, elasticity)
• [ ] Ghent criteria referenced (if Marfan suspected)

Neurological Phenotypes

• [ ] Developmental milestones documented
• [ ] Seizure history (type, onset, frequency)
• [ ] MRI findings (if available)
• [ ] Cognitive assessment
• [ ] Movement disorders noted

Metabolic Phenotypes

• [ ] Biochemical markers (if available)
• [ ] Dietary history relevant
• [ ] Acute decompensation episodes
• [ ] Treatment response history

---

Output Files

Required

• [ ] [PATIENT_ID]_rare_disease_report.md - Main report

Optional (if applicable)

• [ ] [PATIENT_ID]_gene_panel.csv - Prioritized genes
• [ ] [PATIENT_ID]_variant_interpretation.csv - Variant details

CSV Column Requirements

gene_panel.csv:

Gene,Evidence_Level,Constraint_pLI,Associated_Diseases,Priority_Tier

variant_interpretation.csv:

Variant,Gene,ClinVar_Class,gnomAD_AF,ACMG_Criteria,Classification

---

Final Review

Before Delivery

• [ ] No [Researching...] placeholders remaining
• [ ] All tables properly formatted
• [ ] No empty sections (use "Not applicable" if needed)
• [ ] Executive summary synthesizes key findings
• [ ] Most likely diagnosis clearly stated
• [ ] Recommendations are actionable
• [ ] Report is understandable to referring clinician

Common Issues to Avoid

• [ ] HPO terms without IDs
• [ ] Diseases without ORPHA/OMIM identifiers
• [ ] Variants without population frequency
• [ ] ACMG classification without documented criteria
• [ ] Recommendations without priority order
• [ ] Missing family history implications

---

Urgent Findings Protocol

If any of these found, flag prominently:

• [ ] Pathogenic variant in actionable gene
• [ ] High suspicion for condition requiring immediate intervention
• [ ] Cardiac abnormality suggesting aortic pathology
• [ ] Metabolic emergency risk
• [ ] Cancer predisposition syndrome

Diagnostic Workflow: Detailed Procedures

Detailed diagnostic algorithms, code examples, and phase-by-phase procedures for the Rare Disease Diagnosis skill.

---

Phase 1: Phenotype Standardization

1.1 Convert Symptoms to HPO Terms

def standardize_phenotype(tu, symptoms_list):
    """Convert clinical descriptions to HPO terms."""
    hpo_terms = []

    for symptom in symptoms_list:
        # Search HPO for matching terms
        results = tu.tools.HPO_search_terms(query=symptom)
        if results:
            hpo_terms.append({
                'original': symptom,
                'hpo_id': results[0]['id'],
                'hpo_name': results[0]['name'],
                'confidence': 'exact' if symptom.lower() in results[0]['name'].lower() else 'partial'
            })

    return hpo_terms

1.2 Phenotype Categories

---

Phase 2: Disease Matching

2.1 Orphanet Disease Search

def match_diseases_orphanet(tu, symptom_keywords):
    """Find rare diseases matching symptoms using Orphanet."""
    candidate_diseases = []

    # Search Orphanet by disease keywords
    for keyword in symptom_keywords:
        results = tu.tools.Orphanet_search_diseases(
            operation="search_diseases",
            query=keyword
        )
        if results.get('status') == 'success':
            candidate_diseases.extend(results['data']['results'])

    # Get genes for each disease
    for disease in candidate_diseases:
        orpha_code = disease.get('ORPHAcode')
        genes = tu.tools.Orphanet_get_genes(
            operation="get_genes",
            orpha_code=orpha_code
        )
        disease['genes'] = genes.get('data', {}).get('genes', [])

    return deduplicate_and_rank(candidate_diseases)

2.2 OMIM Cross-Reference

def cross_reference_omim(tu, orphanet_diseases, gene_symbols):
    """Get OMIM details for diseases and genes."""
    omim_data = {}

    for gene in gene_symbols:
        search_result = tu.tools.OMIM_search(
            operation="search",
            query=gene,
            limit=5
        )
        if search_result.get('status') == 'success':
            for entry in search_result['data'].get('entries', []):
                mim_number = entry.get('mimNumber')

                details = tu.tools.OMIM_get_entry(
                    operation="get_entry",
                    mim_number=str(mim_number)
                )

                synopsis = tu.tools.OMIM_get_clinical_synopsis(
                    operation="get_clinical_synopsis",
                    mim_number=str(mim_number)
                )

                omim_data[gene] = {
                    'mim_number': mim_number,
                    'details': details.get('data', {}),
                    'clinical_synopsis': synopsis.get('data', {})
                }

    return omim_data

2.3 DisGeNET Gene-Disease Associations

def get_gene_disease_associations(tu, gene_symbols):
    """Get gene-disease associations from DisGeNET."""
    associations = {}

    for gene in gene_symbols:
        result = tu.tools.DisGeNET_search_gene(
            operation="search_gene",
            gene=gene,
            limit=20
        )

        if result.get('status') == 'success':
            associations[gene] = result['data'].get('associations', [])

    return associations

def get_disease_genes_disgenet(tu, disease_name):
    """Get all genes associated with a disease."""
    result = tu.tools.DisGeNET_search_disease(
        operation="search_disease",
        disease=disease_name,
        limit=30
    )
    return result.get('data', {}).get('associations', [])

2.4 Phenotype Overlap Scoring

---

Phase 3: Gene Panel Identification

3.1 Extract Disease Genes

def build_gene_panel(tu, candidate_diseases):
    """Build prioritized gene panel from candidate diseases."""
    genes = {}

    for disease in candidate_diseases:
        for gene in disease['genes']:
            if gene not in genes:
                genes[gene] = {
                    'symbol': gene,
                    'diseases': [],
                    'evidence_level': 'unknown'
                }
            genes[gene]['diseases'].append(disease['name'])

    return genes

3.2 ClinGen Gene-Disease Validity Check

Critical: Always verify gene-disease validity through ClinGen before including in panel.

def get_clingen_gene_evidence(tu, gene_symbol):
    """
    Get ClinGen gene-disease validity and dosage sensitivity.
    ESSENTIAL for rare disease gene panel prioritization.
    """

    # 1. Gene-disease validity classification
    validity = tu.tools.ClinGen_search_gene_validity(gene=gene_symbol)

    validity_levels = []
    diseases_with_validity = []
    if validity.get('data'):
        for entry in validity.get('data', []):
            validity_levels.append(entry.get('Classification'))
            diseases_with_validity.append({
                'disease': entry.get('Disease Label'),
                'mondo_id': entry.get('Disease ID (MONDO)'),
                'classification': entry.get('Classification'),
                'inheritance': entry.get('Inheritance')
            })

    # 2. Dosage sensitivity (critical for CNV interpretation)
    dosage = tu.tools.ClinGen_search_dosage_sensitivity(gene=gene_symbol)

    hi_score = None
    ts_score = None
    if dosage.get('data'):
        for entry in dosage.get('data', []):
            hi_score = entry.get('Haploinsufficiency Score')
            ts_score = entry.get('Triplosensitivity Score')
            break

    # 3. Clinical actionability (return of findings context)
    actionability = tu.tools.ClinGen_search_actionability(gene=gene_symbol)
    is_actionable = (actionability.get('adult_count', 0) > 0 or
                     actionability.get('pediatric_count', 0) > 0)

    # Determine best evidence level
    level_priority = ['Definitive', 'Strong', 'Moderate', 'Limited', 'Disputed', 'Refuted']
    best_level = 'Not curated'
    for level in level_priority:
        if level in validity_levels:
            best_level = level
            break

    return {
        'gene': gene_symbol,
        'evidence_level': best_level,
        'diseases_curated': diseases_with_validity,
        'haploinsufficiency_score': hi_score,
        'triplosensitivity_score': ts_score,
        'is_actionable': is_actionable,
        'include_in_panel': best_level in ['Definitive', 'Strong', 'Moderate']
    }

def prioritize_genes_with_clingen(tu, gene_list):
    """Prioritize genes using ClinGen evidence levels."""

    prioritized = []
    for gene in gene_list:
        evidence = get_clingen_gene_evidence(tu, gene)

        score = 0
        if evidence['evidence_level'] == 'Definitive':
            score = 5
        elif evidence['evidence_level'] == 'Strong':
            score = 4
        elif evidence['evidence_level'] == 'Moderate':
            score = 3
        elif evidence['evidence_level'] == 'Limited':
            score = 1

        if evidence['haploinsufficiency_score'] == '3':
            score += 1
        if evidence['is_actionable']:
            score += 1

        prioritized.append({
            **evidence,
            'priority_score': score
        })

    return sorted(prioritized, key=lambda x: x['priority_score'], reverse=True)

ClinGen Classification Impact on Panel:

3.3 Gene Prioritization Criteria

3.4 Expression Validation

def validate_expression(tu, gene_symbol, affected_tissue):
    """Check if gene is expressed in relevant tissue."""
    gene_info = tu.tools.MyGene_query_genes(q=gene_symbol, species="human")
    ensembl_id = gene_info.get('ensembl', {}).get('gene')

    expression = tu.tools.GTEx_get_median_gene_expression(
        gencode_id=f"{ensembl_id}.latest"
    )

    return expression.get(affected_tissue, 0) > 1  # TPM > 1

---

Phase 3.5: Expression & Tissue Context

Cell-Type Specific Expression (CELLxGENE)

def get_cell_type_expression(tu, gene_symbol, affected_tissues):
    """Get single-cell expression to validate tissue relevance."""

    expression = tu.tools.CELLxGENE_get_expression_data(
        gene=gene_symbol,
        tissue=affected_tissues[0] if affected_tissues else "all"
    )

    cell_metadata = tu.tools.CELLxGENE_get_cell_metadata(
        gene=gene_symbol
    )

    high_expression = [
        ct for ct in expression
        if ct.get('mean_expression', 0) > 1.0
    ]

    return {
        'expression_data': expression,
        'high_expression_cells': high_expression,
        'total_cell_types': len(cell_metadata)
    }

Regulatory Context (ChIPAtlas)

def get_regulatory_context(tu, gene_symbol):
    """Get transcription factor binding for candidate genes."""

    tf_binding = tu.tools.ChIPAtlas_enrichment_analysis(
        gene=gene_symbol,
        cell_type="all"
    )

    peaks = tu.tools.ChIPAtlas_get_peak_data(
        gene=gene_symbol,
        experiment_type="TF"
    )

    return {
        'transcription_factors': tf_binding,
        'regulatory_peaks': peaks
    }

---

Phase 3.6: Pathway Analysis

KEGG Pathway Context

def get_pathway_context(tu, gene_symbols):
    """Get pathway context for candidate genes."""

    pathways = {}
    for gene in gene_symbols:
        kegg_genes = tu.tools.kegg_find_genes(query=f"hsa:{gene}")

        if kegg_genes:
            gene_info = tu.tools.kegg_get_gene_info(gene_id=kegg_genes[0]['id'])
            pathways[gene] = gene_info.get('pathways', [])

    return pathways

Protein-Protein Interactions (IntAct)

def get_protein_interactions(tu, gene_symbol):
    """Get interaction partners for candidate genes."""

    interactions = tu.tools.intact_search_interactions(
        query=gene_symbol,
        species="human"
    )

    network = tu.tools.intact_get_interaction_network(
        gene=gene_symbol,
        depth=1
    )

    return {
        'interactions': interactions,
        'network': network,
        'interactor_count': len(interactions)
    }

---

Phase 4: Variant Interpretation

4.1 ClinVar Lookup

def interpret_variant(tu, variant_hgvs):
    """Get ClinVar interpretation for variant."""
    result = tu.tools.ClinVar_search_variants(query=variant_hgvs)

    return {
        'clinvar_id': result.get('id'),
        'classification': result.get('clinical_significance'),
        'review_status': result.get('review_status'),
        'conditions': result.get('conditions'),
        'last_evaluated': result.get('last_evaluated')
    }

4.2 Population Frequency

def check_population_frequency(tu, variant_id):
    """Get gnomAD allele frequency."""
    freq = tu.tools.gnomad_get_variant(variant_id=variant_id)

    if freq['allele_frequency'] < 0.00001:
        rarity = "Ultra-rare"
    elif freq['allele_frequency'] < 0.0001:
        rarity = "Rare"
    elif freq['allele_frequency'] < 0.01:
        rarity = "Low frequency"
    else:
        rarity = "Common (likely benign)"

    return freq, rarity

4.3 Computational Pathogenicity Prediction

Use multiple prediction tools for VUS interpretation:

def comprehensive_vus_prediction(tu, variant_info):
    """
    Combine multiple prediction tools for VUS classification.
    Critical for rare disease variants not in ClinVar.
    """
    predictions = {}

    # 1. CADD - Deleteriousness
    cadd = tu.tools.CADD_get_variant_score(
        chrom=variant_info['chrom'],
        pos=variant_info['pos'],
        ref=variant_info['ref'],
        alt=variant_info['alt'],
        version="GRCh38-v1.7"
    )
    if cadd.get('status') == 'success':
        predictions['cadd'] = {
            'score': cadd['data'].get('phred_score'),
            'interpretation': cadd['data'].get('interpretation'),
            'acmg': 'PP3' if cadd['data'].get('phred_score', 0) >= 20 else 'neutral'
        }

    # 2. AlphaMissense - DeepMind pathogenicity
    if variant_info.get('uniprot_id') and variant_info.get('aa_change'):
        am = tu.tools.AlphaMissense_get_variant_score(
            uniprot_id=variant_info['uniprot_id'],
            variant=variant_info['aa_change']
        )
        if am.get('status') == 'success' and am.get('data'):
            classification = am['data'].get('classification')
            predictions['alphamissense'] = {
                'score': am['data'].get('pathogenicity_score'),
                'classification': classification,
                'acmg': 'PP3 (strong)' if classification == 'pathogenic' else (
                    'BP4 (strong)' if classification == 'benign' else 'neutral'
                )
            }

    # 2b. ESMC-6B SAE - Mechanism of effect
    # AlphaMissense answers "is it pathogenic?". SAE answers "how?" — which
    # protein-language-model features are disrupted (catalytic, ligand-binding,
    # PTM, etc.). Use when AlphaMissense is ambiguous or when the report
    # needs a mechanistic explanation alongside the pathogenicity score.
    # Requires ESM_API_KEY env var; missense only. Fetches the WT protein
    # sequence on demand from UniProt and parses ref/pos/alt from aa_change.
    import re
    aa_match = re.match(r'^p?\.?([A-Z])(\d+)([A-Z])$', variant_info.get('aa_change', ''))
    if variant_info.get('uniprot_id') and aa_match:
        ref_aa, pos_str, alt_aa = aa_match.groups()
        position = int(pos_str)
        up = tu.tools.UniProt_get_entry_by_accession(accession=variant_info['uniprot_id'])
        wt_seq = ((up.get('data') or {}).get('sequence', {}) or {}).get('value') if up.get('status') == 'success' else None
        # Only call SAE when the WT residue at `position` matches `ref_aa` —
        # otherwise the variant is on a different isoform than the UniProt
        # canonical sequence, and a silent skip is safer than the tool's
        # ref_aa-mismatch error in the diagnostic report.
        if wt_seq and 1 <= position <= len(wt_seq) and wt_seq[position - 1] == ref_aa:
            mech = tu.tools.ESM_explain_variant_mechanism(
                sequence=wt_seq, position=position, ref_aa=ref_aa, alt_aa=alt_aa,
                top_k_features=5,
            )
            if mech.get('status') == 'success':
                predictions['sae_mechanism'] = {
                    'summary': mech['data']['mechanism_summary'],
                    'lost_categories': mech['data']['lost_feature_categories'],
                    'gained_categories': mech['data']['gained_feature_categories'],
                    # Map to ACMG: catalytic / ligand-binding / ptm loss is
                    # mechanistic evidence supporting PP3 (does not replace
                    # functional study PS3).
                }

    # 3. EVE - Evolutionary prediction
    eve = tu.tools.EVE_get_variant_score(
        chrom=variant_info['chrom'],
        pos=variant_info['pos'],
        ref=variant_info['ref'],
        alt=variant_info['alt']
    )
    if eve.get('status') == 'success':
        eve_scores = eve['data'].get('eve_scores', [])
        if eve_scores:
            predictions['eve'] = {
                'score': eve_scores[0].get('eve_score'),
                'classification': eve_scores[0].get('classification'),
                'acmg': 'PP3' if eve_scores[0].get('eve_score', 0) > 0.5 else 'BP4'
            }

    # 4. SpliceAI - Splice variant prediction
    variant_str = f"chr{variant_info['chrom']}-{variant_info['pos']}-{variant_info['ref']}-{variant_info['alt']}"
    splice = tu.tools.SpliceAI_predict_splice(
        variant=variant_str,
        genome="38"
    )
    if splice.get('data'):
        max_score = splice['data'].get('max_delta_score', 0)
        interpretation = splice['data'].get('interpretation', '')

        if max_score >= 0.8:
            splice_acmg = 'PP3 (strong) - high splice impact'
        elif max_score >= 0.5:
            splice_acmg = 'PP3 (moderate) - splice impact'
        elif max_score >= 0.2:
            splice_acmg = 'PP3 (supporting) - possible splice effect'
        else:
            splice_acmg = 'BP7 (if synonymous) - no splice impact'

        predictions['spliceai'] = {
            'max_delta_score': max_score,
            'interpretation': interpretation,
            'scores': splice['data'].get('scores', []),
            'acmg': splice_acmg
        }

    # Consensus for PP3/BP4
    damaging = sum(1 for p in predictions.values() if 'PP3' in p.get('acmg', ''))
    benign = sum(1 for p in predictions.values() if 'BP4' in p.get('acmg', ''))

    return {
        'predictions': predictions,
        'consensus': {
            'damaging_count': damaging,
            'benign_count': benign,
            'pp3_applicable': damaging >= 2 and benign == 0,
            'bp4_applicable': benign >= 2 and damaging == 0
        }
    }

4.4 ACMG Classification Criteria

Enhanced PP3 Evidence:

• AlphaMissense pathogenic (>0.564) = Strong PP3 support (~90% accuracy)
• CADD >=20 + EVE >0.5 = Multiple concordant predictions
• Agreement from 2+ predictors strengthens PP3 evidence

---

Phase 5: Structure Analysis for VUS

5.1 When to Perform Structure Analysis

Perform when:

• Variant is VUS or conflicting interpretations
• Missense variant in critical domain
• Novel variant not in databases
• Additional evidence needed for classification

5.2 Structure Prediction (NVIDIA NIM)

def analyze_variant_structure(tu, protein_sequence, variant_position):
    """Predict structure and analyze variant impact."""

    structure = tu.tools.NvidiaNIM_alphafold2(
        sequence=protein_sequence,
        algorithm="mmseqs2",
        relax_prediction=False
    )

    variant_plddt = get_residue_plddt(structure, variant_position)
    confidence = "High" if variant_plddt > 70 else "Low"

    return {
        'structure': structure,
        'variant_plddt': variant_plddt,
        'confidence': confidence
    }

5.3 Domain Impact Assessment

def assess_domain_impact(tu, uniprot_id, variant_position):
    """Check if variant affects functional domain."""

    domains = tu.tools.InterPro_get_protein_domains(accession=uniprot_id)

    for domain in domains:
        if domain['start'] <= variant_position <= domain['end']:
            return {
                'in_domain': True,
                'domain_name': domain['name'],
                'domain_function': domain['description']
            }

    return {'in_domain': False}

---

Phase 6: Literature Evidence

6.1 Published Literature (PubMed)

def search_disease_literature(tu, disease_name, genes):
    """Search for relevant published literature."""

    disease_papers = tu.tools.PubMed_search_articles(
        query=f'"{disease_name}" AND (genetics OR mutation OR variant)',
        limit=20
    )

    gene_papers = []
    for gene in genes[:5]:
        papers = tu.tools.PubMed_search_articles(
            query=f'"{gene}" AND rare disease AND pathogenic',
            limit=10
        )
        gene_papers.extend(papers)

    return {
        'disease_literature': disease_papers,
        'gene_literature': gene_papers
    }

6.2 Preprint Literature (BioRxiv/MedRxiv)

def search_preprints(tu, disease_name, genes):
    """Search preprints for cutting-edge findings."""

    biorxiv = tu.tools.BioRxiv_list_recent_preprints(
        query=f"{disease_name} genetics",
        limit=10
    )

    arxiv = tu.tools.ArXiv_search_papers(
        query=f"rare disease diagnosis {' OR '.join(genes[:3])}",
        category="q-bio",
        limit=5
    )

    return {
        'biorxiv': biorxiv,
        'arxiv': arxiv
    }

6.3 Citation Analysis (OpenAlex)

def analyze_citations(tu, key_papers):
    """Analyze citation network for key papers."""

    citation_analysis = []
    for paper in key_papers[:5]:
        work = tu.tools.openalex_search_works(
            query=paper['title'],
            limit=1
        )
        if work:
            citation_analysis.append({
                'title': paper['title'],
                'citations': work[0].get('cited_by_count', 0),
                'year': work[0].get('publication_year')
            })

    return citation_analysis

Rare Disease Diagnosis - Examples

Example 1: Connective Tissue Disorder

User Query

"23-year-old male with tall stature (6'5"), long fingers, joint hypermobility, and recent echo showing aortic root dilation 4.2cm. Father had similar build and died suddenly at age 45. What could this be?"

Expected Output

# Rare Disease Diagnostic Report

**Patient ID**: Example-001 | **Date**: 2026-02-04

---

## Executive Summary

This patient presents with a classic phenotype highly suggestive of **Marfan syndrome** (★★★). Key findings include tall stature, arachnodactyly, joint hypermobility, and aortic root dilation with a positive family history of sudden death. The phenotype match is 89% for Marfan syndrome. **Immediate FBN1 genetic testing is recommended**, along with urgent cardiology referral given the aortic dilation and family history of sudden death.

---

## 1. Phenotype Analysis

### 1.1 Standardized HPO Terms

| Clinical Feature | HPO Term | HPO ID | Category |
|------------------|----------|--------|----------|
| Tall stature (6'5") | Tall stature | HP:0000098 | Core |
| Long fingers | Arachnodactyly | HP:0001166 | Core |
| Joint hypermobility | Joint hypermobility | HP:0001382 | Core |
| Aortic root dilation | Aortic root aneurysm | HP:0002616 | Core |
| Family history of sudden death | Sudden cardiac death | HP:0001645 | Family |

**Total HPO Terms**: 5
**Age of Onset**: Childhood (stature)
**Family History**: Father deceased age 45, sudden death, similar phenotype
**Suspected Inheritance**: Autosomal dominant

*Source: HPO via `HPO_search_terms`*

---

## 2. Differential Diagnosis

### 2.1 Ranked Candidate Diseases

| Rank | Disease | ORPHA | OMIM | Match | Inheritance | Genes |
|------|---------|-------|------|-------|-------------|-------|
| 1 | Marfan syndrome | 558 | 154700 | 89% ★★★ | AD | FBN1 |
| 2 | Loeys-Dietz syndrome | 60030 | 609192 | 72% ★★☆ | AD | TGFBR1, TGFBR2, SMAD3 |
| 3 | Vascular EDS | 286 | 130050 | 58% ★☆☆ | AD | COL3A1 |
| 4 | Familial TAAD | 91387 | 607086 | 52% ★☆☆ | AD | ACTA2, MYH11 |
| 5 | Homocystinuria | 394 | 236200 | 45% ☆☆☆ | AR | CBS |

### 2.2 Disease Details

#### 1. Marfan Syndrome (★★★)

**ORPHA**: 558 | **OMIM**: 154700 | **Prevalence**: 1-5/10,000

**Phenotype Comparison**:
| Patient Feature | Marfan Feature | Frequency | Match |
|-----------------|----------------|-----------|-------|
| Tall stature | Tall stature | 95% | ✓ |
| Arachnodactyly | Arachnodactyly | 90% | ✓ |
| Joint hypermobility | Joint hypermobility | 85% | ✓ |
| Aortic root dilation | Aortic root dilation | 80% | ✓ |
| Family sudden death | Aortic dissection | 30% | ✓ |
| Ectopia lentis | Ectopia lentis | 60% | Not assessed |

**Ghent Criteria Assessment**:
- Aortic root Z-score: Likely ≥2 (4.2cm at age 23)
- Systemic score: ≥7 points (tall, arachnodactyly, joint hypermobility)
- FBN1 mutation: Pending testing
- **Clinical diagnosis likely met even without genetic testing**

**Gene**: FBN1 (fibrillin-1)
- ClinGen validity: Definitive
- Inheritance: AD (25% de novo)

*Source: Orphanet via `Orphanet_558`, OMIM via `OMIM_get_entry`*

#### 2. Loeys-Dietz Syndrome (★★☆)

**ORPHA**: 60030 | **OMIM**: 609192

**Key Distinguishing Features** (not present in patient):
- Hypertelorism (wide-set eyes)
- Bifid uvula or cleft palate
- Arterial tortuosity
- Translucent skin

**Consider if**: FBN1 negative AND craniofacial features present

*Source: Orphanet, OMIM*

---

## 3. Recommended Gene Panel

### 3.1 Prioritized Genes

| Priority | Gene | Disease | Evidence | pLI | Expression |
|----------|------|---------|----------|-----|------------|
| ★★★ | FBN1 | Marfan | Definitive | 1.00 | Aorta, heart |
| ★★☆ | TGFBR1 | LDS1 | Definitive | 0.98 | Ubiquitous |
| ★★☆ | TGFBR2 | LDS2 | Definitive | 0.99 | Ubiquitous |
| ★★☆ | SMAD3 | LDS3 | Definitive | 0.89 | Ubiquitous |
| ★☆☆ | COL3A1 | vEDS | Definitive | 1.00 | Connective |
| ★☆☆ | ACTA2 | FTAAD | Definitive | 0.97 | Smooth muscle |

### 3.2 Testing Strategy

**Recommended Approach**:
1. **Immediate**: FBN1 sequencing + deletion/duplication analysis
   - Highest pre-test probability
   - Expected turnaround: 2-4 weeks
   
2. **If FBN1 negative**: Aortopathy gene panel
   - TGFBR1, TGFBR2, SMAD3, COL3A1, ACTA2, MYH11
   
3. **If panel negative**: Consider WES with phenotype-guided analysis

*Source: ClinGen gene-disease validity, GTEx expression*

---

## 4. Variant Interpretation

**No variants provided for interpretation.**

Genetic testing recommended - see Section 3.

---

## 5. Structural Analysis

**Not applicable** - No VUS requiring structural analysis.

---

## 6. Clinical Recommendations

### 6.1 Diagnostic Next Steps

| Priority | Action | Rationale | Timeline |
|----------|--------|-----------|----------|
| 1 | **Urgent cardiology referral** | Aortic root 4.2cm + family history | This week |
| 2 | **FBN1 genetic testing** | Confirm diagnosis, family cascade | Order now |
| 3 | **Ophthalmology exam** | Ectopia lentis screening | Within 1 month |
| 4 | **Full skeletal assessment** | Document systemic features | Within 1 month |

### 6.2 Specialist Referrals

- **Cardiology** (URGENT): Aortic surveillance, beta-blocker consideration
- **Medical Genetics**: Genetic counseling, testing coordination
- **Ophthalmology**: Slit-lamp exam for ectopia lentis
- **Orthopedics**: Scoliosis screening if indicated

### 6.3 Family Screening

**High priority given family history**:
- Father deceased (autopsy results if available)
- Any siblings should be offered:
  - Clinical screening (echo, skeletal exam)
  - Genetic testing once proband result available
- Extended family (paternal) should be informed

### 6.4 Urgent Considerations

⚠️ **URGENT**: Given aortic root dilation AND family history of sudden death:
- Avoid competitive sports and isometric exercise
- Discuss blood pressure management
- Review for aortic dissection symptoms
- Cardiology referral within 1 week

---

## 7. Data Gaps & Limitations

| Gap | Impact | Recommendation |
|-----|--------|----------------|
| No ophthalmology exam | Cannot assess ectopia lentis | Schedule exam |
| Echo Z-score not calculated | Need BSA-adjusted measurement | Request from cardiology |
| Father's autopsy unknown | Cannot confirm aortic dissection | Obtain records |
| No genetic testing yet | Diagnosis presumptive | Order FBN1 testing |

---

## 8. Data Sources

| Tool | Query | Data Retrieved |
|------|-------|----------------|
| HPO_search_terms | Patient symptoms | HPO term mapping |
| Orphanet_558 | Marfan syndrome | Disease details |
| OMIM_get_entry | 154700 | Clinical synopsis |
| ClinGen | FBN1-Marfan | Gene-disease validity |
| GTEx | FBN1 expression | Tissue expression |

---

Example 2: Pediatric Neurological Phenotype

User Query

"5-year-old with developmental delay, hypotonia, seizures starting at age 2, and MRI showing periventricular white matter changes. WES found a VUS: GFAP c.1186C>T (p.Arg396Cys). What's the diagnosis?"

Expected Output (Key Sections)

# Rare Disease Diagnostic Report

**Patient ID**: Example-002 | **Date**: 2026-02-04

---

## Executive Summary

This patient's phenotype and VUS in GFAP are highly consistent with **Alexander disease** (★★★). The combination of developmental delay, hypotonia, seizures, and frontal-predominant white matter changes in a young child matches infantile/juvenile Alexander disease. The GFAP p.Arg396Cys variant affects a highly conserved residue in the rod domain. **Structural analysis and segregation studies are recommended to support reclassification of this VUS to Likely Pathogenic.**

---

## 1. Phenotype Analysis

| Clinical Feature | HPO Term | HPO ID | Category |
|------------------|----------|--------|----------|
| Developmental delay | Global developmental delay | HP:0001263 | Core |
| Hypotonia | Muscular hypotonia | HP:0001252 | Core |
| Seizures (age 2) | Seizures | HP:0001250 | Core |
| White matter changes | Leukoencephalopathy | HP:0002352 | Core |
| Frontal predominance | Frontal white matter abnormality | HP:0012762 | Specific |

---

## 2. Differential Diagnosis

| Rank | Disease | ORPHA | Match | Key Features |
|------|---------|-------|-------|--------------|
| 1 | Alexander disease | 58 | 92% ★★★ | GFAP, frontal WM, macrocephaly |
| 2 | Vanishing white matter | 135 | 68% ★★☆ | eIF2B genes, progressive |
| 3 | Canavan disease | 141 | 55% ★☆☆ | ASPA, NAA elevated |
| 4 | Metachromatic leukodystrophy | 512 | 48% ★☆☆ | ARSA, progressive |

### Alexander Disease Details

**Diagnostic Criteria**:
1. Clinical: Macrocephaly, seizures, developmental delay ✓
2. MRI: Frontal-predominant white matter changes ✓
3. Genetic: Heterozygous GFAP variant ✓ (VUS)

*Source: Orphanet via `Orphanet_58`*

---

## 4. Variant Interpretation

### Variant: GFAP c.1186C>T (p.Arg396Cys)

| Property | Value | Interpretation |
|----------|-------|----------------|
| Gene | GFAP | Alexander disease gene |
| Consequence | Missense | Amino acid change |
| ClinVar | VUS | 1 submission |
| gnomAD AF | 0.0000032 | Absent (PM2) |
| CADD | 29.2 | Deleterious |
| REVEL | 0.89 | Likely damaging |

### ACMG Evidence

| Criterion | Evidence | Strength |
|-----------|----------|----------|
| PM2 | Absent from gnomAD | Moderate |
| PP3 | CADD=29.2, REVEL=0.89 | Supporting |
| PP4 | Phenotype specific for Alexander | Supporting |
| PM1 | Located in rod domain (critical) | Moderate |

**Current Classification**: VUS (2 Moderate + 2 Supporting)
**With segregation (PS2) or functional data**: Would become Likely Pathogenic

---

## 5. Structural Analysis

### 5.1 Structure Prediction

**Method**: AlphaFold2 via NVIDIA NIM
**Protein**: Glial fibrillary acidic protein (GFAP)
**Sequence Length**: 432 amino acids

| Metric | Value |
|--------|-------|
| Mean pLDDT | 78.4 |
| Position 396 pLDDT | 89.2 (high confidence) |
| Domain | Rod domain, coil 2B |

### 5.2 Variant Impact

**p.Arg396Cys Analysis**:

| Feature | Finding |
|---------|---------|
| Location | Rod domain (coiled-coil) |
| Wild-type | Arginine (positive, polar) |
| Mutant | Cysteine (neutral, potential disulfide) |
| Conservation | 100% across vertebrates |
| Nearby pathogenic | p.Arg398Trp (Pathogenic) |

**Structural Interpretation**:
- Arginine at position 396 participates in coiled-coil interactions
- Cysteine substitution disrupts ionic interactions
- Adjacent residue 398 has pathogenic variants
- **Strong structural support for pathogenicity**

*Source: NVIDIA NIM via `NvidiaNIM_alphafold2`, InterPro*

---

## 6. Clinical Recommendations

### Immediate Actions
1. **Clinical genetics consultation** - Discuss VUS implications
2. **Parental testing** - De novo status would upgrade variant (PS2)
3. **Neurology follow-up** - Seizure management, prognosis discussion

### Supporting Studies
- Obtain parental samples for GFAP c.1186C>T
- If not in parents → add PS2 (strong evidence) → Likely Pathogenic

---

Example 3: Limited Data Scenario

User Query

"6-month-old with severe hypotonia and feeding difficulties. No genetic testing done yet. Where do we start?"

Expected Output (Key Sections)

## Executive Summary

This infant presents with a non-specific phenotype (hypotonia + feeding difficulties) that could represent numerous conditions. Given the limited phenotypic information, **a broad approach is recommended**: either chromosomal microarray + trio WES, or a comprehensive neuromuscular panel. Additional clinical information (neuroimaging, EMG, metabolic workup) would help narrow the differential.

---

## 2. Differential Diagnosis

**Note**: With only 2 phenotypic features, differential diagnosis is broad.

### Top Categories to Consider

| Category | Examples | Key Tests |
|----------|----------|-----------|
| **SMA/Neuromuscular** | SMA type 1, CMD | SMN1 del/dup, CK |
| **Congenital myopathy** | RYR1, MTM1 | Muscle biopsy, EMG |
| **Chromosomal** | Prader-Willi, 1p36 del | CMA |
| **Metabolic** | Pompe, mitochondrial | GAA enzyme, lactate |
| **Syndromic** | Various | Dysmorphology exam |

### Priority Testing

| Test | Yield | Rationale |
|------|-------|-----------|
| Chromosomal microarray | 15-20% | Screen for CNVs |
| SMN1 deletion | 8-10% if SMA | Treatable if positive |
| Trio WES | 25-40% | Broad diagnostic screen |

---

## 3. Recommended Additional Workup

Before genetic testing, consider:

| Test | Purpose | Urgency |
|------|---------|---------|
| CK level | Myopathy vs neuropathy | High |
| Lactate | Metabolic disease | Medium |
| Brain MRI | Structural vs metabolic | Medium |
| EMG/NCS | Localize lesion | Medium |
| Dysmorphology exam | Syndromic features | High |

---

## 6. Recommendations

### Immediate
1. **Genetics referral** for comprehensive evaluation
2. **CK and metabolic labs** as first-line screening
3. **SMN1 testing** - treatable condition, high impact

### Diagnostic Strategy Options

**Option A**: Targeted approach
- SMN1 → CMA → Neuromuscular panel → WES

**Option B**: Broad approach (recommended if resources allow)
- Trio WES + CMA concurrently

---

## 7. Data Gaps

| Gap | Impact | Action Needed |
|-----|--------|---------------|
| Limited phenotype | Broad differential | Detailed clinical exam |
| No neuroimaging | Cannot assess CNS | Order brain MRI |
| No metabolic studies | May miss treatable | Order basic metabolic |
| No family history | Cannot assess inheritance | Take detailed pedigree |

*Note: This case has significant diagnostic uncertainty due to limited phenotypic information.*

Report Template & Output Examples

Templates and example outputs for each phase of the rare disease diagnosis workflow.

---

Report File Template

File: [PATIENT_ID]_rare_disease_report.md

# Rare Disease Diagnostic Report

**Patient ID**: [ID] | **Date**: [Date] | **Status**: In Progress

---

## Executive Summary
[Researching...]

---

## 1. Phenotype Analysis
### 1.1 Standardized HPO Terms
[Researching...]
### 1.2 Key Clinical Features
[Researching...]

---

## 2. Differential Diagnosis
### 2.1 Ranked Candidate Diseases
[Researching...]
### 2.2 Disease Details
[Researching...]

---

## 3. Recommended Gene Panel
### 3.1 Prioritized Genes
[Researching...]
### 3.2 Testing Strategy
[Researching...]

---

## 4. Variant Interpretation (if applicable)
### 4.1 Variant Details
[Researching...]
### 4.2 ACMG Classification
[Researching...]

---

## 5. Structural Analysis (if applicable)
### 5.1 Structure Prediction
[Researching...]
### 5.2 Variant Impact
[Researching...]

---

## 6. Clinical Recommendations
### 6.1 Diagnostic Next Steps
[Researching...]
### 6.2 Specialist Referrals
[Researching...]
### 6.3 Family Screening
[Researching...]

---

## 7. Data Gaps & Limitations
[Researching...]

---

## 8. Data Sources
[Will be populated as research progresses...]

---

Phase Output Examples

Phase 1: Phenotype Analysis Output

## 1. Phenotype Analysis

### 1.1 Standardized HPO Terms

| Clinical Feature | HPO Term | HPO ID | Category |
|------------------|----------|--------|----------|
| Tall stature | Tall stature | HP:0000098 | Core |
| Long fingers | Arachnodactyly | HP:0001166 | Core |
| Heart murmur | Cardiac murmur | HP:0030148 | Variable |
| Joint hypermobility | Joint hypermobility | HP:0001382 | Core |

**Total HPO Terms**: 8
**Onset**: Childhood
**Family History**: Father with similar features (AD suspected)

*Source: HPO via `HPO_search_terms`*

Phase 2: Differential Diagnosis Output

## 2. Differential Diagnosis

### Top Candidate Diseases (Ranked by Phenotype Match)

| Rank | Disease | ORPHA | OMIM | Match | Inheritance | Key Gene(s) |
|------|---------|-------|------|-------|-------------|-------------|
| 1 | Marfan syndrome | 558 | 154700 | 85% | AD | FBN1 |
| 2 | Loeys-Dietz syndrome | 60030 | 609192 | 72% | AD | TGFBR1, TGFBR2 |
| 3 | Ehlers-Danlos, vascular | 286 | 130050 | 65% | AD | COL3A1 |
| 4 | Homocystinuria | 394 | 236200 | 58% | AR | CBS |

### DisGeNET Gene-Disease Evidence

| Gene | Associated Diseases | GDA Score | Evidence |
|------|---------------------|-----------|----------|
| FBN1 | Marfan syndrome, MASS phenotype | 0.95 | Curated |
| TGFBR1 | Loeys-Dietz syndrome | 0.89 | Curated |
| COL3A1 | vascular EDS | 0.91 | Curated |

*Source: DisGeNET via `DisGeNET_search_gene`*

### Disease Details

#### 1. Marfan Syndrome

**ORPHA**: 558 | **OMIM**: 154700 | **Prevalence**: 1-5/10,000

**Phenotype Match Analysis**:
| Patient Feature | Disease Feature | Match |
|-----------------|-----------------|-------|
| Tall stature | Present in 95% | Yes |
| Arachnodactyly | Present in 90% | Yes |
| Joint hypermobility | Present in 85% | Yes |
| Cardiac murmur | Aortic root dilation (70%) | Partial |

**OMIM Clinical Synopsis** (via `OMIM_get_clinical_synopsis`):
- **Cardiovascular**: Aortic root dilation, mitral valve prolapse
- **Skeletal**: Scoliosis, pectus excavatum, tall stature
- **Ocular**: Ectopia lentis, myopia

**Diagnostic Criteria**: Ghent nosology (2010)
- Aortic root dilation/dissection + FBN1 mutation = Diagnosis
- Without genetic testing: systemic score >=7 + ectopia lentis

**Inheritance**: Autosomal dominant (25% de novo)

*Source: Orphanet via `Orphanet_get_disease`, OMIM via `OMIM_get_entry`, DisGeNET*

Phase 3: Gene Panel Output

## 3. Recommended Gene Panel

### 3.1 Prioritized Genes for Testing

| Priority | Gene | Diseases | Evidence | Constraint (pLI) | Expression |
|----------|------|----------|----------|------------------|------------|
| High | FBN1 | Marfan syndrome | Definitive | 1.00 | Heart, aorta |
| High | TGFBR1 | Loeys-Dietz 1 | Definitive | 0.98 | Ubiquitous |
| High | TGFBR2 | Loeys-Dietz 2 | Definitive | 0.99 | Ubiquitous |
| Medium | COL3A1 | EDS vascular | Definitive | 1.00 | Connective tissue |
| Low | CBS | Homocystinuria | Definitive | 0.00 | Liver |

### 3.2 Panel Design Recommendation

**Minimum Panel** (high yield): FBN1, TGFBR1, TGFBR2, COL3A1
**Extended Panel** (+differential): Add CBS, SMAD3, ACTA2

**Testing Strategy**:
1. Start with FBN1 sequencing (highest pre-test probability)
2. If negative, proceed to full connective tissue panel
3. Consider WES if panel negative

*Source: ClinGen via gene-disease validity, GTEx expression*

Phase 3.5: Expression & Regulatory Context Output

## 3.5 Expression & Regulatory Context

### Cell-Type Specific Expression (CELLxGENE)

| Gene | Top Expressing Cell Types | Expression Level | Tissue Relevance |
|------|---------------------------|------------------|------------------|
| FBN1 | Fibroblasts, Smooth muscle | High (TPM=45) | Connective tissue |
| TGFBR1 | Endothelial, Fibroblasts | Medium (TPM=12) | Vascular |
| COL3A1 | Fibroblasts, Myofibroblasts | Very High (TPM=120) | Connective tissue |

**Interpretation**: All top candidate genes show high expression in disease-relevant cell types.

### Regulatory Context (ChIPAtlas)

| Gene | Key TF Regulators | Regulatory Significance |
|------|-------------------|------------------------|
| FBN1 | TGFb pathway (SMAD2/3), AP-1 | TGFb-responsive |
| TGFBR1 | STAT3, NF-kB | Inflammation-responsive |

*Source: CELLxGENE Census, ChIPAtlas*

Phase 3.6: Pathway & Network Context Output

## 3.6 Pathway & Network Context

### KEGG Pathways

| Gene | Key Pathways | Biological Process |
|------|--------------|-------------------|
| FBN1 | ECM-receptor interaction (hsa04512) | Extracellular matrix |
| TGFBR1/2 | TGF-beta signaling (hsa04350) | Cell signaling |
| COL3A1 | Focal adhesion (hsa04510) | Cell-matrix adhesion |

### Shared Pathway Analysis

**Convergent pathways** (>=2 candidate genes):
- TGF-beta signaling pathway: FBN1, TGFBR1, TGFBR2, SMAD3
- ECM organization: FBN1, COL3A1

**Interpretation**: Candidate genes converge on TGF-beta signaling and extracellular matrix pathways, consistent with connective tissue disorder etiology.

### Protein-Protein Interactions (IntAct)

| Gene | Direct Interactors | Notable Partners |
|------|-------------------|------------------|
| FBN1 | 42 | LTBP1, TGFB1, ADAMTS10 |
| TGFBR1 | 68 | TGFBR2, SMAD2, SMAD3 |

*Source: KEGG, IntAct, Reactome*

Phase 4: Variant Interpretation Output

## 4. Variant Interpretation

### 4.1 Variant: FBN1 c.4621G>A (p.Glu1541Lys)

| Property | Value | Interpretation |
|----------|-------|----------------|
| Gene | FBN1 | Marfan syndrome gene |
| Consequence | Missense | Amino acid change |
| ClinVar | VUS | Uncertain significance |
| gnomAD AF | 0.000004 | Ultra-rare (PM2) |

### 4.2 Computational Predictions

| Predictor | Score | Classification | ACMG Support |
|-----------|-------|----------------|--------------|
| **AlphaMissense** | 0.78 | Pathogenic | PP3 (strong) |
| **CADD PHRED** | 28.5 | Top 0.1% deleterious | PP3 |
| **EVE** | 0.72 | Likely pathogenic | PP3 |

**Consensus**: 3/3 predictors concordant damaging -> **Strong PP3 support**

*Source: AlphaMissense, CADD API, EVE via Ensembl VEP*

### 4.3 ACMG Evidence Summary

| Criterion | Evidence | Strength |
|-----------|----------|----------|
| PM2 | Absent from gnomAD (AF < 0.00001) | Moderate |
| PP3 | AlphaMissense + CADD + EVE concordant | Supporting (strong) |
| PP4 | Phenotype highly specific for Marfan | Supporting |
| PS4 | Multiple affected family members | Strong |

**Preliminary Classification**: Likely Pathogenic (1 Strong + 1 Moderate + 2 Supporting)

*Source: ClinVar, gnomAD, AlphaMissense, CADD, EVE*

Phase 5: Structure Analysis Output

## 5. Structural Analysis

### 5.1 Structure Prediction

**Method**: AlphaFold2 via NVIDIA NIM
**Protein**: Fibrillin-1 (FBN1)
**Sequence Length**: 2,871 amino acids

| Metric | Value | Interpretation |
|--------|-------|----------------|
| Mean pLDDT | 85.3 | High confidence overall |
| Variant position pLDDT | 92.1 | Very high confidence |
| Nearby domain | cbEGF-like domain 23 | Calcium-binding |

### 5.2 Variant Location Analysis

**Variant**: p.Glu1541Lys

| Feature | Finding | Impact |
|---------|---------|--------|
| Domain | cbEGF-like domain 23 | Critical for calcium binding |
| Conservation | 100% conserved across vertebrates | High constraint |
| Structural role | Calcium coordination residue | Likely destabilizing |
| Nearby pathogenic | p.Glu1540Lys (Pathogenic) | Adjacent residue |

### 5.3 Structural Interpretation

The variant p.Glu1541Lys:
1. **Located in cbEGF domain** - Critical for fibrillin-1 function
2. **Glutamate to Lysine** - Charge reversal (negative to positive)
3. **Calcium binding** - Glutamate at this position coordinates Ca2+
4. **Adjacent pathogenic variant** - p.Glu1540Lys is classified Pathogenic

**Structural Evidence**: Strong support for pathogenicity (PM1 - critical domain)

*Source: NVIDIA NIM via `NvidiaNIM_alphafold2`, InterPro*

Phase 6: Literature Evidence Output

## 6. Literature Evidence

### 6.1 Key Published Studies

| PMID | Title | Year | Citations | Relevance |
|------|-------|------|-----------|-----------|
| 32123456 | FBN1 variants in Marfan syndrome... | 2023 | 45 | Direct |
| 31987654 | TGF-beta signaling in connective... | 2022 | 89 | Pathway |
| 30876543 | Novel diagnostic criteria for... | 2021 | 156 | Diagnostic |

### 6.2 Recent Preprints (Not Yet Peer-Reviewed)

| Source | Title | Posted | Relevance |
|--------|-------|--------|-----------|
| BioRxiv | Novel FBN1 splice variant causes... | 2024-01 | Case report |
| MedRxiv | Machine learning for Marfan... | 2024-02 | Diagnostic |

**Note**: Preprints have not undergone peer review. Use with caution.

### 6.3 Evidence Summary

| Evidence Type | Count | Strength |
|---------------|-------|----------|
| Case reports | 12 | Supporting |
| Functional studies | 5 | Strong |
| Clinical trials | 2 | Strong |
| Reviews | 8 | Context |

*Source: PubMed, BioRxiv, OpenAlex*

---

Additional Output Files

Gene Panel CSV

File: [PATIENT_ID]_gene_panel.csv

priority,gene,diseases,evidence_level,pLI,expression,clingen_classification,actionable
1,FBN1,Marfan syndrome,Definitive,1.00,"Heart, aorta",Definitive,Yes
2,TGFBR1,Loeys-Dietz 1,Definitive,0.98,Ubiquitous,Definitive,Yes
3,TGFBR2,Loeys-Dietz 2,Definitive,0.99,Ubiquitous,Definitive,Yes
4,COL3A1,EDS vascular,Definitive,1.00,Connective tissue,Definitive,Yes
5,CBS,Homocystinuria,Definitive,0.00,Liver,Definitive,No

Variant Interpretation CSV

File: [PATIENT_ID]_variant_interpretation.csv

gene,variant,consequence,clinvar,gnomad_af,cadd,alphamissense,eve,acmg_class
FBN1,c.4621G>A,Missense,VUS,0.000004,28.5,0.78,0.72,Likely Pathogenic

Rare Disease Diagnosis - Tool Reference

Phase 1: Phenotype Standardization

HPO Tools

Example - Convert symptom to HPO:

# Search for HPO term
results = tu.tools.HPO_search_terms(query="tall stature")
# Returns: [{"id": "HP:0000098", "name": "Tall stature", ...}]

---

Phase 2: Disease Matching

Orphanet Tools (UPDATED)

Example - Search Orphanet (NEW):

# Search for rare diseases
results = tu.tools.Orphanet_search_diseases(
    operation="search_diseases",
    query="Marfan"
)
# Returns: List of matching rare diseases with ORPHA codes

# Get genes for a disease
genes = tu.tools.Orphanet_get_genes(
    operation="get_genes",
    orpha_code="558"
)
# Returns: FBN1 (causative), associated genes

Common Orphanet Disease Codes:

OMIM Tools (UPDATED)

⚠️ Requires: OMIM_API_KEY environment variable (register at omim.org/api)

Example - Get OMIM details (NEW):

# Search OMIM
search = tu.tools.OMIM_search(
    operation="search",
    query="BRCA1",
    limit=5
)
# Returns: List of MIM numbers

# Get detailed entry
entry = tu.tools.OMIM_get_entry(
    operation="get_entry",
    mim_number="154700"  # Marfan syndrome
)
# Returns: Full text, inheritance, molecular genetics

# Get clinical synopsis (structured phenotype)
synopsis = tu.tools.OMIM_get_clinical_synopsis(
    operation="get_clinical_synopsis",
    mim_number="154700"
)
# Returns: Features by organ system (neurologicCentralNervousSystem, cardiovascular, etc.)

DisGeNET Tools (NEW)

⚠️ Requires: DISGENET_API_KEY environment variable (register free at disgenet.org)

Example - DisGeNET gene-disease associations:

# Get diseases associated with gene
result = tu.tools.DisGeNET_search_gene(
    operation="search_gene",
    gene="FBN1",
    limit=20
)
# Returns: Marfan syndrome (score: 0.95), MASS phenotype, etc.

# Get high-confidence curated associations
gda = tu.tools.DisGeNET_get_gda(
    operation="get_gda",
    gene="FBN1",
    source="CURATED",
    min_score=0.3,
    limit=20
)
# Returns: Gene-disease associations with evidence scores

# Get variant-disease associations for diagnosis
vda = tu.tools.DisGeNET_get_vda(
    operation="get_vda",
    gene="FBN1",
    limit=30
)
# Returns: Variants with disease associations

DisGeNET Score Interpretation:

ClinGen - Gene-Disease Validity (NEW)

Authoritative curation of gene-disease relationships.

# Check gene-disease validity classification
validity = tu.tools.ClinGen_search_gene_validity(gene="FBN1")
# Returns: Definitive for Marfan syndrome, Strong for MASS phenotype

# Check dosage sensitivity (for CNV interpretation)
dosage = tu.tools.ClinGen_search_dosage_sensitivity(gene="MECP2")
# Returns: HI Score 3 (haploinsufficient), TS Score 0

# Check clinical actionability
actionability = tu.tools.ClinGen_search_actionability(gene="BRCA1")
# Returns: Adult and pediatric actionability data

ClinGen Validity Classification (for gene panel prioritization):

Dosage Sensitivity Scores (for CNV interpretation):

OpenTargets Disease Tools

---

Phase 3: Gene Panel

Gene Information

Parameter Note: Use q not gene for MyGene_query_genes.

Expression Validation

Note: GTEx requires versioned Ensembl ID (e.g., ENSG00000166147.15)

Constraint Scores

---

Phase 4: Variant Interpretation

ClinVar Tools

Parameter Note: Use id not variant_id for ClinVar lookups.

Population Frequency

Variant ID Format: 1-55505647-G-A (chrom-pos-ref-alt)

Pathogenicity Prediction (ENHANCED)

CADD API (NEW)

Direct access to CADD deleteriousness scores:

# Get CADD score for variant
result = tu.tools.CADD_get_variant_score(
    chrom="15",
    pos=48942946,
    ref="G",
    alt="A",
    version="GRCh38-v1.7"
)
# Returns: phred_score, raw_score, interpretation
# PHRED ≥20 = top 1% deleterious (PP3 support)

AlphaMissense (NEW)

DeepMind's state-of-the-art missense pathogenicity prediction (~90% accuracy):

# Get pathogenicity score for missense variant
result = tu.tools.AlphaMissense_get_variant_score(
    uniprot_id="P35555",  # FBN1
    variant="E1541K"  # or "p.E1541K"
)
# Returns: pathogenicity_score, classification (pathogenic/ambiguous/benign)
# Thresholds: >0.564 pathogenic, <0.34 benign

ESMC-6B SAE — Mechanism of Effect (NEW)

AlphaMissense gives a pathogenicity score but no mechanism. ESMC-6B Sparse Autoencoder features identify which interpretable protein-language-model features the mutation disrupts (catalytic, ligand-binding, PTM, domain, transmembrane, etc.). Use as a mechanism complement when the report needs to explain how a variant is pathogenic, not just whether.

# One-call mechanism for a VUS (requires WT protein sequence)
result = tu.tools.ESM_explain_variant_mechanism(
    sequence=wt_protein_sequence,
    position=1541, ref_aa="E", alt_aa="K",
    top_k_features=5,
)
# result["data"]["mechanism_summary"] e.g.:
#   "Disrupted feature categories (lost): ligand-binding=2, domain=1"

Other SAE tools (advanced):

• ESM_score_variant_sae_disruption — single variant, raw feature deltas, no labels (faster, no describe-feature calls)
• ESM_score_variant_sae_batch — many variants at once (N+1 Forge calls instead of 2N); use for saturation mutagenesis
• ESM_get_region_sae_features — aggregate features over a residue range (e.g. characterize a domain or motif)
• ESM_describe_sae_feature — biological category label for a feature_id (cached per id)

Mapping SAE categories → ACMG support:

Requires: ESM_API_KEY env var (free non-commercial token at https://forge.evolutionaryscale.ai) and pip install 'esm @ git+https://github.com/evolutionaryscale/esm@ee891c52' (SAE support on unmerged feature branch; PyPI esm 3.2.x lacks SAEConfig). Outputs governed by EvolutionaryScale Cambrian Inference License — non-commercial use only.

EVE (NEW)

Evolutionary variant effect prediction (Harvard/Oxford):

# Get EVE score
result = tu.tools.EVE_get_variant_score(
    chrom="15",
    pos=48942946,
    ref="G",
    alt="A"
)
# Returns: eve_score, classification (likely_pathogenic/likely_benign)
# Threshold: >0.5 likely pathogenic

SpliceAI - Splice Variant Prediction (NEW)

Deep learning model for predicting splice-altering effects. ~15% of pathogenic variants affect splicing.

# Full splice prediction
result = tu.tools.SpliceAI_predict_splice(
    variant="chr15-48942946-G-A",
    genome="38"  # or "37"
)
# Returns: DS_AG, DS_AL, DS_DG, DS_DL scores + max_delta_score + interpretation

# Quick triage (max score only)
quick = tu.tools.SpliceAI_get_max_delta(
    variant="chr15-48942946-G-A",
    genome="38"
)
# Returns: max_delta_score, interpretation, pathogenicity_threshold

Variant Format: chr{chrom}-{pos}-{ref}-{alt}

SpliceAI Delta Score Interpretation:

Max Score Thresholds for ACMG:

When to Use SpliceAI:

• Intronic variants within ±50bp of splice sites
• Synonymous variants (may still affect splicing)
• Exonic variants near splice junctions
• Variants creating cryptic splice sites

---

Prediction Tool Thresholds for PP3:

Recommended Strategy for VUS: 1. Run all predictors (AlphaMissense, CADD, EVE for missense; SpliceAI for splice) 2. If ≥2 concordant damaging → Strong PP3 support 3. If ≥2 concordant benign → BP4 support 4. If discordant → Weight AlphaMissense highest for missense, SpliceAI for splice

---

Phase 3.5: Expression & Regulatory Context (NEW)

CELLxGENE - Single-Cell Expression

Example - Get cell-type expression:

# Get expression across cell types
expression = tu.tools.CELLxGENE_get_expression_data(
    gene="FBN1",
    tissue="heart"
)
# Returns: Expression values per cell type

Why use it: Validates that candidate genes are expressed in disease-relevant cell types (e.g., fibroblasts for connective tissue disorders).

ChIPAtlas - Transcription Factor Binding

Example - Get regulatory context:

# Find TFs that regulate gene
tf_binding = tu.tools.ChIPAtlas_enrichment_analysis(
    gene="FBN1",
    cell_type="Fibroblast"
)
# Returns: TFs with significant binding near gene

Why use it: Identifies regulatory mechanisms that may be disrupted; helps interpret regulatory variants.

ENCODE - Regulatory Elements

Example - Get regulatory data:

# Search for regulatory data
experiments = tu.tools.ENCODE_search_experiments(
    assay_title="ATAC-seq",
    biosample="heart"
)

---

Phase 3.6: Pathway Analysis (NEW)

KEGG - Metabolic & Signaling Pathways

Example - Get pathway context:

# Find gene in KEGG
kegg_gene = tu.tools.kegg_find_genes(query="hsa:FBN1")
# Get pathway membership
gene_info = tu.tools.kegg_get_gene_info(gene_id="hsa:2200")
# Returns: Pathways containing FBN1

Reactome - Biological Processes

Example - Get Reactome pathways:

# Search for pathways
pathways = tu.tools.ReactomeContent_search(query="TGF-beta signaling")

IntAct - Protein-Protein Interactions

Example - Get protein interactions:

# Get interaction partners
interactions = tu.tools.intact_search_interactions(
    query="FBN1",
    species="human"
)
# Returns: Direct interaction partners with confidence scores

Why use it: Identifies protein complexes and pathways; variants may disrupt protein-protein interactions.

---

Phase 5: Structure Analysis (NVIDIA NIM)

Structure Prediction

Example - AlphaFold2 prediction:

structure = tu.tools.NvidiaNIM_alphafold2(
    sequence=protein_sequence,
    algorithm="mmseqs2",
    relax_prediction=False
)
# Returns: PDB structure with pLDDT scores

Domain Annotation

---

Phase 6: Literature Evidence (NEW)

PubMed - Published Literature

Example - Search disease literature:

# Disease-specific search
papers = tu.tools.PubMed_search_articles(
    query='"Marfan syndrome" AND (FBN1 OR genetics)',
    limit=20
)

BioRxiv/MedRxiv - Preprints

Example - Search preprints (bioRxiv/medRxiv don't have search APIs, use EuropePMC):

# Search for recent preprints
preprints = tu.tools.EuropePMC_search_articles(
    query="Marfan syndrome genetics",
    source="PPR",  # PPR = Preprints only
    pageSize=10
)

# Get full metadata if you have a DOI
if doi_from_results.startswith('10.1101/'):
    full = tu.tools.BioRxiv_get_preprint(doi=doi_from_results)
# Returns: Recent preprints (not peer-reviewed)

⚠️ Important: Preprints are NOT peer-reviewed. Flag this in reports.

OpenAlex - Citation Analysis

Example - Citation analysis:

# Get citation data for paper
work = tu.tools.openalex_search_works(
    query="FBN1 Marfan pathogenic",
    limit=10
)
# Returns: Papers with citation counts, open access status

Semantic Scholar - AI-Enhanced Search

Example:

# AI-enhanced literature search
papers = tu.tools.SemanticScholar_search_papers(
    query="rare disease diagnosis machine learning",
    limit=15
)

---

Workflow Code Examples

Example 1: Full Phenotype-to-Diagnosis

def diagnose_rare_disease(tu, symptoms, patient_id):
    """Complete rare disease diagnostic workflow."""
    
    # Phase 1: Standardize phenotype
    hpo_terms = []
    for symptom in symptoms:
        results = tu.tools.HPO_search_terms(query=symptom)
        if results:
            hpo_terms.append(results[0])
    
    # Phase 2: Match diseases
    candidate_diseases = []
    for hpo in hpo_terms:
        diseases = tu.tools.HPO_get_diseases_by_phenotype(hp_id=hpo['id'])
        candidate_diseases.extend(diseases)
    
    # Rank by frequency
    disease_counts = Counter(d['orpha_id'] for d in candidate_diseases)
    top_diseases = disease_counts.most_common(10)
    
    # Phase 3: Build gene panel
    genes = set()
    for orpha_id, count in top_diseases:
        disease_genes = tu.tools.Orphanet_get_disease_genes(orpha_code=orpha_id)
        genes.update(disease_genes)
    
    return {
        'hpo_terms': hpo_terms,
        'candidate_diseases': top_diseases,
        'gene_panel': list(genes)
    }

Example 2: Variant Interpretation

def interpret_variant(tu, variant_hgvs, gene_symbol):
    """Interpret a variant using ACMG criteria."""
    
    evidence = {}
    
    # PM2: Population frequency
    freq = tu.tools.gnomad_get_variant(variant_id=variant_hgvs)
    if freq['allele_frequency'] < 0.00001:
        evidence['PM2'] = {'strength': 'Moderate', 'reason': 'Absent from gnomAD'}
    
    # PP3: Computational predictions
    cadd = tu.tools.CADD_get_scores(variant=variant_hgvs)
    if cadd['phred_score'] > 25:
        evidence['PP3'] = {'strength': 'Supporting', 'reason': f'CADD={cadd["phred_score"]}'}
    
    # ClinVar
    clinvar = tu.tools.ClinVar_search_variants(query=variant_hgvs)
    if clinvar:
        evidence['ClinVar'] = clinvar[0]['clinical_significance']
    
    return evidence

Example 3: Structure Analysis for VUS

def analyze_vus_structure(tu, uniprot_id, variant_position):
    """Structural analysis for variant of uncertain significance."""
    
    # Get protein sequence
    protein = tu.tools.UniProt_get_entry_by_accession(accession=uniprot_id)
    sequence = protein['sequence']
    
    # Predict structure
    structure = tu.tools.NvidiaNIM_alphafold2(
        sequence=sequence,
        algorithm="mmseqs2"
    )
    
    # Get domain annotations
    domains = tu.tools.InterPro_get_protein_domains(accession=uniprot_id)
    
    # Check if variant in domain
    variant_domain = None
    for domain in domains:
        if domain['start'] <= variant_position <= domain['end']:
            variant_domain = domain
            break
    
    return {
        'structure': structure,
        'plddt_at_position': get_plddt(structure, variant_position),
        'domain': variant_domain
    }

---

Fallback Chains

Disease Matching

Expression & Regulatory

Pathway Analysis

Variant Annotation

Pathogenicity Prediction (ENHANCED)

Structure Prediction

Literature

---

Common Parameter Mistakes

---

NVIDIA NIM Requirements

API Key: NVIDIA_API_KEY environment variable required

Check availability:

import os
nvidia_available = bool(os.environ.get("NVIDIA_API_KEY"))

Rate limits: 40 RPM (1.5 second minimum between calls)

Async operations: AlphaFold2 may return 202, requiring polling:

# Initial call may return 202
result = tu.tools.NvidiaNIM_alphafold2(sequence=seq)
if result.get('status') == 'pending':
    # Poll for completion (handled internally by tool)
    pass