DeepVariant: a pileup-image CNN variant caller for diploid germline data
DeepVariant is an analysis pipeline that uses a deep neural network to call genetic variants from next-generation DNA sequencing data.
At a glance
- What is it?
- DeepVariant turns aligned reads into pileup image tensors and classifies them with a convolutional neural network, emitting VCF or gVCF. It is a diploid germline caller with human-trained models, and both of those boundaries matter more than the neural network does.
- Who is it for?
- Adopt DeepVariant if you have diploid germline sequencing data, aligned BAM or CRAM, and a reference whose ploidy is two, and if you accept that the bundled models were trained on human data. Do not adopt it for somatic calling (the README points to the separate DeepSomatic repository), for polyploid or copy-number-variable organisms, or for non-human samples without reading the non-human variant-calling blog post first.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 6 months ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The calling problem DeepVariant reframes as image classification
Conventional germline callers decide a genotype by evaluating candidate alleles against a statistical model of sequencing error, mapping quality and local haplotype structure. DeepVariant replaces the hand-built model with a learned one. Its README describes the pipeline as taking aligned reads in BAM or CRAM, producing pileup image tensors, classifying each tensor with a convolutional neural network, and reporting results as VCF or gVCF. The intended user is a genomics engineer or analyst who already has alignments and a reference and wants genotypes out, not someone building a caller from scratch. The scope is narrow by design: the README states that DeepVariant supports germline variant-calling in diploid organisms, and that it currently supports variant calling only on organisms where ploidy or copy number is two, because the genotypes it emits are hom-alt, het and hom-ref. That is a hard boundary, not a tuning knob.
Reads become images: the make_examples and call_variants split
The architecture visible in the material is a two-stage split. One stage, make_examples, converts aligned reads into pileup image tensors. The other, call_variants, runs the CNN over those tensors. The Docker example exposes this split through flags: --num_shards controls how many cores make_examples uses, and the README comments that this will use all your cores, with a note to change it. There is also an experimental mode, described in the Fast Pipeline case study, that runs make_examples on CPU and call_variants on GPU at the same time, which tells you the two stages are separable rather than fused. A --disable_small_model flag disables the small model from the make_examples stage. That flag name is the only hint in the supplied material that more than one model participates, so treat any claim about how the small model differs from the main one as unverified here. The output side is equally explicit: --output_vcf and --output_gvcf are separate paths, meaning a single run writes both files unless you omit one.
Running it: the documented Docker command and its flags
The README recommends the Docker solution and gives a concrete command. It sets BIN_VERSION="1.10.0", mounts an input and an output directory, and invokes /opt/deepvariant/bin/run_deepvariant inside the google/deepvariant image. The required flags in that example are --model_type, --ref, --reads, --output_vcf and --output_gvcf. The README states that --model_type must be exactly one of WGS, WES, PACBIO, ONT_R104 or HYBRID_PACBIO_ILLUMINA. Optional flags in the same block include --vcf_stats_report (default false, writes an HTML statistics report), --disable_small_model (default false), --logging_dir (saves per-stage logs separately), --haploid_contigs and --par_regions_bed, and --dry_run (default false, prints commands without executing them). To list every flag the README says to run the image with no arguments. For GPU use or for Singularity instead of Docker, the README redirects to the Quick Start document rather than repeating instructions. Two details in the --haploid_contigs description are worth reading twice: it re-genotypes heterozygous variants on the named contigs as the most likely of reference or homozygous alternate, and the README says it should be set to "chrX,chrY" for GRCh38 and "X,Y" for GRCh37 on an XY sample, and should not be used at all for an XX sample. The PAR bed files are downloadable from the URLs the README lists, one for GRCh38 and one for GRCh37.
Diploid-only genotypes and human-only training are the real constraints
Two limitations come straight from the README and neither is a bug. First, the genotype set is hom-alt, het and hom-ref, which is why ploidy must be two. A triploid sample, a haploid bacterial genome, or a sample with copy-number variation in the region of interest falls outside what the output vocabulary can express. Second, the models included with DeepVariant are only trained on human data. For other organisms the README points to a blog post on non-human variant-calling that discusses pitfalls and how to handle them, and it does not promise that the bundled models transfer. There is a third limitation that is easy to miss: the README notes that DeepVariant has been adapted for somatic calling, but that work lives in the separate DeepSomatic repository, so a tumor-normal pair is not a DeepVariant job. The --haploid_contigs flag is a partial workaround for sex chromosomes, not a general escape from the diploid assumption, and it requires the PAR bed to avoid adjusting genotypes inside the pseudoautosomal regions.
DeepTrio and the multi-sample path
DeepTrio is built on top of DeepVariant and predicts variants in trios or duos, using neural networks to combine information across family members rather than calling each sample in isolation. The README states that DeepTrio supports germline calling in diploid organisms for Illumina whole genome or whole exome, and for PacBio HiFi, and that all DeepTrio models were trained on human data. It can run with only two samples, child plus one parent. One implementation detail matters operationally: the external tool GLnexus is used to merge output VCFs. That means a trio run introduces a dependency outside the DeepVariant image, and the README points to a separate best-practices document for multi-sample calling. If you are calling many unrelated samples and merging afterward, the same trio-merge case study is the document the README offers, but the merging tool is GLnexus, not something inside DeepVariant.
Where a haplotype-based caller like GATK still fits better
The natural comparison is GATK HaplotypeCaller, which assembles candidate haplotypes locally and genotypes them against a statistical model rather than classifying pileup images. The difference in approach has practical consequences. A haplotype-based caller's error model is inspectable and adjustable through documented parameters; DeepVariant's decision boundary lives in trained weights, so when it calls something surprising you cannot read the reason out of a parameter table. That cuts the other way too: there is no local reassembly step to get wrong, and no hand-tuned thresholds to retune per sequencing chemistry, provided a matching --model_type exists. The supplied material lists case studies for Illumina, Element, PacBio HiFi, ONT R10.4.1 simplex, Complete Genomics T7 and G400, Roche SBX, pangenome-mapped data via vg, RNA data, and hybrid PacBio HiFi plus Illumina, which suggests the model coverage is broad. It does not list a somatic model, and it does not list a polyploid model. If your project is somatic or non-diploid, the comparison is not DeepVariant versus GATK; it is a different tool versus GATK.
Licence, releases and what a version bump costs you
DeepVariant is BSD-3-Clause, a permissive licence that generally allows modification and redistribution provided the copyright notice and disclaimer are retained. That is a statement about the licence text, not legal advice; if you plan to redistribute a modified pipeline, read the licence and your organisation's policy. On maintenance, the release history shows v1.9.0 in May 2025, a v1.10.0-beta in October 2025, and v1.10.0 in March 2026, with the default branch named r1.10. The upgrade cost is mostly in the model, not the code: --model_type strings are tied to the release, and the README's Docker example pins BIN_VERSION="1.10.0" explicitly rather than using latest, which is the right pattern to copy. The practical upgrade question is whether a new release changes the model for your data type, because that changes your calls, and the supplied material does not include a changelog describing model changes between 1.9.0 and 1.10.0. Verify that against the release notes before rolling a new image into a production pipeline.
Editorial conclusion
Adopt DeepVariant if you have diploid germline sequencing data, aligned BAM or CRAM, and a reference whose ploidy is two, and if you accept that the bundled models were trained on human data. Do not adopt it for somatic calling (the README points to the separate DeepSomatic repository), for polyploid or copy-number-variable organisms, or for non-human samples without reading the non-human variant-calling blog post first. Before committing, verify three things: that your read technology has a matching --model_type, since the README lists WGS, WES, PACBIO, ONT_R104 and HYBRID_PACBIO_ILLUMINA as the supported strings; that you have a PAR bed file if you intend to set --haploid_contigs for an XY sample; and that your output directory has room for both the VCF and the gVCF, because the documented command writes both.
Community notes