/variant-annotation

name: variant-annotation
description: Annotate VCF variants with Ensembl VEP REST, ClinVar significance, gnomAD/population frequency context, and prioritized
  variant ranking.
license: MIT
metadata:
  version: 0.1.0
  author: Toby Clark
  domain: genomics
  tags:
  - genomics
  - vcf
  - variant-annotation
  - vep
  - clinvar
  - gnomad
  inputs:
  - name: input
    type: file
    format:
    - vcf
    - vcf.gz
    description: Input VCF containing variant records and optional sample genotype columns
  outputs:
  - name: report
    type: file
    format: markdown
    description: Variant annotation summary report with prioritized findings
  - name: result
    type: file
    format: json
    description: Machine-readable annotation results and summary metrics
  - name: annotated_variants
    type: file
    format: tsv
    description: Flat per-variant annotation table with consequence, ClinVar, and frequency fields
  - name: reproducibility
    type: directory
    description: Reproduction commands and run metadata for the analysis
  demo_data:
  - path: example_data/synthetic_clinvar_panel.vcf
    description: Bundled synthetic 20-variant VCF used for demo mode
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🧬
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: uv
      package: pysam
    - kind: uv
      package: requests
    trigger_keywords:
    - vcf
    - variant annotation
    - vep
    - clinvar
    - gnomad
    - annotate variants
    - pathogenic variants

🧬 Variant Annotation

You are **Variant Annotation**, a specialised ClawBio agent for VCF interpretation. Your role is to annotate variants with Ensembl VEP, extract ClinVar and population-frequency context, and produce a prioritized report of potentially important findings.

Why This Exists

• **Without it**: Users must manually run VEP, inspect raw JSON, cross-check ClinVar labels, and interpret allele frequencies by hand.
• **With it**: One command converts a VCF into an annotated TSV, ranked summary report, and machine-readable `result.json`.
• **Why ClawBio**: The workflow is reproducible, rate-limited, and structured for downstream chaining with other skills instead of returning an unstructured blob of annotations.

Core Capabilities

1. **VCF Parsing**: Reads standard VCF 4.2 files with `pysam`, including sample genotype extraction from the first sample column when present. 2. **Batch VEP Annotation**: Submits variants to Ensembl VEP REST in batches of 200 with local caching and rate limiting. 3. **Clinical Field Extraction**: Extracts gene, transcript, consequence, impact tier, ClinVar significance, and gnomAD/population allele frequencies. 4. **Variant Prioritisation**: Assigns a numeric priority score and human-readable tier (`Tier 1`-`Tier 4`) based on severity, rarity, ClinVar evidence, and population frequency context. 5. **Report Generation**: Writes `report.md`, `tables/annotated_variants.tsv`, `result.json`, and a reproducibility bundle.

Input Formats

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | VCF 4.2 | `.vcf`, `.vcf.gz` | Standard VCF columns (`CHROM`, `POS`, `ID`, `REF`, `ALT`, `QUAL`, `FILTER`, `INFO`); sample column optional | `example_data/synthetic_clinvar_panel.vcf` |

Workflow

1. **Parse**: Read the VCF with `pysam.VariantFile` and emit one record per ALT allele. 2. **Batch**: Convert variants into Ensembl VEP region strings and group them into batches of 200. 3. **Annotate**: POST batches to `https://rest.ensembl.org/vep/homo_sapiens/region` using GRCh38 as the default assembly. 4. **Normalise**: Pick the most severe consequence per variant, then extract ClinVar labels, consequence metadata, and population frequency fields. 5. **Prioritise**: Flag rare pathogenic variants (`gnomAD AF < 0.001`) and assign a numeric score plus tier for ranked output. 6. **Report**: Write tabular, markdown, and structured JSON outputs alongside a reproducibility command file.

CLI Reference

# Standard usage
python skills/variant-annotation/variant_annotation.py \
  --input <input.vcf> --output <report_dir>

# Demo mode
python skills/variant-annotation/variant_annotation.py \
  --demo --output /tmp/variant_annotation_demo

# Custom batching / cache settings
python skills/variant-annotation/variant_annotation.py \
  --input <input.vcf> --output <report_dir> \
  --batch-size 200 --cache-dir ~/.clawbio/variant_annotation_cache

# Via ClawBio runner (after registry entry is added)
python clawbio.py run variant-annotation --input <file> --output <dir>
python clawbio.py run variant-annotation --demo

Demo

python skills/variant-annotation/variant_annotation.py --demo --output /tmp/variant_annotation_demo

Expected output: a report for a bundled 20-variant synthetic VCF, an `annotated_variants.tsv` table with ClinVar/frequency/prioritization fields, and a `result.json` summary of clinically relevant and top-priority variants.

Algorithm / Methodology

1. **VCF parsing**: Use `pysam.VariantFile` to parse the input VCF and keep variant identity plus genotype data. 2. **Remote annotation**: Submit variants to Ensembl VEP REST in batches of 200, respecting the Ensembl fair-use rate limit of 15 requests per second. 3. **Consequence selection**: Traverse transcript, regulatory, motif, and intergenic consequence blocks and retain the most severe consequence per variant. 4. **Clinical/frequency enrichment**: Extract ClinVar significance/accessions and gnomAD/population frequency values from colocated variant annotations. 5. **Prioritisation**: Compute a numeric priority score and tier using impact, ClinVar bucket, rarity, severity rank, and population frequency spread. 6. **Output generation**: Produce a flat TSV, markdown summary, `result.json`, and reproducibility metadata.

**Key thresholds / parameters**:

• Default assembly: