tooluniverse-structural-variant-analysis

What this skill does

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

# Structural Variant Analysis Workflow

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

**LOOK UP DON'T GUESS** - Always retrieve ClinGen HI/TS scores, gnomAD frequencies, and ClinVar evidence from tools. Do not infer dosage sensitivity from gene function alone.

**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 (High/Moderate/Limited)
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. Respond in the user's language

---

## 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

---

## SV Pathogenicity Reasoning (Start Here)

Before any tool call, apply this reasoning to frame the analysis:

**SV pathogenicity depends on what the SV disrupts. A deletion removing an entire gene is likely pathogenic if the gene is haploinsufficient. A duplication is pathogenic if the gene is dosage-sensitive. An inversion is pathogenic only if it disrupts a coding region or regulatory element at the breakpoint.**

Work through these questions in order:

**1. What type is the SV, and what disruption mechanism does it cause?**
- **Deletion**: loss of one copy. Pathogenic if any contained gene is haploinsufficient (ClinGen HI score 3, pLI >= 0.9). A deletion of a dosage-insensitive gene in a gene-dense region may be benign even if large.
- **Duplication**: gain of one copy. Pathogenic if any contained gene is dosage-sensitive (ClinGen TS score 3). Duplications can also disrupt gene regulation if tandem (disrupts reading frame at junction) or if they separate a gene from its enhancer.
- **Inversion**: no copy number change. Pathogenic only at the breakpoints: if one breakpoint falls within an exon (truncation) or separates a gene from its regulatory element. Inversions entirely within gene-poor, regulatory-poor regions are often benign.
- **Translocation**: pathogenic if a breakpoint disrupts a coding region or creates a pathogenic fusion gene. Balanced translocations in parents of affected children warrant special scrutiny.
- **Complex rearrangements**: assess each segment and each breakpoint independently.

**2. Is the disrupted gene dosage-sensitive?**
- ClinGen HI score 3 = definitive haploinsufficiency (deletion of this gene is pathogenic)
- ClinGen HI score 2 = likely haploinsufficient
- pLI >= 0.9 = strong LoF intolerance (supporting haploinsufficiency)
- ClinGen TS score 3 = definitive triplosensitivity (duplication is pathogenic)
- If no ClinGen data: use OMIM inheritance (autosomal dominant = often dosage-sensitive) as weaker evidence

**3. Does the population frequency contextualize the SV?**
- >=1% frequency in gnomAD SV = BA1 (likely benign unless phenotype is extreme)
- <0.01% = supports pathogenicity (PM2)
- Present in unaffected parents = weak evidence against pathogenicity, but not conclusive

**4. Is there clinical precedent?**
- Identical SV in ClinVar as Pathogenic/Likely Pathogenic = strong evidence (PS1)
- De novo occurrence = strong evidence for pathogenicity (PS2)
- Phenotype match to known gene-disease association = supporting evidence (PP4)

Document this reasoning before computing the final score.

---

## Workflow Overview

```
Phase 1: SV IDENTITY & CLASSIFICATION
  Normalize coordinates (hg19/hg38), determine type (DEL/DUP/INV/TRA/CPX),
  calculate size, assess breakpoint precision

Phase 2: GENE CONTENT ANALYSIS
  Identify fully contained genes, partially disrupted genes (breakpoint within),
  flanking genes (within 1 Mb), annotate function and disease associations

Phase 3: DOSAGE SENSITIVITY ASSESSMENT
  ClinGen HI/TS scores, pLI scores, OMIM inheritance patterns,
  gene-disease validity levels

Phase 4: POPULATION FREQUENCY CONTEXT
  gnomAD SV database, ClinVar known SVs, DECIPHER patient cases,
  reciprocal overlap calculation (>=70% = same SV)

Phase 5: PATHOGENICITY SCORING
  Quantitative 0-10 scale: gene content (40%), dosage sensitivity (30%),
  population frequency (20%), clinical evidence (10%)

Phase 6: LITERATURE & CLINICAL EVIDENCE
  PubMed searches, DECIPHER cohort analysis, functional evidence

Phase 7: ACMG-ADAPTED CLASSIFICATION
  Apply SV-specific evidence codes, calculate final classification,
  generate clinical recommendations
```

---

## Phase 1: SV Identity & Classification

**Goal**: Standardize SV notation and classify type.

Capture: chromosome(s), coordinates (start/end in hg19/hg38), SV size, SV type (DEL/DUP/INV/TRA/CPX), breakpoint precision, inheritance pattern (de novo/inherited/unknown).

For SV type definitions, scoring tables, and ACMG code details, see `CLASSIFICATION_GUIDE.md`.

---

## Phase 2: Gene Content Analysis

**Goal**: Annotate all genes affected by the SV.

Tools:
- `ensembl_lookup_gene` - gene structure, coordinates, exons
- `NCBIGene_search` - official symbol, aliases, description
- `GO_get_term_details` - biological process, molecular function
- `OMIM_search`, `OMIM_get_entry` - disease associations, inheritance
- `DisGeNET_search_gene` - gene-disease association scores

Classify genes as: **fully contained** (entire gene in SV), **partially disrupted** (breakpoint within gene), or **flanking** (within 1 Mb of breakpoints).

For implementation pseudocode, see `ANALYSIS_PROCEDURES.md` Phase 2.

---

## Phase 3: Dosage Sensitivity Assessment

**Goal**: Determine if affected genes are dosage-sensitive.

Tools:
- `ClinGen_search_dosage_sensitivity` - HI/TS scores (0-3, gold standard)
- `ClinGen_search_gene_validity` - gene-disease validity level
- `gnomad_search_variants` - pLI scores for LoF intolerance
- `OMIM_get_entry` - inheritance pattern (AD suggests dosage sensitivity)

Interpret scores using the reasoning above. ClinGen HI/TS score 3 = definitive; score 2 = likely; score 1 = little evidence; score 0 = no evidence. Do not equate AD inheritance with haploinsufficiency without ClinGen support.

---

## Phase 4: Population Frequency Context

**Goal**: Determine if SV is common (likely benign) or rare (supports pathogenicity).

Tools:
- `gnomad_search_variants` - population SV frequencies
- `ClinVar_search_variants` - known pathogenic/benign SVs
- `ClinGen_search_dosage_sensitivity` - patient SVs with phenotypes

Use >=70% reciprocal overlap to define "same" SV for comparison. A frequency >=1% triggers BA1 unless there is very strong clinical evidence to override.

---

## Phase 5: Pathogenicity Scoring

**Goal**: Quantitative pathogenicity assessment on 0-10 scale.

Four components weighted: gene content (40%), dosage sensitivity (30%), population frequency (20%), clinical evidence (10%).

Score mapping: 9-10 = Pathogenic, 7-8 = Likely Pathogenic, 4-6 = VUS, 2-3 = Likely Benign, 0-1 = Benign.

For detailed scoring breakdowns and implementation, see `CLASSIFICATION_GUIDE.md` and `ANALYSIS_PROCEDURES.md` Phase 5.

---

## Phase 6: Literature & Clin