lamm-mit/structural-variant-analysis

---

name: tooluniverse-structural-variant-analysis description: Comprehensive structural variant (SV) analysis skill for clinical genomics. Classifies SVs (deletions, duplications, inversions, translocations), assesses pathogenicity using ACMG-adapted criteria, evaluates gene disruption and dosage sensitivity, and provides clinical interpretation with evidence grading. Use when analyzing CNVs, large deletions/duplications, chromosomal rearrangements, or any structural variants requiring clinical interpretation.

Structural Variant Analysis Workflow

Systematic analysis of structural variants (deletions, duplications, inversions, translocations, complex rearrangements) for clinical genomics interpretation using ACMG-adapted criteria.

KEY PRINCIPLES:

1. Report-first approach - Create SV_analysis_report.md FIRST, then populate progressively
2. ACMG-style classification - Pathogenic/Likely Pathogenic/VUS/Likely Benign/Benign with explicit evidence
3. Evidence grading - Grade all findings by confidence level (★★★/★★☆/★☆☆)
4. Dosage sensitivity critical - Gene dosage effects drive SV pathogenicity
5. Breakpoint precision matters - Exact gene disruption vs dosage-only effects
6. Population context essential - gnomAD SVs for frequency assessment
7. English-first queries - Always use English terms in tool calls (gene names, disease names), even if the user writes in another language. Only try original-language terms as a fallback. Respond in the user's language

---

Problem This Skill Solves

Structural variants (SVs) present unique interpretation challenges:

1. Complex molecular consequences - SVs can cause gene dosage changes, gene disruption, gene fusions, position effects
2. Size matters - Pathogenicity depends on size, gene content, and breakpoint precision
3. Limited databases - Fewer curated SVs in ClinVar compared to SNVs
4. Dosage sensitivity - Haploinsufficiency and triplosensitivity are critical but gene-specific
5. Population frequency - Large benign CNVs are common; distinguishing pathogenic from benign is challenging

This skill provides: A systematic workflow integrating SV classification, gene content analysis, dosage sensitivity assessment, population frequencies, and ACMG-adapted criteria into clinically actionable interpretations.

---

Triggers

Use this skill when users:

• Ask about structural variant interpretation
• Have CNV data from array or sequencing
• Ask "is this deletion/duplication pathogenic?"
• Need ACMG classification for SVs
• Want to assess gene dosage effects
• Ask about chromosomal rearrangements
• Have large-scale genomic alterations requiring interpretation

---

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│              STRUCTURAL VARIANT INTERPRETATION                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Phase 1: SV IDENTITY & CLASSIFICATION                          │
│  ├── Normalize SV coordinates (hg19/hg38)                       │
│  ├── Determine SV type (DEL/DUP/INV/TRA/CPX)                   │
│  ├── Calculate SV size                                          │
│  └── Assess breakpoint precision                                │
│                                                                  │
│  Phase 2: GENE CONTENT ANALYSIS                                  │
│  ├── Identify genes fully contained in SV                       │
│  ├── Identify genes with breakpoints (disrupted)                │
│  ├── Annotate gene function and disease associations            │
│  ├── Identify regulatory elements affected                      │
│  └── Assess gene orientation (for inversions/translocations)    │
│                                                                  │
│  Phase 3: DOSAGE SENSITIVITY ASSESSMENT                          │
│  ├── ClinGen dosage sensitivity scores                          │
│  │   └─ Haploinsufficiency / Triplosensitivity ratings          │
│  ├── DECIPHER haploinsufficiency predictions                    │
│  ├── pLI scores (gnomAD) for loss-of-function intolerance       │
│  ├── OMIM gene-disease associations (dominant/recessive)        │
│  └── Known dosage-sensitive genes from literature               │
│                                                                  │
│  Phase 4: POPULATION FREQUENCY CONTEXT                           │
│  ├── gnomAD SV database (overlapping SVs)                       │
│  ├── DGV (Database of Genomic Variants)                         │
│  ├── ClinVar (known pathogenic/benign SVs)                      │
│  └── Calculate reciprocal overlap with population SVs           │
│                                                                  │
│  Phase 5: PATHOGENICITY SCORING                                  │
│  ├── Pathogenicity score (0-10 scale)                           │
│  │   ├─ Gene content weight (40%)                               │
│  │   ├─ Dosage sensitivity weight (30%)                         │
│  │   ├─ Population frequency weight (20%)                       │
│  │   └─ Inheritance/phenotype match weight (10%)                │
│  ├── Apply ACMG SV criteria                                     │
│  └── Generate classification recommendation                      │
│                                                                  │
│  Phase 6: LITERATURE & CLINICAL EVIDENCE                         │
│  ├── PubMed: Similar SVs, gene disruption studies               │
│  ├── DECIPHER: Developmental disorder cases                     │
│  ├── Clinical case reports                                      │
│  └── Functional evidence for gene dosage effects                │
│                                                                  │
│  Phase 7: ACMG-ADAPTED CLASSIFICATION                            │
│  ├── Apply SV-specific evidence codes                           │
│  ├── Calculate final classification                             │
│  ├── Identify limiting factors                                  │
│  └── Generate clinical recommendations                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Phase Details

Phase 1: SV Identity & Classification

Goal: Standardize SV notation and classify type

SV Types: | Type | Abbreviation | Description | Molecular Effect | |------|--------------|-------------|------------------| | Deletion | DEL | Loss of genomic segment | Haploinsufficiency, gene disruption | | Duplication | DUP | Gain of genomic segment | Triplosensitivity, gene dosage imbalance | | Inversion | INV | Segment flipped in orientation | Gene disruption at breakpoints, position effects | | Translocation | TRA | Segment moved to different chromosome | Gene fusions, disruption, position effects | | Complex | CPX | Multiple rearrangement types | Variable effects |

Key Information to Capture:

• Chromosome(s) involved
• Coordinates (start, end) in hg19/hg38
• SV size (bp or Mb)
• SV type (DEL/DUP/INV/TRA/CPX)
• Breakpoint precision (±50bp, ±1kb, etc.)
• Inheritance pattern (de novo, inherited, unknown)

Example:

SV: arr[GRCh38] 17q21.31(44039927-44352659)x1
- Type: Deletion (heterozygous)
- Size: 313 kb
- Genes: MAPT, KANSL1 (fully contained)
- Breakpoints: Well-defined (array resolution ±5kb)

---

Phase 2: Gene Content Analysis

Goal: Comprehensive annotation of genes affected by SV

Tools: | Tool | Purpose | Key Data | |------|---------|----------| | Ensembl_lookup_gene | Gene structure, coordinates | Gene boundaries, exons, transcripts | | NCBI_gene_search | Gene information | Official symbol, aliases, description | | Gene_Ontology_get_term_info | Gene function | Biological process, molecular function | | OMIM_search, OMIM_get_entry | Disease associations | Inheritance, clinical features | | DisGeNET_search_gene | Gene-disease associations | Evidence scores |

Gene Categories:

1. Fully contained genes - Entire gene within SV boundaries

   • Deletion: Complete loss of one copy (haploinsufficiency)
   • Duplication: Extra copy (triplosensitivity)

2. Partially disrupted genes - Breakpoint within gene

   • Likely loss-of-function for affected allele
   • Check if critical domains disrupted

3. Flanking genes - Within 1 Mb of breakpoints

   • May be affected by position effects
   • Regulatory disruption possible

Example Gene Content Analysis:

def analyze_gene_content(tu, chrom, sv_start, sv_end, sv_type):
    """
    Identify and annotate all genes within SV region.
    """
    genes = {
        'fully_contained': [],
        'partially_disrupted': [],
        'flanking': []
    }

    # Use Ensembl to find overlapping genes
    # This is pseudocode - actual implementation depends on available tools

    for gene in genes_in_region:
        gene_start = gene['start']
        gene_end = gene['end']

        # Classify gene relationship to SV
        if gene_start >= sv_start and gene_end <= sv_end:
            # Fully contained
            gene_info = annotate_gene(tu, gene['symbol'])
            genes['fully_contained'].append(gene_info)

        elif (gene_start < sv_start < gene_end) or (gene_start < sv_end < gene_end):
            # Partially disrupted
            gene_info = annotate_gene(tu, gene['symbol'])
            genes['partially_disrupted'].append(gene_info)

        elif abs(gene_start - sv_end) < 1000000 or abs(gene_end - sv_start) < 1000000:
            # Flanking (within 1 Mb)
            gene_info = annotate_gene(tu, gene['symbol'])
            genes['flanking'].append(gene_info)

    return genes

def annotate_gene(tu, gene_symbol):
    """
    Comprehensive gene annotation.
    """
    # OMIM associations
    omim = tu.tools.OMIM_search(
        operation="search",
        query=gene_symbol,
        limit=5
    )

    # DisGeNET associations
    disgenet = tu.tools.DisGeNET_search_gene(
        operation="search_gene",
        gene=gene_symbol,
        limit=10
    )

    # Gene Ontology
    # Note: Need gene ID first
    ncbi = tu.tools.NCBI_gene_search(
        term=gene_symbol,
        organism="human"
    )

    return {
        'symbol': gene_symbol,
        'omim': omim,
        'disgenet': disgenet,
        'ncbi': ncbi
    }

Report Section:

### 2.1 Fully Contained Genes (Complete Dosage Effect)

| Gene | Function | Disease Association | Inheritance | Evidence |
|------|----------|---------------------|-------------|----------|
| **MAPT** | Microtubule-associated protein tau | Frontotemporal dementia (AD) | Autosomal Dominant | ★★★ |
| **KANSL1** | Histone acetyltransferase complex | Koolen-De Vries syndrome (AD) | Autosomal Dominant | ★★★ |

**Interpretation**: Deletion results in haploinsufficiency of two dosage-sensitive genes. KANSL1 haploinsufficiency is the primary cause of pathogenicity.

*Sources: OMIM, DisGeNET, Ensembl*

### 2.2 Partially Disrupted Genes (Breakpoint Within Gene)

| Gene | Breakpoint Location | Effect | Critical Domains Lost |
|------|-------------------|--------|----------------------|
| **NF1** | Intron 28 of 58 | 5' portion deleted | Yes - GTPase-activating domain |

**Interpretation**: Breakpoint disrupts NF1 coding sequence, likely resulting in loss-of-function. NF1 is haploinsufficient (causes neurofibromatosis type 1).

### 2.3 Flanking Genes (Potential Position Effects)

| Gene | Distance from SV | Regulatory Risk | Evidence |
|------|------------------|-----------------|----------|
| **KCNJ2** | 450 kb upstream | Low | ★☆☆ |

**Note**: Position effects are possible but less common. Consider if phenotype unexplained by contained genes.

---

Phase 3: Dosage Sensitivity Assessment

Goal: Determine if affected genes are dosage-sensitive

Tools: | Tool | Purpose | Key Data | |------|---------|----------| | ClinGen_search_dosage_sensitivity | Gold standard curation | HI/TS scores (0-3) | | ClinGen_search_gene_validity | Gene-disease validity | Definitive/Strong/Moderate | | gnomad_search (pLI) | Loss-of-function intolerance | pLI score (0-1) | | DECIPHER_search | Developmental disorders | Patient phenotypes with similar SVs | | OMIM_get_entry | Inheritance pattern | AD/AR indicates dosage sensitivity |

ClinGen Dosage Sensitivity Scores:

| Score | Haploinsufficiency (HI) | Triplosensitivity (TS) | Interpretation | |-------|------------------------|------------------------|----------------| | 3 | Sufficient evidence | Sufficient evidence | Gene IS dosage-sensitive | | 2 | Emerging evidence | Emerging evidence | Likely dosage-sensitive | | 1 | Little evidence | Little evidence | Insufficient evidence | | 0 | No evidence | No evidence | No established dosage sensitivity |

pLI Score Interpretation (gnomAD): | pLI Range | Interpretation | LoF Intolerance | |-----------|----------------|-----------------| | ≥0.9 | Extremely intolerant | High - likely haploinsufficient | | 0.5-0.9 | Moderately intolerant | Moderate | | <0.5 | Tolerant | Low - likely NOT haploinsufficient |

Implementation:

def assess_dosage_sensitivity(tu, gene_list):
    """
    Assess dosage sensitivity for all genes in SV.
    Returns dosage scores and interpretation.
    """
    dosage_data = []

    for gene_symbol in gene_list:
        # 1. ClinGen dosage sensitivity (gold standard)
        clingen = tu.tools.ClinGen_search_dosage_sensitivity(
            gene=gene_symbol
        )

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

        # 2. ClinGen gene validity (supports dosage sensitivity)
        validity = tu.tools.ClinGen_search_gene_validity(
            gene=gene_symbol
        )

        validity_level = None
        if validity.get('data'):
            for entry in validity['data']:
                validity_level = entry.get('Classification')
                break

        # 3. pLI score from gnomAD (if available via gene search)
        # Note: May need to use myvariant or other tools
        # pli_score = get_pli_score(tu, gene_symbol)

        # 4. OMIM inheritance pattern
        omim = tu.tools.OMIM_search(
            operation="search",
            query=gene_symbol,
            limit=3
        )

        inheritance_pattern = None
        if omim.get('data', {}).get('entries'):
            for entry in omim['data']['entries']:
                mim = entry.get('mimNumber')
                details = tu.tools.OMIM_get_entry(
                    operation="get_entry",
                    mim_number=str(mim)
                )
                # Extract inheritance from details
                # inheritance_pattern = parse_inheritance(details)

        # Integrate evidence
        dosage_assessment = {
            'gene': gene_symbol,
            'hi_score': hi_score,
            'ts_score': ts_score,
            'validity_level': validity_level,
            'inheritance': inheritance_pattern,
            'is_dosage_sensitive': (hi_score == '3' or ts_score == '3'),
            'evidence_grade': calculate_evidence_grade(hi_score, ts_score, validity_level)
        }

        dosage_data.append(dosage_assessment)

    return dosage_data

def calculate_evidence_grade(hi_score, ts_score, validity):
    """
    Calculate evidence grade for dosage sensitivity.
    """
    if (hi_score == '3' or ts_score == '3') and validity == 'Definitive':
        return '★★★'  # High confidence
    elif (hi_score in ['2', '3'] or ts_score in ['2', '3']):
        return '★★☆'  # Moderate confidence
    else:
        return '★☆☆'  # Low confidence

Report Section:

### 3. Dosage Sensitivity Assessment

#### Haploinsufficient Genes (Deletions/Disruptions)

| Gene | ClinGen HI Score | pLI | Validity | Disease | Evidence |
|------|-----------------|-----|----------|---------|----------|
| **KANSL1** | 3 (Sufficient) | 0.99 | Definitive | Koolen-De Vries syndrome | ★★★ |
| **MAPT** | 2 (Emerging) | 0.85 | Strong | FTD (rare) | ★★☆ |

**Interpretation**: KANSL1 has definitive evidence for haploinsufficiency. Deletion of one copy is expected to cause Koolen-De Vries syndrome (intellectual disability, hypotonia, distinctive facial features).

*Sources: ClinGen Dosage Sensitivity Map, gnomAD pLI*

#### Triplosensitive Genes (Duplications)

| Gene | ClinGen TS Score | Disease Mechanism | Evidence |
|------|-----------------|-------------------|----------|
| **MECP2** | 3 (Sufficient) | MECP2 duplication syndrome | ★★★ |
| **PMP22** | 3 (Sufficient) | Charcot-Marie-Tooth 1A | ★★★ |

**Note**: For this deletion, triplosensitivity is not applicable. Listed for reference.

#### Non-Dosage-Sensitive Genes

| Gene | HI Score | TS Score | Interpretation |
|------|----------|----------|----------------|
| **GENE_X** | 0 | 0 | No established dosage sensitivity |
| **GENE_Y** | 1 | 1 | Insufficient evidence |

**Interpretation**: These genes lack evidence for dosage sensitivity. Deletion/duplication less likely to be pathogenic solely due to these genes.

---

Phase 4: Population Frequency Context

Goal: Determine if SV is common in general population (likely benign) or rare (supports pathogenicity)

Tools: | Tool | Purpose | Key Data | |------|---------|----------| | gnomad_search | Population SV frequencies | Overlapping SVs, frequencies | | ClinVar_search_variants | Known pathogenic/benign SVs | Classification, review status | | DECIPHER_search | Patient SVs with phenotypes | Case reports, phenotype similarity |

Frequency Interpretation (adapted from ACMG):

| SV Frequency | ACMG Code | Interpretation | |--------------|-----------|----------------| | ≥1% in gnomAD SVs | BA1 (Stand-alone Benign) | Too common for rare disease | | 0.1-1% | BS1 (Strong Benign) | Likely benign common variant | | <0.01% | PM2 (Supporting Pathogenic) | Rare, supports pathogenicity | | Absent | PM2 (Supporting) | Very rare, supports pathogenicity |

Reciprocal Overlap Calculation:

For proper comparison, calculate reciprocal overlap between query SV and population SV:

Reciprocal Overlap = min(overlap_with_A, overlap_with_B)
where:
  overlap_with_A = (overlap length) / (SV_A length)
  overlap_with_B = (overlap length) / (SV_B length)

Threshold: ≥70% reciprocal overlap = "same" SV

Implementation:

def assess_population_frequency(tu, chrom, sv_start, sv_end, sv_type):
    """
    Check population databases for overlapping SVs.
    """
    # 1. Check ClinVar for known pathogenic/benign SVs
    clinvar = tu.tools.ClinVar_search_variants(
        chromosome=str(chrom),
        start=sv_start,
        stop=sv_end,
        variant_type=sv_type.upper()
    )

    known_svs = []
    if clinvar.get('data'):
        for variant in clinvar['data']:
            classification = variant.get('clinical_significance')
            known_svs.append({
                'database': 'ClinVar',
                'classification': classification,
                'review_status': variant.get('review_status'),
                'coordinates': f"{variant.get('chromosome')}:{variant.get('start')}-{variant.get('stop')}"
            })

    # 2. gnomAD SVs (if available)
    # Note: gnomAD SV database may not have direct API access via ToolUniverse
    # May need to use genomic coordinate search

    # 3. DECIPHER for similar patient cases
    decipher_search = tu.tools.DECIPHER_search(
        query=f"chr{chrom}:{sv_start}-{sv_end}",
        search_type="region"
    )

    patient_cases = []
    if decipher_search.get('data'):
        patient_cases = decipher_search['data']

    return {
        'clinvar_matches': known_svs,
        'decipher_cases': patient_cases,
        'frequency_interpretation': interpret_frequency(known_svs)
    }

def interpret_frequency(known_svs):
    """
    Interpret frequency based on ClinVar matches.
    """
    if any(sv['classification'] == 'Benign' for sv in known_svs):
        return {
            'acmg_code': 'BA1 or BS1',
            'interpretation': 'Likely benign based on ClinVar benign classification',
            'evidence_grade': '★★★'
        }
    elif any(sv['classification'] == 'Pathogenic' for sv in known_svs):
        return {
            'acmg_code': 'PS1',
            'interpretation': 'Pathogenic based on ClinVar pathogenic classification',
            'evidence_grade': '★★★'
        }
    else:
        return {
            'acmg_code': 'PM2',
            'interpretation': 'Rare variant, not found in ClinVar or population databases',
            'evidence_grade': '★★☆'
        }

Report Section:

### 4. Population Frequency Context

#### ClinVar Matches (Overlapping SVs)

| VCV ID | Classification | Size | Overlap | Review Status | Genes |
|--------|----------------|------|---------|---------------|-------|
| VCV000012345 | Pathogenic | 320 kb | 95% reciprocal | ★★★ Reviewed by expert panel | KANSL1, MAPT |

**Match Found**: Query deletion has 95% reciprocal overlap with known pathogenic deletion in ClinVar (VCV000012345). This is the Koolen-De Vries syndrome deletion.

**ACMG Code**: **PS1** (Strong) - Same genomic region as established pathogenic SV

*Source: ClinVar via `ClinVar_search_variants`*

#### gnomAD SV Database

**Search Result**: No overlapping deletions found in gnomAD SV v4.0 (>10,000 genomes)

**Interpretation**: Absence from gnomAD supports rarity and pathogenic potential.

**ACMG Code**: **PM2** (Moderate) - Absent from population databases

*Note: gnomAD SVs queried via browser (no direct API access)*

#### DECIPHER Patient Cases

| Case ID | Phenotype | SV Type | Size | Overlap | Similarity |
|---------|-----------|---------|------|---------|------------|
| 12345 | Intellectual disability, hypotonia | DEL | 315 kb | 98% | High |
| 67890 | Developmental delay, facial dysmorphism | DEL | 305 kb | 92% | High |

**Phenotype Match**: 8/10 DECIPHER patients have intellectual disability and hypotonia, consistent with Koolen-De Vries syndrome.

**ACMG Support**: **PP4** (Supporting) - Patient phenotype consistent with gene's disease association

*Source: DECIPHER via `DECIPHER_search`*

---

Phase 5: Pathogenicity Scoring

Goal: Quantitative pathogenicity assessment (0-10 scale)

Scoring Components:

1. Gene Content (40 points max):

   • 10 points per dosage-sensitive gene (HI/TS score 3)
   • 5 points per likely dosage-sensitive gene (score 2)
   • 2 points per gene with disease association
   • Cap at 40 points

2. Dosage Sensitivity Evidence (30 points max):

   • 30 points: Multiple genes with definitive HI/TS (score 3)
   • 20 points: One gene with definitive HI/TS
   • 10 points: Genes with emerging evidence (score 2)
   • 5 points: Predicted haploinsufficiency (pLI >0.9)

3. Population Frequency (20 points max):

   • 20 points: Absent from gnomAD, DGV
   • 10 points: Rare (<0.01%)
   • 0 points: Common (>0.1%)
   • -20 points: Very common (>1%) - likely benign

4. Clinical Evidence (10 points max):

   • 10 points: Matching ClinVar pathogenic SV
   • 8 points: DECIPHER cases with matching phenotype
   • 5 points: Literature support for gene dosage effects
   • 3 points: Phenotype consistent with genes

Pathogenicity Score Interpretation:

| Score | Classification | Confidence | Interpretation | |-------|----------------|------------|----------------| | 9-10 | Pathogenic | ★★★ | High confidence pathogenic | | 7-8 | Likely Pathogenic | ★★☆ | Strong evidence for pathogenicity | | 4-6 | VUS | ★☆☆ | Uncertain significance | | 2-3 | Likely Benign | ★★☆ | Strong evidence for benign | | 0-1 | Benign | ★★★ | High confidence benign |

Implementation:

def calculate_pathogenicity_score(gene_content, dosage_data, frequency_data, clinical_data):
    """
    Calculate comprehensive pathogenicity score (0-10 scale).
    """
    score = 0
    breakdown = {}

    # 1. Gene content scoring (40 points max)
    gene_score = 0
    for gene in gene_content['fully_contained'] + gene_content['partially_disrupted']:
        dosage_info = next((d for d in dosage_data if d['gene'] == gene['symbol']), None)
        if dosage_info:
            if dosage_info['hi_score'] == '3':
                gene_score += 10
            elif dosage_info['hi_score'] == '2':
                gene_score += 5
            elif gene.get('omim_disease'):
                gene_score += 2

    gene_score = min(gene_score, 40)  # Cap at 40
    breakdown['gene_content'] = gene_score / 40 * 4  # Scale to 0-4

    # 2. Dosage sensitivity scoring (30 points max)
    dosage_score = 0
    definitive_genes = sum(1 for d in dosage_data if d['hi_score'] == '3')

    if definitive_genes >= 2:
        dosage_score = 30
    elif definitive_genes == 1:
        dosage_score = 20
    else:
        emerging_genes = sum(1 for d in dosage_data if d['hi_score'] == '2')
        dosage_score = emerging_genes * 5

    dosage_score = min(dosage_score, 30)
    breakdown['dosage_sensitivity'] = dosage_score / 30 * 3  # Scale to 0-3

    # 3. Population frequency scoring (20 points max)
    freq_score = 0
    if frequency_data.get('frequency') is None:
        freq_score = 20  # Absent
    elif frequency_data['frequency'] < 0.0001:
        freq_score = 10  # Rare
    elif frequency_data['frequency'] < 0.001:
        freq_score = 5  # Uncommon
    elif frequency_data['frequency'] > 0.01:
        freq_score = -20  # Common - likely benign

    breakdown['population_frequency'] = freq_score / 20 * 2  # Scale to -2 to 2

    # 4. Clinical evidence scoring (10 points max)
    clinical_score = 0
    if clinical_data.get('clinvar_pathogenic'):
        clinical_score = 10
    elif clinical_data.get('decipher_matching_phenotype'):
        clinical_score = 8
    elif clinical_data.get('literature_support'):
        clinical_score = 5

    clinical_score = min(clinical_score, 10)
    breakdown['clinical_evidence'] = clinical_score / 10 * 1  # Scale to 0-1

    # Total score (0-10 scale)
    total_score = breakdown['gene_content'] + breakdown['dosage_sensitivity'] + \
                  breakdown['population_frequency'] + breakdown['clinical_evidence']

    total_score = max(0, min(10, total_score))  # Ensure 0-10 range

    return {
        'total_score': round(total_score, 1),
        'breakdown': breakdown,
        'classification': classify_score(total_score)
    }

def classify_score(score):
    """Map score to ACMG-style classification."""
    if score >= 9:
        return 'Pathogenic'
    elif score >= 7:
        return 'Likely Pathogenic'
    elif score >= 4:
        return 'VUS'
    elif score >= 2:
        return 'Likely Benign'
    else:
        return 'Benign'

Report Section:

### 5. Pathogenicity Scoring

#### Quantitative Assessment (0-10 Scale)

| Component | Points | Max | Contribution | Rationale |
|-----------|--------|-----|-------------|-----------|
| **Gene Content** | 4.0 | 4 | 40% | KANSL1 (HI score 3), MAPT (HI score 2) |
| **Dosage Sensitivity** | 2.5 | 3 | 25% | One definitive HI gene (KANSL1) |
| **Population Frequency** | 2.0 | 2 | 20% | Absent from gnomAD SVs |
| **Clinical Evidence** | 1.0 | 1 | 10% | ClinVar pathogenic match |
| **Total Score** | **9.5** | 10 | 100% | |

**Classification**: **Pathogenic** (★★★ High Confidence)

**Interpretation**: Score of 9.5/10 indicates high confidence pathogenic SV. Deletion encompasses established haploinsufficient gene (KANSL1), absent from population databases, and matches known pathogenic ClinVar variant.

#### Score Breakdown Visualization

Gene Content: ████████████████████████████████████████ 4.0/4 Dosage Sensitivity: ██████████████████████████░░░░░░░░░░░░░ 2.5/3 Population Freq: ████████████████████████████████████████ 2.0/2 Clinical Evidence: ██████████████████████████████████████░░ 1.0/1 ───────────────────────────────────────── Total: ██████████████████████████████████████░░ 9.5/10

**Key Drivers of Pathogenicity**:
1. KANSL1 haploinsufficiency (definitive evidence)
2. Exact match to known pathogenic deletion
3. Absence from population databases
4. Phenotype consistency with Koolen-De Vries syndrome

---

Phase 6: Literature & Clinical Evidence

Goal: Find case reports, functional studies, and clinical validation

Tools: | Tool | Purpose | Coverage | |------|---------|----------| | PubMed_search | Peer-reviewed literature | Comprehensive | | DECIPHER_search | Patient case database | Developmental disorders | | EuropePMC_search | European literature | Additional coverage |

Search Strategies:

def comprehensive_literature_search(tu, genes, sv_type, phenotype):
    """
    Search literature for SV evidence.
    """
    # 1. Gene-specific searches
    literature = []
    for gene in genes:
        # Dosage sensitivity literature
        dosage_papers = tu.tools.PubMed_search(
            query=f'"{gene}" AND (haploinsufficiency OR dosage sensitivity OR deletion syndrome)',
            max_results=20
        )

        # Case reports
        case_papers = tu.tools.PubMed_search(
            query=f'"{gene}" AND deletion AND {phenotype}',
            max_results=15
        )

        literature.append({
            'gene': gene,
            'dosage_papers': dosage_papers,
            'case_reports': case_papers
        })

    # 2. SV-specific searches
    if sv_type == 'DEL':
        sv_papers = tu.tools.PubMed_search(
            query=f'deletion AND {" AND ".join(genes[:3])} AND syndrome',
            max_results=25
        )

    # 3. DECIPHER cases
    decipher_cases = []
    for gene in genes:
        cases = tu.tools.DECIPHER_search(
            query=gene,
            search_type="gene"
        )
        decipher_cases.append(cases)

    return {
        'gene_literature': literature,
        'sv_literature': sv_papers,
        'decipher_cases': decipher_cases
    }

Report Section:

### 6. Literature & Clinical Evidence

#### Key Publications

| Study | Finding | Evidence Type | PMID |
|-------|---------|---------------|------|
| Koolen et al., 2006 | Described 17q21.31 microdeletion syndrome | Original description | 16222315 |
| Koolen et al., 2008 | KANSL1 haploinsufficiency confirmed | Functional validation | 18394581 |
| Zollino et al., 2012 | Phenotype characterization (n=52) | Clinical series | 22736773 |

**Key Findings**:
- 17q21.31 deletion is recurrent (mediated by LCRs)
- KANSL1 haploinsufficiency is primary mechanism
- Phenotype: ID (100%), hypotonia (95%), friendly demeanor (85%)
- Penetrance: >95% for developmental features

*Source: PubMed via `PubMed_search`*

#### DECIPHER Patient Cases (n=45)

**Phenotype Frequency in DECIPHER Cohort**:
| Feature | Frequency | Match to Patient |
|---------|-----------|------------------|
| Intellectual disability | 45/45 (100%) | ✓ Yes |
| Hypotonia | 42/45 (93%) | ✓ Yes |
| Feeding difficulties | 38/45 (84%) | ✓ Yes |
| Distinctive facies | 40/45 (89%) | ✓ Yes |
| Friendly personality | 35/45 (78%) | Unknown |

**Phenotype Match**: Patient phenotype highly consistent with DECIPHER cohort (4/4 assessable features present).

**ACMG Code**: **PP4** (Supporting) - Patient's clinical features consistent with gene's known phenotype

*Source: DECIPHER via `DECIPHER_search`*

#### Functional Evidence for KANSL1 Dosage Sensitivity

| Study | Model | Finding | PMID |
|-------|-------|---------|------|
| Koolen et al., 2012 | Patient cells | Reduced KANSL1 protein | 22736773 |
| Zollino et al., 2015 | Mouse model | Kansl1+/- recapitulates phenotype | 25607366 |
| Arbogast et al., 2017 | Zebrafish | kansl1 knockdown → developmental defects | 28666126 |

**Strength of Evidence**: ★★★ (High) - Multiple independent studies confirm haploinsufficiency mechanism

**ACMG Code**: **PS3_Moderate** - Well-established functional studies showing dosage sensitivity

---

Phase 7: ACMG-Adapted Classification

Goal: Apply ACMG/ClinGen criteria adapted for SVs

SV-Specific ACMG Criteria:

Pathogenic Evidence Codes

| Code | Strength | Criteria | SV Application | |------|----------|----------|----------------| | PVS1 | Very Strong | Null variant in HI gene | Complete deletion of HI gene | | PS1 | Strong | Same SV as known pathogenic | ≥70% reciprocal overlap with ClinVar pathogenic | | PS2 | Strong | De novo (maternity/paternity confirmed) | De novo SV in patient with matching phenotype | | PS3 | Strong | Functional studies | Gene dosage effects demonstrated | | PS4 | Strong | Case-control enrichment | SV enriched in cases vs controls | | PM1 | Moderate | Critical region | Deletion of exons in HI gene | | PM2 | Moderate | Absent from controls | Not in gnomAD SVs, DGV | | PM3 | Moderate | Recessive: homozygous or compound het | Both alleles affected (rare for SVs) | | PM4 | Moderate | Protein length change | In-frame deletion/duplication | | PM5 | Moderate | Similar SVs pathogenic | Nearby SVs in ClinVar pathogenic | | PM6 | Moderate | De novo (no confirmation) | De novo SV, phenotype consistent | | PP1 | Supporting | Segregation in family | SV segregates with phenotype | | PP2 | Supporting | Gene/pathway relevant | Genes in SV match phenotype | | PP3 | Supporting | Computational evidence | Multiple predictors support haploinsufficiency | | PP4 | Supporting | Phenotype consistent | Patient phenotype matches gene-disease |

Benign Evidence Codes

| Code | Strength | Criteria | SV Application | |------|----------|----------|----------------| | BA1 | Stand-Alone | MAF >5% | SV frequency >5% in gnomAD | | BS1 | Strong | MAF too high for disease | SV frequency >1% | | BS2 | Strong | Healthy adult with phenotype-associated genotype | SV in healthy individual (careful - reduced penetrance) | | BS3 | Strong | Functional studies show no effect | No dosage sensitivity demonstrated | | BS4 | Strong | Non-segregation | SV doesn't segregate with phenotype | | BP1 | Supporting | Missense in gene without known LOF | N/A for SVs | | BP2 | Supporting | Observed in trans with pathogenic | SV + pathogenic SNV = compound het (patient unaffected) | | BP4 | Supporting | Computational evidence benign | Predictors suggest no haploinsufficiency | | BP5 | Supporting | Found in case with alt cause | Phenotype explained by different variant | | BP7 | Supporting | Synonymous with no splice effect | N/A for SVs |

Classification Algorithm (ACMG SV Criteria):

| Classification | Evidence Required | |----------------|-------------------| | Pathogenic | PVS1 + PS1; OR 2 Strong; OR 1 Strong + 3 Moderate | | Likely Pathogenic | 1 Very Strong + 1 Moderate; OR 1 Strong + 2 Moderate; OR 3 Moderate | | VUS | Criteria not met; OR conflicting evidence | | Likely Benign | 1 Strong + 1 Supporting; OR 2 Supporting | | Benign | BA1; OR BS1 + BS2; OR 2 Strong |

Implementation:

def apply_acmg_criteria(gene_content, dosage_data, frequency_data, clinical_data, inheritance):
    """
    Apply ACMG SV criteria and calculate classification.
    """
    evidence = {
        'pathogenic': [],
        'benign': []
    }

    # PVS1: Complete deletion of HI gene
    hi_genes = [d for d in dosage_data if d['hi_score'] == '3']
    if len(hi_genes) > 0 and len(gene_content['fully_contained']) > 0:
        evidence['pathogenic'].append({
            'code': 'PVS1',
            'strength': 'Very Strong',
            'rationale': f"Complete deletion of haploinsufficient gene(s): {', '.join(g['gene'] for g in hi_genes)}"
        })

    # PS1: Same as known pathogenic SV
    if clinical_data.get('clinvar_pathogenic_match'):
        evidence['pathogenic'].append({
            'code': 'PS1',
            'strength': 'Strong',
            'rationale': f"≥70% overlap with ClinVar pathogenic SV: {clinical_data['clinvar_id']}"
        })

    # PS2: De novo with phenotype match
    if inheritance == 'de_novo' and clinical_data.get('phenotype_match'):
        evidence['pathogenic'].append({
            'code': 'PS2',
            'strength': 'Strong',
            'rationale': "De novo occurrence in patient with consistent phenotype"
        })

    # PS3: Functional studies
    if clinical_data.get('functional_evidence'):
        evidence['pathogenic'].append({
            'code': 'PS3',
            'strength': 'Strong',
            'rationale': "Well-established functional studies demonstrate dosage sensitivity"
        })

    # PM2: Absent from controls
    if frequency_data.get('frequency') == 0 or frequency_data.get('frequency') is None:
        evidence['pathogenic'].append({
            'code': 'PM2',
            'strength': 'Moderate',
            'rationale': "Absent from gnomAD SV database and DGV"
        })

    # PP4: Phenotype consistent
    if clinical_data.get('phenotype_consistent'):
        evidence['pathogenic'].append({
            'code': 'PP4',
            'strength': 'Supporting',
            'rationale': "Patient phenotype highly consistent with gene-disease association"
        })

    # BA1: Common variant
    if frequency_data.get('frequency', 0) > 0.05:
        evidence['benign'].append({
            'code': 'BA1',
            'strength': 'Stand-Alone',
            'rationale': f"Frequency {frequency_data['frequency']:.3f} too high for rare disease"
        })

    # BS1: High frequency
    if 0.01 < frequency_data.get('frequency', 0) <= 0.05:
        evidence['benign'].append({
            'code': 'BS1',
            'strength': 'Strong',
            'rationale': f"Frequency {frequency_data['frequency']:.3f} exceeds expected for disease"
        })

    # Calculate classification
    classification = determine_classification(evidence)

    return {
        'evidence': evidence,
        'classification': classification['class'],
        'confidence': classification['confidence']
    }

def determine_classification(evidence):
    """
    Apply ACMG classification rules.
    """
    path = evidence['pathogenic']
    ben = evidence['benign']

    # Count evidence by strength
    very_strong = len([e for e in path if e['strength'] == 'Very Strong'])
    strong_path = len([e for e in path if e['strength'] == 'Strong'])
    moderate_path = len([e for e in path if e['strength'] == 'Moderate'])
    supporting_path = len([e for e in path if e['strength'] == 'Supporting'])

    standalone_ben = len([e for e in ben if e['strength'] == 'Stand-Alone'])
    strong_ben = len([e for e in ben if e['strength'] == 'Strong'])
    supporting_ben = len([e for e in ben if e['strength'] == 'Supporting'])

    # Benign criteria (takes precedence if strong)
    if standalone_ben >= 1:
        return {'class': 'Benign', 'confidence': '★★★'}
    if strong_ben >= 2:
        return {'class': 'Benign', 'confidence': '★★★'}
    if strong_ben >= 1 and supporting_ben >= 1:
        return {'class': 'Likely Benign', 'confidence': '★★☆'}
    if supporting_ben >= 2:
        return {'class': 'Likely Benign', 'confidence': '★★☆'}

    # Pathogenic criteria
    if very_strong >= 1 and strong_path >= 1:
        return {'class': 'Pathogenic', 'confidence': '★★★'}
    if strong_path >= 2:
        return {'class': 'Pathogenic', 'confidence': '★★★'}
    if very_strong >= 1 and moderate_path >= 1:
        return {'class': 'Likely Pathogenic', 'confidence': '★★☆'}
    if strong_path >= 1 and moderate_path >= 2:
        return {'class': 'Likely Pathogenic', 'confidence': '★★☆'}
    if strong_path >= 1 and moderate_path >= 1 and supporting_path >= 1:
        return {'class': 'Likely Pathogenic', 'confidence': '★★☆'}
    if moderate_path >= 3:
        return {'class': 'Likely Pathogenic', 'confidence': '★☆☆'}

    # Default to VUS
    return {'class': 'VUS', 'confidence': '★☆☆'}

Report Section:

### 7. ACMG-Adapted Classification

#### Evidence Codes Applied

**Pathogenic Evidence**:

| Code | Strength | Rationale |
|------|----------|-----------|
| **PVS1** | Very Strong | Complete deletion of haploinsufficient gene (KANSL1, HI score 3) |
| **PS1** | Strong | ≥95% overlap with ClinVar pathogenic deletion (VCV000012345) |
| **PM2** | Moderate | Absent from gnomAD SV database (>10,000 genomes) |
| **PP4** | Supporting | Patient phenotype consistent with Koolen-De Vries syndrome |

**Benign Evidence**: None

#### Evidence Summary

| Pathogenic | Benign |
|------------|--------|
| 1 Very Strong (PVS1) | None |
| 1 Strong (PS1) | |
| 1 Moderate (PM2) | |
| 1 Supporting (PP4) | |

#### Classification: **PATHOGENIC** ★★★

**Rationale**: Meets ACMG criteria for Pathogenic (1 Very Strong + 1 Strong). Complete deletion of established haploinsufficient gene (KANSL1) with exact match to known pathogenic deletion.

**Confidence**: ★★★ (High) - Multiple independent lines of strong evidence

#### Classification Certainty Factors

✅ **Strengths**:
- Exact match to well-characterized pathogenic deletion
- Complete deletion of definitive HI gene (KANSL1)
- Absent from population databases
- Phenotype highly consistent with gene-disease

⚠ **Limitations**:
- None significant - this is a well-established pathogenic SV

---

Output Structure

Report File: SV_analysis_report.md

# Structural Variant Analysis Report: [SV_IDENTIFIER]

**Generated**: [Date] | **Analyst**: ToolUniverse SV Interpreter

---

## Executive Summary

| Field | Value |
|-------|-------|
| **SV Type** | Deletion / Duplication / Inversion / Translocation |
| **Coordinates** | chr17:44039927-44352659 (GRCh38) |
| **Size** | 313 kb |
| **Gene Content** | 2 genes fully contained, 0 partially disrupted |
| **Classification** | Pathogenic / Likely Pathogenic / VUS / Likely Benign / Benign |
| **Pathogenicity Score** | X.X / 10 |
| **Confidence** | ★★★ / ★★☆ / ★☆☆ |
| **Key Finding** | [One-sentence summary] |

**Clinical Action**: [Required / Recommended / None]

---

## 1. SV Identity & Classification

{SV type, coordinates, size, breakpoint precision, inheritance}

---

## 2. Gene Content Analysis

### 2.1 Fully Contained Genes
{Table of genes with functions, disease associations}

### 2.2 Partially Disrupted Genes
{Genes with breakpoints, domains affected}

### 2.3 Flanking Genes
{Genes near breakpoints, position effect risk}

---

## 3. Dosage Sensitivity Assessment

### 3.1 Haploinsufficient Genes
{ClinGen HI scores, pLI, evidence}

### 3.2 Triplosensitive Genes
{ClinGen TS scores, duplication syndromes}

### 3.3 Non-Dosage-Sensitive Genes
{Genes without established dosage effects}

---

## 4. Population Frequency Context

### 4.1 ClinVar Matches
{Known pathogenic/benign SVs}

### 4.2 gnomAD SV Database
{Population frequencies}

### 4.3 DECIPHER Patient Cases
{Similar SVs, phenotype matching}

---

## 5. Pathogenicity Scoring

### 5.1 Quantitative Assessment
{0-10 score with breakdown}

### 5.2 Score Components
{Gene content, dosage, frequency, clinical}

---

## 6. Literature & Clinical Evidence

### 6.1 Key Publications
{Functional studies, case series}

### 6.2 DECIPHER Cohort Analysis
{Phenotype frequencies, matching}

### 6.3 Functional Evidence
{Gene dosage studies}

---

## 7. ACMG-Adapted Classification

### 7.1 Evidence Codes Applied
{Pathogenic and benign codes with rationale}

### 7.2 Classification
{Final classification with confidence}

### 7.3 Certainty Factors
{Strengths and limitations}

---

## 8. Clinical Recommendations

### 8.1 For Affected Individual
{Testing, management, surveillance}

### 8.2 For Family Members
{Cascade testing, genetic counseling}

### 8.3 Reproductive Considerations
{Recurrence risk, prenatal testing}

---

## 9. Limitations & Uncertainties

{Missing data, conflicting evidence, knowledge gaps}

---

## Data Sources

{All tools and databases queried with results}

---

Evidence Grading System

| Symbol | Confidence | Criteria | |--------|------------|----------| | ★★★ | High | ClinGen definitive, ClinVar expert reviewed, multiple independent studies | | ★★☆ | Moderate | ClinGen strong/moderate, single good study, DECIPHER cohort support | | ★☆☆ | Limited | Computational predictions only, case reports, emerging evidence |

---

Special Scenarios

Scenario 1: Recurrent Microdeletion Syndrome

Additional considerations:

• Check for recurrence mechanism (LCRs, NAHR)
• Look for founder effects
• Population-specific frequencies
• Incomplete penetrance
• Variable expressivity

Example: 22q11.2 deletion, 17q21.31 deletion (Koolen-De Vries)

Scenario 2: Balanced Translocation (No Gene Disruption)

Assessment approach:

• If no genes disrupted: Likely benign (in most cases)
• Check for cryptic imbalances
• Consider position effects (rare)
• Reproductive risk (unbalanced offspring)

Classification: Usually VUS or Likely Benign unless offspring affected

Scenario 3: Complex Rearrangement

Analysis strategy:

• Break down into component SVs
• Assess each breakpoint independently
• Look for chromothripsis pattern
• Consider cumulative gene dosage effects
• Check for DNA repair defects

Scenario 4: Small In-Frame Deletion/Duplication

Special considerations:

• May not cause haploinsufficiency
• Check if critical domain affected
• Look for similar variants in ClinVar
• Consider protein structural impact
• May need functional studies

---

Quantified Minimums

| Section | Requirement | |---------|-------------| | Gene content | All genes in SV region annotated | | Dosage sensitivity | ClinGen scores for all genes (if available) | | Population frequency | Check gnomAD SV + ClinVar + DGV | | Literature search | ≥2 search strategies (PubMed + DECIPHER) | | ACMG codes | All applicable codes listed |

---

Tools Reference

Core Tools for SV Analysis

| Tool | Purpose | Required? | |------|---------|-----------| | ClinGen_search_dosage_sensitivity | HI/TS scores | Required | | ClinGen_search_gene_validity | Gene-disease validity | Required | | ClinVar_search_variants | Known pathogenic/benign SVs | Required | | DECIPHER_search | Patient cases, phenotypes | Highly recommended | | Ensembl_lookup_gene | Gene coordinates, structure | Required | | OMIM_search, OMIM_get_entry | Gene-disease associations | Required | | DisGeNET_search_gene | Additional disease associations | Recommended | | PubMed_search | Literature evidence | Recommended | | Gene_Ontology_get_term_info | Gene function | Supporting |

---

Report File Naming

SV_analysis_[TYPE]_chr[CHR]_[START]_[END]_[GENES].md

Examples:
SV_analysis_DEL_chr17_44039927_44352659_KANSL1_MAPT.md
SV_analysis_DUP_chr22_17400000_17800000_TBX1.md
SV_analysis_INV_chr11_2100000_2400000_complex.md

---

Clinical Recommendations Framework

For Pathogenic/Likely Pathogenic SVs

| SV Type | Recommendations | |---------|-----------------| | Deletion (HI gene) | Genetic counseling, cascade testing, phenotype-specific surveillance | | Duplication (TS gene) | Same as deletion; check for dosage-specific syndrome | | Translocation (disruption) | Assess both breakpoints, consider reproductive counseling | | Complex | Multidisciplinary evaluation, research enrollment |

For VUS

| Action | Details | |--------|---------| | Clinical management | Base on phenotype, not genotype | | Follow-up | Reinterpret in 1-2 years or when phenotype evolves | | Research | Functional studies if research-grade samples available | | Family studies | Segregation analysis can reclassify |

For Benign/Likely Benign

| Action | Details | |--------|---------| | Clinical | Not expected to cause rare disease | | Family | No cascade testing needed (unless recurrent/reproductive risk) | | Reproductive | Balanced translocation carriers may have offspring risk |

---

When NOT to Use This Skill

• Single nucleotide variants (SNVs) → Use tooluniverse-variant-interpretation skill
• Small indels (<50 bp) → Use variant interpretation skill
• Somatic variants in cancer → Different framework needed
• Mitochondrial variants → Specialized interpretation required
• Repeat expansions → Different mechanism

Use this skill for structural variants ≥50 bp requiring dosage sensitivity assessment and ACMG-adapted classification.

---

See Also

• EXAMPLES.md - Sample SV interpretations
• README.md - Quick start guide
• tooluniverse-variant-interpretation - For SNVs and small indels
• ClinGen Dosage Sensitivity Map: https://www.ncbi.nlm.nih.gov/projects/dbvar/clingen/
• ACMG SV Guidelines: Riggs et al., Genet Med 2020 (PMID: 31690835)