tooluniverse-structural-variant-analysis

## 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
- `Gene_Ontology_get_term_info` - 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 & Clinical Evidence

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

Tools:
- `PubMed_search_articles` - peer-reviewed literature
- `EuropePMC_search_articles` - additional coverage
- `ClinGen_search_dosage_sensitivity` - patient case database

Search strategies: gene-specific dosage sensitivity papers, SV-specific case reports, phenotype-gene associations. See `ANALYSIS_PROCEDURES.md` Phase 6.

---

## Phase 7: ACMG-Adapted Classification

**Goal**: Apply ACMG/ClinGen criteria adapted for SVs and generate a final classification with explicit evidence summary.

The LLM knows the ACMG criteria codes and combination rules. Apply them to the evidence gathered in Phases 1-6. Key points to verify with tool data:
- PVS1 applies to deletions of genes with ClinGen HI score >= 2 or pLI >= 0.9
- PS2 requires confirmed de novo status (check parental genotypes if available)
- PM2 requires absence from population databases at >=70% reciprocal overlap

For complete evidence code tables and classification algorithm, see `CLASSIFICATION_GUIDE.md`.

---

## Output

Create report using the template in `REPORT_TEMPLATE.md`. Name files as:
```
SV_analysis_[TYPE]_chr[CHR]_[START]_[END]_[GENES].md
```

---

## Required Tools Reference

- `ClinGen_search_dosage_sensitivity` - HI/TS scores (required for all deletions/duplications)
- `ClinGen_search_gene_validity` - gene-disease validity (required)
- `ClinVar_search_variants` - known pathogenic/benign SVs (required)
- `ensembl_lookup_gene` - gene coordinates, structure (required)
- `OMIM_search`, `OMIM_get_entry` - gene-disease associations (required)
- `gnomad_search_variants` - population frequency and pLI (required)
- `DisGeNET_search_gene` - additional disease associations (recommended)
- `PubMed_search_articles` - literature evidence (recommended)
- `Gene_Ontology_get_term_info` - gene function (supporting)

---

## When NOT to Use This Skill

- **Single nucleotide variants (SNVs)** - Use `tooluniverse-variant-interpretation`
- **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.

---

## Reference Files

- `EXAMPLES.md` - Sample SV interpretations with worked examples
- `CLASSIFICATION_GUIDE.md` - ACMG criteria, scoring system, evidence codes, special scenarios, clinical recommendations
- `REPORT_TEMPLATE.md` - Full report template with section structure and file naming
- `ANALYSIS_PROCEDURES.md` - Detailed implementation pseudocode for each phase

## External References

- ClinGen Dosage Sensitivity Map: https://www.ncbi.nlm.nih.gov/projects/dbvar/clingen/
- ACMG SV Guidelines: Riggs et al., Genet Med 2020 (PMID: 31690835)
- `tooluniverse-variant-interpretation` - For SNVs and small indels