> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/clara/parabricks/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/clara/parabricks/_mcp/server.

# pangenome_aware_deepvariant

Run a GPU-accelerated Pangenome-aware DeepVariant algorithm.

Refer to the [pangenome\_aware\_deepvariant Reference](#options) section for a detailed listing of all available options.

## What is Pangenome-aware DeepVariant?

Pangenome-aware DeepVariant is an enhanced version of Google's DeepVariant that leverages
pangenome reference graphs (GBZ files) to improve variant calling accuracy, particularly
in complex and highly variable genomic regions. Traditional variant calling pipelines use a
single linear reference genome, which can miss variants in regions that differ significantly
from the reference. Pangenome-aware DeepVariant uses pangenome graphs that represent multiple
haplotypes and structural variations, enabling more accurate variant detection in diverse
populations. Like DeepVariant, Pangenome-aware Deepvariant generates pileup images and uses a
CNN to infer genotypes. However, unlike DeepVariant, pileup images are generated for both the
input reads and the pangenome haplotypes at potential variant positions. This allows directly
using a pangenome for identifying true variants.

## Why Pangenome-aware DeepVariant?

Linear genome references have been the standard for reference-based genomic analysis. However,
linear references can introduce reference bias where the reference geneome is significantly
different from the sample under study. Using a pangenome reference is one way to address this issue,
since it includes diverse, non-redundant DNA sequences from multiple individuals. Pangenome-aware
Deepvariant leverages the pangenome reference to outperform linear-reference-based DeepVariant
by upto 25.5% across various short-read sequencing platforms and read mappers. Researchers from
Google have also shown that Element reads with pangenome-aware DeepVariant can achieve 23.6% more
accurate variant calling performance compared to existing methods.

## Quick Start

```sh
# This command assumes all the inputs are in the current working directory and all the outputs go to the same place.
docker run --rm --gpus all --volume $(pwd):/workdir --volume $(pwd):/outputdir \
    --workdir /workdir \
    nvcr.io/nvidia/clara/clara-parabricks:4.7.1-1 \
    pbrun pangenome_aware_deepvariant \
    --ref /workdir/${REFERENCE_FILE} \
    --pangenome /workdir/${GBZ_FILE} \
    --in-bam /workdir/${INPUT_BAM} \
    --out-variants /outputdir/${OUTPUT_VCF}
```

## Compatible Google Pangenome-aware DeepVariant Command

The command below shows the equivalent Google pangenome-aware DeepVariant command.
Note that the Parabricks version provides the same accuracy with significant GPU acceleration.

```sh
sudo docker run \
--volume <INPUT_DIR>:/input \
--volume <OUTPUT_DIR>:/output \
--shm-size 12gb \
google/pangenome_aware_deepvariant-1.9.0 \
/opt/deepvariant/bin/run_pangenome_aware_deepvariant \
--model_type WGS \
--ref /input/${REFERENCE_FILE} \
--reads /input/${INPUT_BAM} \
--pangenome /input/${GBZ_FILE} \
--output_vcf /output/${OUTPUT_VCF} \
--num_shards $(nproc) \
--make_examples_extra_args "ws_use_window_selector_model=true"
```

## Source of Mismatches

While Parabricks Pangenome-aware DeepVariant does not lose any accuracy in functionality when compared with Google's
Pangenome-aware DeepVariant, there are several reasons that can result in different output files:

* **CNN Inference**

Google DeepVariant uses a CNN (convolutional neural network) to predict the possibilities of each variant candidate.
The model is trained, and does inference through, Keras. In Parabricks DeepVariant we convert this Keras model to an
engine file with TensorRT to perform accelerated deep learning inferencing on NVIDIA GPUs. Because of the optimizations
from TensorRT, there is a small difference in the final possibility scores after inferencing (10^-5), which could cause
a few different variants in the final VCF output. Based on current observations, the mismatches only happen to
RefCalls with a quality score of zero.

* **Read Sorting Differences**

The Google Pangenome-aware DeepVariant implementation uses `sort` instead of `stable_sort` for sorting reads
based on position, fragment\_name, and read\_number. Unfortunately, when the `keep-supplementary-alignments` option
is enabled, it is possible to have duplicate reads which are sorted non-deterministically by `std::sort`. The
Parabricks implementation uses `stable_sort` to resolve this. To obtain identical results with Google's implementation,
users are recommended to update the `std::sort` in `BuildPileupForOneSample pileup_image_native.cc` to
`std::stable_sort`.

* **GBZ Reader Caching Mechanism**

Google Pangenome-aware DeepVariant's GBZ reader includes a fast path to speed up queries to the pangenome graph.
This fast path introduces non-determinism in the query operation to the pangenome where the result returned by
the operation depends on the order of the previous queries to the pangenome. Since, Parabricks relies on multi-threading
to achieve high performance, we disable the fast path in the Parabricks implementation. To obtain identical results using
Google's implementation, users should comment out the call to `updateCache` in the `GbzReader::Query()`
function in `deepvariant/third_party/nucleus/io/gbz_reader.cc`. Also, the check for whether the requested range is cached
or not should be disabled (in the same function). Note that disabling the cache can slow down Google Deepvariant
significantly and is not recommended in general. We suggest this approach only for the purposes of comparing output accuracy.

## Options