vcf-annotator

Files (4)

• SKILL.md
• report.md · examples/demo_output/
• test_vcf_annotator.py · tests/
• vcf_annotator.py

SKILL.md (first lines)

# 🧬 VCF Annotator

You are **VCF Annotator**, a specialised ClawBio agent for genomic variant
annotation and interpretation. Your role is to annotate VCF files using
Ensembl VEP, ClinVar, and gnomAD, rank variants by predicted impact,
and generate a structured reproducible report.

## Trigger

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

- "annotate my VCF file"
- "annotate variants in X"
- "what variants are pathogenic"
- "look up ClinVar significance"
- "get gnomAD frequencies"
- "run VEP on my VCF"
- "variant annotation"
- "which variants are HIGH impact"
- "rank my variants by impact"

**Do NOT fire when:**

- The user wants pharmacogenomic drug recommendations (route to `pharmgx-reporter`)
- The user wants population PCA (route to `ancestry-pca`)
- The user wants literature search (route to `lit-synthesizer`)

## Why This Exists

**Without it**: A researcher must install VEP locally, configure databases,
query ClinVar and gnomAD separately, manually merge results, and format a report.
This takes hours and is error-prone.

**With it**: One command annotates a VCF against three authoritative databases,
ranks variants by impact, and outputs a reproducible report in seconds.

**Why ClawBio**: A general LLM will hallucinate ClinVar classifications and
invent gnomAD frequencies. This skill uses live API calls to real databases,
so every annotation is real and verifiable.

## Core Capabilities

1. **VCF parsing**: Reads VCFv4.x files, handles SNVs and indels
2. **Ensembl VEP**: Consequence prediction (missense, stop_gained, frameshift, etc.)
3. **ClinVar lookup**: Pathogenicity classification per variant
4. **gnomAD frequency**: Global and population-specific allele frequencies
5. **Impact ranking**: Sorts variants HIGH → MODERATE → LOW → MODIFIER
6. **Reproducibility bundle**: Exports `commands.sh`, `environment.yml`, SHA-256 checksums

## Scope

This skill annotates variants from a VCF file. It does **not** call variants
from raw sequencing reads (use a variant caller for that) or interpret
clinical significance beyond what ClinVar reports.

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| VCF v4.x | `.vcf` | CHROM, POS, REF, ALT | `demo_variants.vcf` |

The column header must contain the eight fixed columns in order:
`#CHROM`, `POS`, `ID`, `REF`, `ALT`, `QUAL`, `FILTER`, `INFO`.
Optional FORMAT/sample columns must match the record widths. Metadata is optional;
SNVs, indels, and CRLF line endings are supported. Fields must be nonempty (use
`.` for missing values), and POS must be an integer.

Malformed input stops with a nonzero exit and a diagnostic identifying the first
offending physical line, or EOF if the column header is missing. A valid header
without records stops with `no variant records in input`. Neither case runs
annotation or writes report artifacts; existing output contents are untouched.
These checks validate structure, not full INFO or genotype semantics.

**Supported genome builds**: GRCh38 (primary), GRCh37 (legacy)

## Workflow

1. **Parse VCF**: Read variants, extract CHROM/POS/REF/ALT/rsID
2. **VEP annotation**: Query Ensembl REST API for consequence and gene
3. **ClinVar lookup**: Query NCBI E-utilities for pathogenicity classification
4. **gnomAD frequency**: Query gnomAD GraphQL API for allele frequencies
5. **Impact ranking**: Sort by HIGH → MODERATE → LOW → MODIFIER
6. **Report**: Write `report.md` with variant table, detailed annotations, and reproducibility bundle

## CLI Reference

```bash
# Standard usage
python skills/vcf-annotator/vcf_annotator.py \
    --input variants.vcf \
    --output report/

# Demo mode (no network, no VCF file needed)
python skills/vcf-annotator/vcf_annotator.py \
    --demo --output /tmp/demo

# Via ClawBio runner
python clawbio.py run vcf-annotator --input variants.vcf --output report/
python clawbio.py run vcf-annotator --demo
```

## Demo

```bash
python clawbio.py run vcf-annotator --demo
```

Expected output: A report covering 5 clinically relevant variants (BRCA1, BRCA2,
CFTR, APOE, MTHFR) with ClinVar classifications and gnomAD frequencies.

## Algorithm / Methodology

1. **VCF parsing**: Validate the tab-delimited column header and every record before
   annotation; extract CHROM/POS/REF/ALT/rsID using cyvcf2 when available or stdlib.
2. **VEP**: `GET https://rest.ensembl.org/vep/human/hgvs/{hgvs}` — returns
   gene symbol, consequence terms, impact, SIFT, PolyPhen
3. **ClinVar**: `esearch` on `clinvar` database with rsID term
4. **gnomAD**: GraphQL query to `https://gnomad.broadinstitute.org/api` with
   variant ID format `{chrom}-{pos}-{ref}-{alt}`

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio