> 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.

# giraffe (vg giraffe + GATK)

Note that the Parabricks GPU-accelerated Giraffe tool is currently in beta.

Generate BAM output given one or a pair of FASTQ files using the pangenome
aligner VG Giraffe \[^note] \[^note].

Refer to the [giraffe Reference](#options) section for a detailed listing of all available options.

## What is giraffe?

VG Giraffe is a short-read mapping tool developed by Dr. Benedict Paten's lab at the
University of California, Santa Cruz (UCSC). This innovative tool can align reads to a graph
representation of multiple reference genomes, enhancing the quality of downstream
analyses. By accurately mapping reads to thousands of genomes simultaneously,
VG Giraffe offers a substantial improvement over traditional single-reference aligners.

## Why giraffe?

By utilizing a graph-based approach, VG Giraffe can more effectively handle genetic
diversity and structural variations across populations. Here are three key benefits of
using VG Giraffe:

1. Improved accuracy: VG Giraffe achieves higher precision and recall in read mapping
   compared to linear genome aligners, especially when dealing with complex genomic
   regions or populations with significant genetic diversity.
2. Reduced reference bias (or mapping bias): By incorporating multiple haplotypes and
   known variants into its graph structure, VG Giraffe minimizes the reference bias
   inherent in traditional linear genome aligners. This leads to more comprehensive
   and unbiased characterization of genetic variation, especially for samples that
   diverge significantly from the standard reference genome.
3. Faster performance: Despite working with more complex graph structures, VG Giraffe
   is significantly faster than its predecessor VG Map and comparable in speed to popular
   linear genome mappers. It can map sequencing reads to thousands of human genomes
   at a speed similar to methods that map to a single reference genome.

## How Should I Use giraffe in Parabricks?

VG Giraffe can be used within Parabricks, a software suite designed for accelerated
secondary analysis in genomics. Our wrapper (`pbrun giraffe`) will run our GPU-accelerated
VG Giraffe and sort the output BAM by coordinate.

While users can build custom reference graphs for VG Giraffe using the VG Autoindex
tool, pre-built pangenome graphs are also available. Dr. Paten's lab and the Human
Pangenome Consortium have made these resources publicly accessible, allowing
researchers to leverage high-quality, ready-to-use pangenome graphs for their analyses ([HPRC data](https://humanpangenome.org/data/)).

## Generating Required Index Files

The index files `.gbz`, `.dist`, `.min`, and `.zipcodes` are required to run Giraffe.
A reference paths file is also needed to define the set of paths used for BAM output.

The index files can be generated from a GBZ graph using `vg autoindex`. The following
example uses the HPRC v1.1 Minigraph-Cactus pangenome graph aligned to GRCh38:

```sh
# Download GBZ
# https://s3-us-west-2.amazonaws.com/human-pangenomics/pangenomes/freeze/freeze1/minigraph-cactus/hprc-v1.1-mc-grch38/hprc-v1.1-mc-grch38.d9.gbz
aws s3 cp \
    s3://human-pangenomics/pangenomes/freeze/freeze1/minigraph-cactus/hprc-v1.1-mc-grch38/hprc-v1.1-mc-grch38.d9.gbz \
    . \
    --no-sign-request

# Extract index files from GBZ
docker run --rm --volume $(pwd):/workdir \
    --workdir /workdir \
    --user $(id -u):$(id -g) \
    quay.io/vgteam/vg:v1.70.0 \
    vg autoindex \
        -p hprc-v1.1-mc-grch38.d9.autoindex.1.70 \
        -G hprc-v1.1-mc-grch38.d9.gbz \
        -w giraffe

# Extract paths from GBZ
docker run --rm \
    --user $(id -u):$(id -g) \
    --volume $(pwd):/workdir \
    --workdir /workdir \
    quay.io/vgteam/vg:v1.70.0 \
    vg paths -x hprc-v1.1-mc-grch38.d9.gbz \
    -L --paths-by GRCh38 > hprc-v1.1-mc-grch38.d9.paths

# As per best practices, remove decoys, unplaced/unlocalized contigs,
# and other non-primary paths unnecessary for pangenome graph alignment.
grep -v _decoy hprc-v1.1-mc-grch38.d9.paths \
    | grep -v _random \
    | grep -v chrUn_ \
    | grep -v chrEBV \
    | grep -v chrM \
    | grep -v chain_ > hprc-v1.1-mc-grch38.d9.paths.sub
```

## Quick Start

Before running giraffe, ensure you have generated the required index files. Refer to the
[index generation](/tool-reference/tools/giraffe-vg-giraffe-gatk) section above for instructions.

```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 giraffe --read-group "sample_rg1" \
    --sample "sample-name" --read-group-library "library" \
    --read-group-platform "platform" --read-group-pu "pu" \
    --gbz-name /workdir/hprc-v1.1-mc-grch38.d9.gbz \
    --dist-name /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.dist \
    --minimizer-name /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.shortread.withzip.min \
    --zipcodes-name /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.shortread.zipcodes \
    --ref-paths /workdir/hprc-v1.1-mc-grch38.d9.paths.sub \
    --in-fq /workdir/${INPUT_FASTQ_1} /workdir/${INPUT_FASTQ_2} \
    --out-bam /outputdir/${OUTPUT_BAM}
```

## System Requirements and Useful Options for Performance

To ensure optimal performance with VG Giraffe, consider the following system
requirements based on your GPU configuration:

* A 2 GPU system should have at least 100GB CPU RAM and at least 32 CPU threads.

* A 4 GPU system should have at least 200GB CPU RAM and at least 64 CPU threads.

* For GPUs with less than 22 GB of device memory, use `--low-memory`.

## Auto Mode

By default, `--nstreams` is set to `auto`, which enables auto mode. In this
mode, Giraffe automatically configures the number of CUDA streams, batch size, and GPU
acceleration options based on the available GPU device memory. Auto mode is designed to
provide sensible defaults, but may still require further optimization for each specific
system. The following table summarizes the auto mode configuration based on GPU
device memory:

| GPU Memory | Streams        | Batch Size | minimizers-gpu (SE only) |
| ---------- | -------------- | ---------- | ------------------------ |
| \< 22 GB   | 1 (low-memory) | 5000       | No                       |
| 22-32 GB   | 1              | 8000       | No                       |
| 32-40 GB   | 2              | 10000      | No                       |
| 40-80 GB   | 3              | 10000      | No                       |
| 80-120 GB  | 4              | 10000      | Yes                      |
| >= 120 GB  | 5              | 10000      | Yes                      |

Auto mode also takes host memory into account. If host memory is insufficient,
`--minimizers-gpu` may be disabled, and batch size and work queue capacity may
be reduced.

Note that `--minimizers-gpu` is only enabled for single-end (SE) reads.
For paired-end (PE) reads, the number of streams and batch size are configured as
shown above, but `--minimizers-gpu` is always disabled.

For best performance, auto mode can be overridden by explicitly setting `--nstreams`
and other options. The following configurations are, for example, recommended for L4, H100
and RTX PRO 6000 Blackwell Server Edition GPUs:

* **L4 (16 GB):** `--batch-size 5000 --nstreams 2`

* **H100 (80 GB):** `--nstreams 5 --num-cpu-threads-per-gpu 24 --minimizers-gpu`

* **RTX PRO 6000 Blackwell Server Edition (96 GB):** `--nstreams 4 --num-cpu-threads-per-gpu 24 --minimizers-gpu`

Note: While a fixed base memory allocation exists per device, the number of streams
and batch size are the primary factors affecting total device memory consumption.

## Using Giraffe in Variant Calling Workflows

To use Giraffe-aligned BAM files for variant calling, you need to extract the
appropriate reference file from the Giraffe index files. Run the following
commands from the directory containing the Giraffe index files:

```sh
# Extract the sequences corresponding to the list of paths to a FASTA file
docker run --rm \
    --user $(id -u):$(id -g) \
    --volume $(pwd):/workdir \
    --workdir /workdir \
    quay.io/vgteam/vg:v1.70.0 \
    vg paths -x hprc-v1.1-mc-grch38.d9.gbz \
        -p hprc-v1.1-mc-grch38.d9.paths.sub \
        -F > hprc-v1.1-mc-grch38.d9.fa

# Index the FASTA file
docker run --rm \
    --user $(id -u):$(id -g) \
    --volume $(pwd):/workdir \
    --workdir /workdir \
    quay.io/biocontainers/samtools:1.17--hd87286a_2 \
    samtools faidx hprc-v1.1-mc-grch38.d9.fa
```

These commands will generate a FASTA file (`hprc-v1.1-mc-grch38.d9.fa`),
and the corresponding index (`hprc-v1.1-mc-grch38.d9.fa.fai`), that can
be used as the reference for variant calling. Note that these files can be also used
for BQSR ([bqsr](/tool-reference/tools/bqsr)). We can now run Giraffe to obtain the aligned BAM as follows:

```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 giraffe --read-group "sample_rg1" \
    --sample "sample-name" --read-group-library "library" \
    --read-group-platform "platform" --read-group-pu "pu" \
    --gbz-name /workdir/hprc-v1.1-mc-grch38.d9.gbz \
    --dist-name /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.dist \
    --minimizer-name /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.shortread.withzip.min \
    --zipcodes-name /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.shortread.zipcodes \
    --ref-paths /workdir/hprc-v1.1-mc-grch38.d9.paths.sub \
    --in-fq /workdir/${INPUT_FASTQ_1} /workdir/${INPUT_FASTQ_2} \
    --out-bam /outputdir/${OUTPUT_BAM}
```

Once you have the Giraffe-aligned BAM file and the extracted reference FASTA, you can
proceed with variant calling using HaplotypeCaller, Deepvariant, Pangenome\_aware\_deepvariant,
or the end-to-end [pangenome\_germline](/tool-reference/tools/pangenome-germline) pipeline.

```sh
# Haplotype Caller
# 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 haplotypecaller \
    --ref /workdir/hprc-v1.1-mc-grch38.d9.fa \
    --in-bam /workdir/${INPUT_BAM} \
    --in-recal-file /workdir/${INPUT_RECAL_FILE} \
    --out-variants /outputdir/${OUTPUT_VCF}

# Deepvariant
# 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 deepvariant \
    --ref /workdir/hprc-v1.1-mc-grch38.d9.fa \
    --in-bam /workdir/${INPUT_BAM} \
    --out-variants /outputdir/${OUTPUT_VCF}

# Pangenome_aware_deepvariant
# 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/hprc-v1.1-mc-grch38.d9.fa \
    --pangenome /workdir/hprc-v1.1-mc-grch38.d9.gbz \
    --in-bam /workdir/${INPUT_BAM} \
    --out-variants /outputdir/${OUTPUT_VCF}
```

For more detailed instructions on variant calling, refer to the tool-specific
documentation ([haplotypecaller](/tool-reference/tools/haplotypecaller), [deepvariant](/tool-reference/tools/deepvariant), [pangenome\_aware\_deepvariant](/tool-reference/tools/pangenome-aware-deepvariant),
[pangenome\_germline](/tool-reference/tools/pangenome-germline)).

## Using Giraffe with Haplotype Sampling

Giraffe's haplotype sampling functionality, activated using arguments
`--haplotype-name` and `--kff-name`, was introduced to significantly enhance
alignment accuracy by tailoring the reference graph to the specific genetic profile
of a sample. This process begins by analyzing sequencing reads with a kmer counter to
identify patterns of kmer presence and frequency. Using this information, Giraffe
sub-samples the GBWT (using the original `.hapl` and `.gbz` files)
to select haplotypes that best represent the sample, creating a customized graph.
From this tailored graph, Giraffe also generates new index files
(`.dist`, `.min`, and `.zipcodes`) that are optimized for the sample to be analyzed.

These steps can be performed using the baseline VG container for graph customization
and index generation, followed by Parabricks' accelerated Giraffe for
high-performance alignment, as demonstrated below.

The required `.hapl` and `.gbz` files can be downloaded as follows:

```sh
aws s3 cp \
    s3://human-pangenomics/pangenomes/freeze/freeze1/minigraph-cactus/hprc-v1.1-mc-grch38/hprc-v1.1-mc-grch38.gbz \
    . \
    --no-sign-request

aws s3 cp \
    s3://human-pangenomics/pangenomes/freeze/freeze1/minigraph-cactus/hprc-v1.1-mc-grch38/hprc-v1.1-mc-grch38.hapl \
    . \
    --no-sign-request
```

You will also need to extract and filter reference paths for this graph:

```sh
docker run --rm \
    --user $(id -u):$(id -g) \
    --volume $(pwd):/workdir \
    --workdir /workdir \
    quay.io/vgteam/vg:v1.70.0 \
    vg paths -x hprc-v1.1-mc-grch38.gbz \
    -L --paths-by GRCh38 > hprc-v1.1-mc-grch38.paths

grep -v _decoy hprc-v1.1-mc-grch38.paths \
    | grep -v _random \
    | grep -v chrUn_ \
    | grep -v chrEBV \
    | grep -v chrM \
    | grep -v chain_ > hprc-v1.1-mc-grch38.paths.sub
```

```sh
# Run KMC on the input reads to obtain the .kff file
mkdir kmc_tmp_dir
cat > input.fq.paths <<- EOM
${INPUT_FASTQ_1}
${INPUT_FASTQ_2}
EOM

docker run --rm --volume $(pwd):/workdir \
    --workdir /workdir \
    quay.io/biocontainers/kmc:3.2.4--haf24da9_3 \
    kmc \
        -k29 \
        -m128 \
        -okff \
        -t64 \
        @input.fq.paths \
        input.fq.distr kmc_tmp_dir

# Compute the sampled .gbz file using the baseline container
docker run --rm --volume $(pwd):/workdir \
    --workdir /workdir \
    quay.io/vgteam/vg:v1.70.0 \
    vg haplotypes \
        -v 2 -t 64 \
        --include-reference \
        --diploid-sampling \
        -i hprc-v1.1-mc-grch38.hapl \
        -k input.fq.distr.kff \
        -g hprc-v1.1-mc-grch38.sampled.gbz \
        hprc-v1.1-mc-grch38.gbz

# Generate index files from the sampled graph using autoindex
docker run --rm --volume $(pwd):/workdir \
    --workdir /workdir \
    --user $(id -u):$(id -g) \
    quay.io/vgteam/vg:v1.70.0 \
    vg autoindex \
        -p hprc-v1.1-mc-grch38.sampled.autoindex.1.70 \
        -G hprc-v1.1-mc-grch38.sampled.gbz \
        -w giraffe

# Align the reads to the sampled graph using Parabricks Giraffe
# 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 giraffe --read-group "sample_rg1" \
    --sample "sample-name" --read-group-library "library" \
    --read-group-platform "platform" --read-group-pu "pu" \
    --gbz-name hprc-v1.1-mc-grch38.sampled.gbz \
    --dist-name hprc-v1.1-mc-grch38.sampled.autoindex.1.70.dist \
    --minimizer-name hprc-v1.1-mc-grch38.sampled.autoindex.1.70.shortread.withzip.min \
    --zipcodes-name hprc-v1.1-mc-grch38.sampled.autoindex.1.70.shortread.zipcodes \
    --ref-paths hprc-v1.1-mc-grch38.paths.sub \
    --in-fq ${INPUT_FASTQ_1} ${INPUT_FASTQ_2} \
    --out-bam /outputdir/${OUTPUT_BAM}
```

## Compatible CPU-based vg giraffe and GATK4 Commands

The commands below are the [vg-1.70.0](https://github.com/vgteam/vg/releases/tag/v1.70.0)
and GATK4 counterpart of the Parabricks command above.
The output from these commands will be identical to the output from the above command. Refer to the
[Output Comparison](/about-parabricks/comparison-with-baseline-tools) page for comparing the results.

The index files used below are generated in the
[index generation](/tool-reference/tools/giraffe-vg-giraffe-gatk) section.

```sh
# Run giraffe and pipe the output to create a sorted BAM.
$ vg giraffe \
    -t 16 \
    -Z /workdir/hprc-v1.1-mc-grch38.d9.gbz \
    -d /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.dist \
    -m /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.shortread.withzip.min \
    -z /workdir/hprc-v1.1-mc-grch38.d9.autoindex.1.70.shortread.zipcodes \
    --ref-paths /workdir/hprc-v1.1-mc-grch38.d9.paths.sub \
    -f /workdir/${INPUT_FASTQ_1} \
    -f /workdir/${INPUT_FASTQ_2} \
    --output-format bam | \
  gatk SortSam \
    --java-options -Xmx30g \
    --MAX_RECORDS_IN_RAM 5000000 \
    -I /dev/stdin \
    -O cpu.bam \
    --SORT_ORDER coordinate

# Mark duplicates.
$ gatk MarkDuplicates \
    -I cpu.bam \
    -O cpu.markdup.bam \
    -M metrics.txt
```

## Source of Mismatches

When comparing output with the CPU counterpart the following can be sources of small
differences.

* **Baseline VG Container**

  * **Single-end (SE) reads:** Parabricks matches the baseline
    `quay.io/vgteam/vg:v1.70.0` container exactly. No modifications to the
    baseline container are needed.

  * **Paired-end (PE) reads:** A bug fix for fragment distance recording is required
    in the baseline container. You need to cherry-pick the fix and rebuild the
    container as follows:

```sh
# Clone the repo (full history needed for cherry-pick)
git clone https://github.com/vgteam/vg.git
cd vg

# Checkout v1.70.0 tag and create a patch branch
git checkout v1.70.0
git checkout -b v1.70.0-fragment-fix

# Initialize submodules (required for build)
git submodule update --init --recursive

# Cherry-pick the bug fix
git cherry-pick d99a2a4d4b16500ec8dd4bd9d9d93c7fbec26ed1

# Build the Docker container
make version
docker build --build-arg THREADS=64 -t vg:v1.70.0-fragment-fix .
```

* **Unmapped reads**

  * Parabricks `giraffe` sorts unmapped reads slightly differently than baseline GATK SortSam.
    Unmapped reads can be filtered with samtools by running `samtools view -F 4`.

## Options

* Jouni Sirén et. al., Pangenomics enables genotyping of known structural variants in 5202 diverse genomes. Science 374, abg 8871 (2021). DOI: [10.1126/science.abg8871](https://doi.org/10.1126/science.abg8871)
* Baseline VG Giraffe: [https://github.com/vgteam/vg](https://github.com/vgteam/vg)