/snpeff-variant-annotation

name: "snpeff-variant-annotation"
description: "Annotate and filter VCF variants with SnpEff and SnpSift. SnpEff predicts functional effects (HIGH/MODERATE/LOW/MODIFIER), genes, transcripts, AA changes, HGVS; SnpSift filters and adds ClinVar/dbSNP. Java CLI with Python subprocess integration. Use ANNOVAR for multi-database annotation; Ensembl VEP for REST API; SnpEff for fast CLI with pre-built genomes."
license: "MIT"

SnpEff + SnpSift — Variant Annotation and Filtering

Overview

SnpEff annotates variants in VCF files by predicting their functional consequences: impact level (HIGH, MODERATE, LOW, MODIFIER), affected gene and transcript, amino acid change, and HGVS notation. SnpSift is the companion tool for filtering, sorting, and enriching annotated VCFs with external databases such as ClinVar and dbSNP. Together they form a fast, self-contained pipeline for going from raw variant calls to biologically interpretable, filtered variant sets. Both tools are Java-based and are invoked from the command line or Python subprocess; pre-built genome databases (hg38, GRCh37, mm10, and 100+ others) are downloaded with a single command.

When to Use

• Annotating VCF files from GATK, DeepVariant, bcftools, or other callers with predicted gene-level functional consequences before manual review or downstream filtering
• Prioritizing clinically relevant variants by filtering to HIGH-impact stop-gain, frameshift, and splice-site variants for rare disease or cancer gene panel analysis
• Adding ClinVar pathogenicity classifications and dbSNP rsIDs to a variant set for cross-study comparison or clinical reporting
• Extracting structured, tab-delimited fields (gene, protein change, AF, ClinSig) from annotated VCFs into pandas DataFrames for statistical analysis
• Identifying candidate de novo variants in trio analysis by combining allele frequency thresholds, impact filters, and parent VCF exclusion
• Use **omics-plotting** SKILL to render consequence/impact bar charts from the annotated variant tables
• Use **ANNOVAR** instead when comprehensive annotation from multiple databases (gnomAD, CADD, SpliceAI) in a single run is required
• Use **Ensembl VEP** instead when REST API access or VEP-specific plugins (CADD, LOFTEE, SpliceRegion) are needed

Prerequisites

• **Java**: Java 11+ (required for SnpEff 5.x)
• **SnpEff JAR**: downloaded from the SnpEff releases page or via conda/bioconda
• **Python packages** (optional): `cyvcf2`, `pandas`, `matplotlib`, `seaborn` for Python-side parsing and visualization
• **Reference genome database**: downloaded once per assembly (e.g., `hg38`, `GRCh37`, `mm10`)

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v snpEff` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run snpEff` rather than bare `snpEff`.

# Download SnpEff JAR
wget https://snpeff.blob.core.windows.net/versions/snpEff_latest_core.zip
unzip snpEff_latest_core.zip
# JAR is at snpEff/snpEff.jar and snpEff/SnpSift.jar

# Or via conda (recommended for reproducibility)
conda install -c bioconda snpeff

# Verify
java -jar snpEff/snpEff.jar -version
# SnpEff 5.2a (build 2024-02-06)

# Install Python packages for downstream parsing
pip install cyvcf2 pandas matplotlib seaborn

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: annotationDatabase
    kind: required
    source: upstream
    ask: "Which genome database should annotate these variants, and does its assembly match the VCF coordinates?"
    default: "the assembly the variants were called on"

  - id: D2
    param: transcriptScope
    kind: required
    source: user
    ask: "Report the consequence on every transcript of a gene, or only on the canonical one?"
    default: "all transcripts - the worst consequence across them is what most filters use"

  - id: D3
    param: filterExpression
    kind: required
    source: user
    ask: "Which annotated variants should survive into the final table - by predicted impact, population frequency, or clinical significance?"
    default: null

  - id: D4
    param: frequencySkip
    kind: optional_conditional
    source: user
    ask: "Skip annotating variants already common in the population?"
    default: "annotate everything"

  - id: D5
    param: summaryReport
    kind: optional
    source: user
    ask: "Generate the HTML summary alongside the annotated VCF?"
    default: "generated"

  - id: D6
    param: javaHeap
    kind: never_ask
    source: data
    reason: "Prevents out-of-memory on large VCFs; does not change annotations"
    default: "4-8 GB"

D3 has no safe default because the filter is the deliverable - a rare-disease question keeps high-impact rare variants, a pharmacogenomic one keeps known clinical annotations regardless of impact. Applying somebody else's filter silently answers their question instead.

Quick Start

# 1. Download the hg38 genome database (one-time setup, ~1 GB)
java -jar snpEff/snpEff.jar download hg38

# 2. Annotate variants
java -jar snpEff/snpEff.jar \
    -v hg38 \
    input.vcf.gz \
    > annotated.vcf

# 3. Filter to HIGH-impact variants
java -jar snpEff/SnpSift.jar filter \
    "ANN[*].IMPACT = 'HIGH'" \
    annotated.vcf \
    > high_impact.vcf

echo "Done. Check snpEff_summary.html and snpEff_genes.txt for QC stats."

Workflow

Step 1: Install SnpEff and Download Genome Database

Download and verify the pre-built genome database for your target assembly. Databases include transcript models from Ensembl or UCSC and are built into SnpEff's local cache directory (`~/.snpEff/data/` or `snpEff/data/`).

# List all available databases (grep for your assembly)
java -jar snpEff/snpEff.jar databases | grep -i "GRCh38\|hg38"

# Download hg38 (Homo sapiens, GRCh38)
j