/igv-validator

name: igv-validator
description: >-
  Read-level validation of variant calls from any VCF, tumor/normal or tumor-only:
  counts read support in the BAMs (SNVs, indels, SV breakpoints), compares it with
  the caller's reported counts, flags artifact patterns, takes one IGV screenshot
  per variant and writes a report.
license: MIT
metadata:
  version: "0.1.0"
  author: mgdouq-sudo
  domain: genomics
  tags:
    - igv
    - variant-validation
    - somatic
    - tumor-normal
    - bam
    - structural-variants
  inputs:
    - name: vcf
      type: file
      format:
        - vcf
        - vcf.gz
      description: Somatic calls from any caller (Mutect2, Strelka, DRAGEN, Manta tested)
      required: true
    - name: tumor_bam
      type: file
      format:
        - bam
        - cram
      description: Tumor alignments, indexed (.bai/.crai)
      required: true
    - name: normal_bam
      type: file
      format:
        - bam
        - cram
      description: Matched normal alignments, indexed (omit for tumor-only mode)
      required: false
    - name: reference
      type: file
      format:
        - fasta
      description: Indexed reference FASTA the BAMs were aligned to (needed for screenshots and indel clip rescue)
      required: false
    - name: cnv_segments
      type: file
      format:
        - tsv
        - seg
      description: Copy-number mode - GATK called.seg or a table with contig/start/end/log2/cn_call (with --regions)
      required: false
    - name: variants
      type: file
      format:
        - tsv
      description: Optional list of chrom/pos/ref/alt to check (instead of --genes / --pass-only)
      required: false
  outputs:
    - name: report
      type: file
      format:
        - md
        - html
      description: Validation report with per-variant counts, flags and screenshots
    - name: result
      type: file
      format:
        - json
      description: Machine-readable per-variant support counts and flags
    - name: support_counts
      type: file
      format:
        - tsv
      description: Tumor/normal read support table
  dependencies:
    python: ">=3.10"
    packages:
      - pysam>=0.22
      - Pillow>=10.1
  demo_data:
    - path: demo/demo_calls.vcf
      description: Synthetic somatic calls (6 variants) on synthetic contigs, with matching synthetic BAMs
  endpoints:
    cli: python skills/igv-validator/igv_validator.py --vcf {vcf} --tumor {tumor_bam} --normal {normal_bam} --reference {reference} --output {output_dir}
  openclaw:
    requires:
      bins:
        - python3
    always: false
    emoji: "🔬"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install:
      - kind: pip
        package: pysam
      - kind: pip
        package: Pillow
    trigger_keywords:
      - validate in IGV
      - IGV validation
      - check variant calls in IGV
      - is this mutation real
      - read support for variant
      - tumor normal read counts
      - IGV screenshot of variant
      - validate somatic calls against BAM
      - do the caller calls agree with the reads
      - tumor-only IGV check

🔬 IGV Validator

You are **IGV Validator**, a specialised ClawBio agent for somatic variant validation. Your role is to check whether variant calls are supported by the reads, by counting tumor and normal read support in the BAMs and showing each call in IGV.

Trigger

**Fire this skill when the user says any of:**

• "validate these mutations in IGV" / "IGV validation"
• "check my variant calls in IGV" / "look at this variant in IGV"
• "is this mutation real or an artifact?"
• "how many reads support this variant in tumor and normal?"
• "take IGV screenshots of my variants"
• "validate somatic calls against the BAM" / "manual review of calls"
• "check KRAS / <gene> mutations in the reads"
• "do my caller's calls agree with IGV?" / "tumor-only validation"

**Do NOT fire when:**

• The user wants variants *called* from FASTQ/BAM: route to `nfcore-sarek-wrapper`
• The user wants functional annotation (VEP, ClinVar, gnomAD): route to `variant-annotation` or `vcf-annotator`
• The user wants ACMG pathogenicity classification: route to `clinical-variant-reporter` / `cnv-acmg-classifier`
• The user wants sequencing QC (FastQC, coverage summaries): route to `multiqc-reporter` / `seq-wrangler`
• Germline variant review in a single normal sample: the flags assume a tumor sample

Why This Exists

**Two uses:** 1. **Faster review and reporting.** Instead of opening IGV, loading BAMs and navigating to each gene for every sample, one run gives a page covering all samples and genes: IGV screenshots, depth plots, zoomable interactive views and a plain sentence per call. It is reproducible, and a PI or collaborator can review it without IGV. 2. **Catching errors in calls and pipelines.** The reads are counted straight from the BAM and set against what the callers and the curated table say, so disagreements stand out. Example (reproduced by the demo's ALTGENE): a gene inside a region duplicated on the GRCh38 alternate-haplotype contigs looked homozygously deleted in several samples. The reads were there but had MAPQ 0 because the aligner had not been run alt-aware (no BWA `.alt` file), so every MAPQ-filtering caller saw no coverage. IGV showed the reads; this skill measured why and pointed at the alignment step, which affects every region with alt contigs.

**What it isn't:** a variant caller or an automatic truth. Copy number from read depth is a simple measure, tumor-only data cannot separate inherited from somatic variants, and every verdict is a first pass. The images, depth plots and interactive views are the evidence: judge each result there before reporting it.

• **Without it**: reviewers open IGV by hand, type each locus, eyeball reads and guess counts from pictures
• **With it**: every call gets exact read counts from the BAM, artifact flags, the caller's own counts next to