Version Compatibility

Reference examples tested with: DeepVariant 1.6+, GLnexus 1.4+, bcftools 1.19+

Before using code patterns, verify installed versions match. If versions differ:

• CLI: docker run google/deepvariant:<tag> --version to confirm build
• bcftools --version and bcftools --help to confirm flags

If code throws errors, introspect the installed container and adapt the example to match the actual API rather than retrying.

DeepVariant Variant Calling

How DeepVariant Works

DeepVariant reframes variant calling as an image classification problem rather than a statistical genotyping problem. For each candidate variant site, the make_examples step encodes the local read pileup as a 100x221x6-channel image tensor. The six channels encode: read base identity, base quality, mapping quality, strand orientation, read support for the variant allele, and reference base mismatch. A convolutional neural network (CNN) then classifies each pileup image into one of three genotype classes: homozygous reference, heterozygous, or homozygous alternate.

This image-based approach is why DeepVariant outperforms statistical callers in difficult genomic contexts such as homopolymer runs, tandem repeats, and low-complexity regions -- the CNN learns visual patterns in pileup geometry that heuristic filters miss. Separate models are trained for each sequencing platform because read error profiles differ substantially (e.g., Illumina substitution errors vs. ONT indel errors in homopolymers).

DeepVariant calls germline variants only. For somatic variant calling, use DeepSomatic, a separate tool from the same team.

Installation

docker pull google/deepvariant:1.6.1

# GPU support (NVIDIA GPU + nvidia-container-toolkit required)
docker pull google/deepvariant:1.6.1-gpu

Singularity alternative:

singularity pull docker://google/deepvariant:1.6.1

Model Selection Guide

Model	Data Type	Notes
WGS	Illumina short-read WGS	Default model; trained on 30-50x PCR-free data
WES	Illumina exome/targeted	Must supply --regions BED for efficiency; without it, wastes time scanning non-target regions
PACBIO	PacBio HiFi only	Not trained on CLR reads; CLR error profile is fundamentally different
ONT_R104	ONT R10.4+ chemistry	Accuracy lower than HiFi model; R9.4 reads perform poorly with this model
HYBRID_PACBIO_ILLUMINA	Mixed platforms	Emerging use case for samples with both HiFi and Illumina data

Model selection has a large effect on accuracy. Using the wrong model (e.g., WGS model on HiFi data) silently degrades results because the CNN expects platform-specific error patterns in the pileup images.

When to Use DeepVariant

Best choice when:

• Highest germline accuracy is the primary goal
• GPU resources are available (or CPU time is acceptable)
• Single-sample calling or small cohort with GLnexus for joint genotyping
• Data is from a supported platform (Illumina, HiFi, ONT R10.4+)

Consider GATK HaplotypeCaller instead when:

• Joint calling across large cohorts (GATK GenomicsDB + GenotypeGVCFs scales better)
• VQSR-based filtering is needed (DeepVariant QUAL scores are CNN confidence, not amenable to VQSR)
• Clinical pipeline requires established GATK validation and regulatory precedent

Consider Clair3 instead when:

• Long-read data where speed matters more than marginal accuracy gains
• ONT data specifically (Clair3 has strong ONT-specific models)
• Resource-constrained environments without GPU access

Basic Usage

docker run -v "${PWD}:/input" -v "${PWD}/output:/output" \
    google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/run_deepvariant \
    --model_type=WGS \
    --ref=/input/reference.fa \
    --reads=/input/sample.bam \
    --output_vcf=/output/sample.vcf.gz \
    --output_gvcf=/output/sample.g.vcf.gz \
    --num_shards=16

Always generate gVCFs (--output_gvcf) even for single samples -- they enable downstream joint calling without re-running DeepVariant.

Step-by-Step Workflow

For more control over intermediate outputs, run each stage separately:

Step 1: Make Examples

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/make_examples \
    --mode calling \
    --ref /data/reference.fa \
    --reads /data/sample.bam \
    --examples /data/examples.tfrecord.gz \
    --gvcf /data/gvcf.tfrecord.gz

Step 2: Call Variants

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/call_variants \
    --outfile /data/call_variants.tfrecord.gz \
    --examples /data/examples.tfrecord.gz \
    --checkpoint /opt/models/wgs/model.ckpt

Step 3: Postprocess Variants

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/postprocess_variants \
    --ref /data/reference.fa \
    --infile /data/call_variants.tfrecord.gz \
    --outfile /data/output.vcf.gz \
    --gvcf_outfile /data/output.g.vcf.gz \
    --nonvariant_site_tfrecord_path /data/gvcf.tfrecord.gz

GPU Acceleration

GPU acceleration primarily benefits the call_variants step (CNN inference). The make_examples and postprocess_variants steps are CPU-bound and benefit more from --num_shards parallelism.

docker run --gpus all -v "${PWD}:/data" \
    google/deepvariant:1.6.1-gpu \
    /opt/deepvariant/bin/run_deepvariant \
    --model_type=WGS \
    --ref=/data/reference.fa \
    --reads=/data/sample.bam \
    --output_vcf=/data/output.vcf.gz \
    --num_shards=16

PacBio HiFi Calling

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/run_deepvariant \
    --model_type=PACBIO \
    --ref=/data/reference.fa \
    --reads=/data/hifi_aligned.bam \
    --output_vcf=/data/hifi_variants.vcf.gz \
    --num_shards=16

HiFi reads achieve Q30+ per-read accuracy, giving DeepVariant cleaner pileup images. The PACBIO model is not suitable for CLR reads (Q10-Q15 accuracy).

ONT Calling

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/run_deepvariant \
    --model_type=ONT_R104 \
    --ref=/data/reference.fa \
    --reads=/data/ont_aligned.bam \
    --output_vcf=/data/ont_variants.vcf.gz \
    --num_shards=16

R10.4+ chemistry substantially reduces systematic indel errors in homopolymers compared to R9.4. For R9.4 data, consider Clair3 which has dedicated R9.4 models.

Exome/Targeted Sequencing

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/run_deepvariant \
    --model_type=WES \
    --ref=/data/reference.fa \
    --reads=/data/exome.bam \
    --regions=/data/targets.bed \
    --output_vcf=/data/exome_variants.vcf.gz \
    --num_shards=8

The --regions flag is not strictly required but omitting it causes DeepVariant to scan the entire genome, wasting hours on off-target reads with minimal coverage.

Joint Calling with GLnexus

For multi-sample cohorts, use per-sample gVCFs merged with GLnexus:

for bam in *.bam; do
    sample=$(basename $bam .bam)
    docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
        /opt/deepvariant/bin/run_deepvariant \
        --model_type=WGS \
        --ref=/data/reference.fa \
        --reads=/data/$bam \
        --output_vcf=/data/${sample}.vcf.gz \
        --output_gvcf=/data/${sample}.g.vcf.gz \
        --num_shards=16
done

docker run -v "${PWD}:/data" quay.io/mlin/glnexus:v1.4.1 \
    /usr/local/bin/glnexus_cli \
    --config DeepVariantWGS \
    /data/*.g.vcf.gz \
    | bcftools view - -Oz -o cohort.vcf.gz

GLnexus Configuration

Config	Use Case	Notes
DeepVariantWGS	Illumina WGS gVCFs	Default for most WGS cohorts
DeepVariantWES	Illumina exome gVCFs	Tuned for higher-depth, narrower-region calling
DeepVariant_unfiltered	Keep all variant sites	Useful for research exploration; produces more false positives

GLnexus performance is driven by the call confidence distribution across sites, not cohort size per se. A cohort of 100 samples with clean 30x WGS merges faster than 20 samples with noisy 10x data. GLnexus scales well to thousands of samples.

Output Quality Metrics

bcftools stats output.vcf.gz > stats.txt

# Ti/Tv ratio: expect ~2.0-2.1 for WGS, ~2.8-3.3 for WES
bcftools stats output.vcf.gz | grep TSTV

# Filter by quality (QUAL is CNN confidence, GQ is genotype quality)
bcftools view -i 'QUAL>20 && FMT/GQ>20' output.vcf.gz -Oz -o filtered.vcf.gz

Benchmarking Against Truth Set

docker run -v "${PWD}:/data" jmcdani20/hap.py:latest \
    /opt/hap.py/bin/hap.py \
    /data/HG002_GRCh38_truth.vcf.gz \
    /data/deepvariant_output.vcf.gz \
    -r /data/reference.fa \
    -o /data/benchmark \
    --threads 16

Comparison with Other Callers

Benchmark numbers below are approximate, derived from GIAB HG002/HG003/HG004 truth sets on GRCh38. Exact values vary by sample, coverage, and version.

Caller	SNP F1	Indel F1	Speed (30x WGS)	Notes
DeepVariant	~0.999	~0.993	~4-6 hrs CPU, ~1-2 hrs GPU	Highest accuracy; slow without GPU
GATK HC	~0.999	~0.989	~4-8 hrs CPU	Strong ecosystem; joint calling pipeline
Strelka2	~0.998	~0.960	~1-2 hrs CPU	Fastest; no longer actively maintained
Clair3	~0.998	~0.980	~8 hrs (50x ONT)	Strong for long reads; active development

Caveat: DeepVariant models are trained and evaluated heavily on GIAB reference samples. Performance on underrepresented populations or complex structural variant regions may not match published benchmarks. Independent benchmarking on population-matched samples is recommended before clinical deployment.

Resource Requirements

Data Type	RAM	CPU Time	GPU Time	Notes
WGS 30x	64 GB	~4-6 hrs	~1-2 hrs	--num_shards scales make_examples linearly
WES	32 GB	~30 min	~10 min	Much faster due to smaller target region
PacBio HiFi 30x	64 GB	~3-5 hrs	~1-2 hrs	Fewer but longer reads
ONT 50x	64 GB	~6-8 hrs	~2-3 hrs	Higher error rate means more candidate sites

GPU acceleration primarily benefits the call_variants step. For large cohorts, parallelizing across samples on CPU nodes may be more cost-effective than queuing for GPU access.

Complete Workflow Script

#!/bin/bash
set -euo pipefail

BAM=$1
REFERENCE=$2
OUTPUT_PREFIX=$3
MODEL_TYPE=${4:-WGS}
THREADS=${5:-16}

echo "=== DeepVariant: ${MODEL_TYPE} mode ==="

docker run -v "${PWD}:/data" google/deepvariant:1.6.1 \
    /opt/deepvariant/bin/run_deepvariant \
    --model_type=${MODEL_TYPE} \
    --ref=/data/${REFERENCE} \
    --reads=/data/${BAM} \
    --output_vcf=/data/${OUTPUT_PREFIX}.vcf.gz \
    --output_gvcf=/data/${OUTPUT_PREFIX}.g.vcf.gz \
    --intermediate_results_dir=/data/${OUTPUT_PREFIX}_tmp \
    --num_shards=${THREADS}

echo "=== Indexing ==="
bcftools index -t ${OUTPUT_PREFIX}.vcf.gz
bcftools index -t ${OUTPUT_PREFIX}.g.vcf.gz

echo "=== Statistics ==="
bcftools stats ${OUTPUT_PREFIX}.vcf.gz > ${OUTPUT_PREFIX}_stats.txt

echo "=== Complete ==="
echo "VCF: ${OUTPUT_PREFIX}.vcf.gz"
echo "gVCF: ${OUTPUT_PREFIX}.g.vcf.gz"

Related Skills

• variant-calling/gatk-variant-calling - GATK alternative with joint calling ecosystem and VQSR integration
• variant-calling/variant-calling - bcftools calling for quick, lightweight analysis
• variant-calling/filtering-best-practices - Post-calling filtering strategies
• variant-calling/joint-calling - GATK joint genotyping alternative to GLnexus
• long-read-sequencing/clair3-variants - Long-read variant calling alternative, especially for ONT