/cnv-acmg-classifier

name: cnv-acmg-classifier
description: >-
  Classify structural variants / copy-number variants (deletions and
  duplications) using the ClinGen / ACMG 2019 (Riggs et al. 2020) point
  framework and return a five-tier classification with a per-section evidence
  trail. Germline CNV interpretation, not SNV/indel.
license: MIT
metadata:
  version: "0.1.0"
  author: ClawBio Contributors
  domain: clinical-genomics
  tags:
    - cnv
    - structural-variant
    - acmg
    - clingen
    - dosage-sensitivity
  inputs:
    - name: input_file
      type: file
      format:
        - vcf
        - csv
        - tsv
      description: CNV/SV calls (VCF with SVTYPE/END, or a CSV/TSV with cnv_id,chrom,start,end,type)
      required: true
    - name: dosage_map
      type: file
      format:
        - csv
      description: Optional dosage-sensitivity map (chrom,start,end,name,hi_score,ts_score,benign)
      required: false
    - name: gene_model
      type: file
      format:
        - csv
      description: Optional protein-coding gene model (chrom,start,end,gene) for gene counting
      required: false
  outputs:
    - name: report
      type: file
      format:
        - md
      description: Per-CNV classification report with evidence codes and tier counts
    - name: result
      type: file
      format:
        - json
      description: Machine-readable classifications with section-by-section evidence
  dependencies:
    python: ">=3.10"
    packages:
  demo_data:
    - path: demo_cnv_calls.csv
      description: Seven synthetic CNVs spanning all five ACMG tiers
    - path: data/curated_dosage_map.csv
      description: Curated demonstration dosage-sensitivity map
    - path: data/curated_gene_model.csv
      description: Curated demonstration gene model (incl. a 40-gene cluster)
  endpoints:
    cli: python skills/cnv-acmg-classifier/cnv_acmg_classifier.py --input {input_file} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🦖"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
    trigger_keywords:
      - CNV classification
      - copy number variant ACMG
      - structural variant interpretation
      - ClinGen dosage sensitivity
      - deletion duplication pathogenic

🦖 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

# Standard usage (bring your own dosage map + gene model for real work)