pangenome_aware_deepvariant

Run a GPU-accelerated Pangenome-aware DeepVariant algorithm.

Refer to the pangenome_aware_deepvariant Reference 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

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

Roche SBX Mode

Use --sbx when calling variants from Roche SBX-D or SBX-Fast BAMs. Parabricks selects the SBX-trained pangenome-aware model (deepvariant_pangenome_aware_sbx.eng) for the current GPU architecture unless --pb-model-file overrides it, and applies make-examples and postprocess defaults aligned with the Google Roche SBX case study.

When --sbx is set, the following defaults apply:

• Pileup image width of 301 base pairs.
• alt_aligned_pileup=single_row pileup layout.
• multiallelic_mode=product for multiallelic genotype resolution.
• vsc_min_fraction_indels=0.08 and ws_min_base_quality=25.
• --create-complex-alleles and --enable-strict-insertion-filter.
• Insert-size pileup channel disabled by default (pass --channel-insert-size to enable it).

Roche SBX Quick Start

1
# This command assumes all the inputs are in the current working directory and all the outputs go to the same place.
2
docker run --rm --gpus all --volume $(pwd):/workdir --volume $(pwd):/outputdir \
3
    --workdir /workdir \
4
    nvcr.io/nvidia/clara/clara-parabricks:4.7.1-1 \
5
    pbrun pangenome_aware_deepvariant \
6
    --ref /workdir/${REFERENCE_FILE} \
7
    --pangenome /workdir/${GBZ_FILE} \
8
    --in-bam /workdir/HG002.roche_sbx.chr20.bam \
9
    --out-variants /outputdir/HG002.chr20.output.vcf.gz \
10
    --sbx \
11
    -L chr20

Public case-study inputs (reference, GBZ, BAM, and GIAB truth sets) are available from the Google Roche SBX case study.

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.

1
sudo docker run \
2
--volume <INPUT_DIR>:/input \
3
--volume <OUTPUT_DIR>:/output \
4
--shm-size 12gb \
5
google/pangenome_aware_deepvariant-1.9.0 \
6
/opt/deepvariant/bin/run_pangenome_aware_deepvariant \
7
--model_type WGS \
8
--ref /input/${REFERENCE_FILE} \
9
--reads /input/${INPUT_BAM} \
10
--pangenome /input/${GBZ_FILE} \
11
--output_vcf /output/${OUTPUT_VCF} \
12
--num_shards $(nproc) \
13
--make_examples_extra_args "ws_use_window_selector_model=true"

Compatible Google Pangenome-aware DeepVariant Command (Roche SBX)

The command below shows the equivalent Google pangenome-aware DeepVariant Roche SBX command from the Roche SBX case study. Parabricks applies the same SBX defaults when --sbx is set.

1
sudo docker run \
2
--volume <INPUT_DIR>:/input \
3
--volume <OUTPUT_DIR>:/output \
4
--volume <REFERENCE_DIR>:/reference \
5
--volume <MODEL_DIR>:/model \
6
--shm-size 12gb \
7
google/deepvariant:pangenome_aware_deepvariant-sbx \
8
/opt/deepvariant/bin/run_pangenome_aware_deepvariant \
9
--model_type WGS \
10
--ref /reference/${REFERENCE_FILE} \
11
--reads /input/HG002.roche_sbx.chr20.bam \
12
--pangenome /input/${GBZ_FILE} \
13
--output_vcf /output/HG002.chr20.output.vcf.gz \
14
--num_shards $(nproc) \
15
--regions chr20 \
16
--customized_model /model/model.ckpt \
17
--make_examples_extra_args="alt_aligned_pileup=single_row,create_complex_alleles=true,enable_strict_insertion_filter=true,keep_legacy_allele_counter_behavior=true,keep_only_window_spanning_haplotypes=true,keep_supplementary_alignments=true,min_mapping_quality=0,normalize_reads=true,pileup_image_height_pangenome=100,pileup_image_height_reads=100,pileup_image_width=301,sort_by_haplotypes=true,trim_reads_for_pileup=true,vsc_min_fraction_indels=0.08,ws_min_base_quality=25" \
18
--postprocess_variants_extra_args="multiallelic_mode=product"

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