cnv-acmg-classifier

Files (9)

• INTENTS.json
• SKILL.md
• cnv_acmg_classifier.py
• curated_dosage_map.csv · data/
• curated_gene_model.csv · data/
• demo_cnv_calls.csv
• expected_classifications.csv · examples/
• expected_demo_report.md · examples/
• test_cnv_acmg_classifier.py · tests/

SKILL.md (first lines)

# 🦖 CNV ACMG Classifier

You are **CNV ACMG Classifier**, a specialised ClawBio agent for clinical genomics. Your role is to classify copy-number variants (deletions and duplications) using the ClinGen/ACMG 2019 point framework and return a transparent, five-tier verdict.

## Trigger

**Fire this skill when the user says any of:**
- "classify this CNV" / "classify this copy-number variant"
- "is this deletion / duplication pathogenic?"
- "ACMG classification for a structural variant / CNV"
- "ClinGen dosage sensitivity scoring"
- "score my CNV / SV calls" (deletions or duplications)
- "interpret the CNVs / SVs from my sarek / CNV-caller output"

**Do NOT fire when:**
- The user wants SNV/indel ACMG classification → route to `clinical-variant-reporter`.
- The user wants to *call* CNVs/SVs from reads → route to `nfcore-sarek-wrapper`.
- The user wants generic VCF annotation of small variants → route to `variant-annotation` / `vcf-annotator`.

**Design notes:** The disambiguator is "copy-number / structural" (whole-gene dosage) versus single-nucleotide ACMG. If the variant is a DEL/DUP spanning genes, it belongs here.

## Why This Exists

- **Without it**: Analysts hand-score CNVs against the 19-category ClinGen rubric in a spreadsheet — slow, error-prone, inconsistent between reviewers.
- **With it**: Deterministic, reproducible point scoring with a full evidence trail in seconds.
- **Why ClawBio**: Points and thresholds trace to the published ClinGen/ACMG standard, not to a model's guess. The agent never invents dosage sensitivity.

## Core Capabilities

1. **Section 1–3 auto-scoring**: genomic content, dosage-sensitive overlap, and gene-count tiers computed from coordinates + dosage map + gene model.
2. **Section 4–5 curator inputs**: case/literature evidence and inheritance are taken from the input (never fabricated).
3. **Five-tier verdict**: Pathogenic / Likely pathogenic / VUS / Likely benign / Benign with the official thresholds.

## Scope

**One skill, one task.** This skill classifies germline CNV/SV dosage effects and nothing else. It does not call variants, annotate SNVs, or predict phenotypes.

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| Table | `.csv` / `.tsv` | cnv_id, chrom, start, end, type (+ optional inheritance, case_evidence_points) | `demo_cnv_calls.csv` |
| VCF | `.vcf` / `.vcf.gz` | CHROM, POS, INFO SVTYPE + END | sarek/Manta/CNVnator output |

Optional reference files: `--dosage-map` columns `chrom,start,end,name,hi_score,ts_score,benign,element_type` (`element_type` is `gene` or `region`) plus, for gene entries, `strand` and `cds_start,cds_end` (used to derive the 2C/2D breakpoint geometry; if omitted the whole gene is treated as coding); `--gene-model` columns `chrom,start,end,gene`. Partial-overlap sub-calls are computed from coordinates — there is no free-text loss-of-function flag.

## Workflow

1. **Validate**: Check input columns (or VCF SVTYPE/END); normalise type to loss/gain.
2. **Process**: For each CNV apply Section 1 (content), Section 2 (dosage/benign overlap), Section 3 (gene count), Section 4 (case evidence), Section 5 (inheritance).
3. **Generate**: Sum points, round to 2 dp, map to the five-tier classification.
4. **Report**: Write `report.md`, `result.json`, `tables/cnv_classifications.csv`, and a reproducibility bundle.

**Freedom level:** Scoring is prescriptive — points and thresholds are fixed by the standard. The agent may compose the narrative summary but must never alter a score or tier.

## CLI Reference

```bash
# Standard usage (bring your own dosage map + gene model for real work)
python skills/cnv-acmg-classifier/cnv_acmg_classifier.py \
  --input cnvs.vcf --dosage-map clingen_dosage.csv --gene-model gencode_genes.csv \
  --output cnv_report

# Demo mode (synthetic data, no user files needed)
python skills/cnv-acmg-classifier/cnv_acmg_classifier.py --demo --output /tmp/cnv_demo

# Via ClawBio runner
python clawbio.py run cnv-acmg --demo
```

## Demo

```bash
python clawbio.py run cnv-acmg --demo
```

Expected output: a report classifying 7 synthetic CNVs covering all five ACMG tiers (2 Pathogenic, 2 Likely pathogenic, 1 VUS, 1 Likely benign, 1 Benign).

## Algorithm / Methodology

ClinGen/ACMG copy-number point framework (Riggs et al. 2020):

The five sections are **additive** — every applicable section contributes points and the total is their sum (there is no early stop on 2A or 2F). Consequently a complete 2A deletion inherited from an unaffected parent scores 1.00 + (−0.30) = 0.70 = VUS, and a de novo 2A gain scores 1.00 + 0.45 = 1.45 = Pathogenic — matching the ClinGen worked examples.

1. **Section 1 — content**: 1A (contains protein-coding/functional element) = 0.00; 1B (no functional content) = −0.60 (nothing further to score).
2. **Section 2 — dosage**: 2A complete overlap of an established (score 3) HI region/gene (loss) or TS region/gene (gain) = +1.00; 2F complete containment in an established benign region = −1.00. Partial overlaps of an established HI **gene** are derived from **breakpoint geometry** (gene strand + coding boundaries), not a free-text flag: 2C-1 (+0.90) 5′ end deleted with coding sequence involved; 2C-2 (0.00) 5′ end, 5′UTR only; 2D-4 (+0.90) 3′ end deleted with coding exon(s) involved; 2D-1 (0.00) 3′ end, 3′UTR only; 2E intragenic (+0.90 if coding involved, else 0.00). Region-level partial overlaps and all gain partials = 2B (0.00, uncertain).
3. **Section 3 — gene number** (per the ClinGen note, omitted **only when a _complete_ established call — 2A or 2F — is made**; a 0-scoring partial such as 2B/2C-2/2D-1 still earns it, so a deletion that merely clips an established region but spans many genes is scored on size): loss → 0–24 (0.00) / 25–34 (+0.45) / ≥35 (+0.90); gain → 0–34 (0.00) / 35–49 (+0.45) / ≥50 (+0.90).
4. **Section 4 — case/literature**: analyst-supplied aggregate points, clamped to ±0.90, always summed.
5. **Section 5 — inheritance**: de novo (both parents tested) = +0.45; inherited from an unaffected parent = −0.30; always summed.

**Key thresholds** (source: ClinGen/ACMG 2019, Riggs 2020) — symmetric about zero:
- Pathogenic ≥ +0.99; Likely pathogenic +0.90 to +0.98; VUS −0.89 to +0.89; Likely benign −0.90 to −0.98; Benign ≤ −0.99.
- "Established" dosage sensitivity = ClinGen score 3 (sufficient evidence).

## Example Queries

- "Classify the deletions in this VCF with ACMG."
- "Is a duplication spanning the 22q11.2 region pathogenic?"
- "Score these CNV calls against ClinGen dosage sensitivity."

## Example Output

```markdown
| CNV | Region | Type | Genes | Score | Classification | Evidence |
|---|---|---|---:|---:|---|---|
| CNV_P_TP53del | chr17:7,660,000-7,695,000 | loss | 1 | 1.00 | Pathogenic | 1A, 2A |
| CNV_LP_TP53partial | chr17:7,680,000-7,700,000 | loss | 1 | 0.90 | Likely pathogenic | 1A, 2C-1, 3A |
| CNV_B_benign | chr1:152,030,000-152,070,000 | loss | 1 | -1.00 | Benign | 1A, 2F |
| CNV_VUS_inh | chr2:50,120,000-50,180,000 | loss | 1 | -0.30 | Variant of uncertain significance | 1A, 3A, 5B |
| CNV_LB_caseev | chr2:50,120,000-50,180,000 | loss | 1 | -0.95 | Likely benign | 1A, 3A, 4, 5B |
| CNV_P_dup22q | chr22:18,800,000-21,600,000 | gain | 3 | 1.45 | Pathogenic | 1A, 2A, 5A |
| CNV_LP_genedense | chr19:51,990,000-52,410,000 | loss | 40 | 0.90 | Likely pathogenic | 1A, 3C |
```

## Output Structure

```
output_directory/
├── report.md                       # Primary markdown report

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio