GATK
Template:DRAFT The Genome Analysis Toolkit (GATK) is a set of bioinformatic tools for analyzing high-throughput sequencing (HTS) and variant call format (VCF) data. The toolkit is well established for germline short variant discovery from whole genome and exome sequencing data (1). It is a leading tool in variant discovery and best practices for genomics research.
Availability and loading module
In all Compute Canada clusters (Graham, Cedar, Beluga), we provide different versions of GATK. To access the version information you can use the module command:
[name@server ~]$ module spider gatk
which will give you some information about GATK and the versions:
gatk/3.7 gatk/3.8 gatk/4.0.0.0 gatk/4.0.8.1 gatk/4.0.12.0 gatk/4.1.0.0 gatk/4.1.2.0
More specific information of any given version can be access with:
[name@server ~]$ module spider gatk/4.1.2.0
As you can see, this module only has nixpkgs/16.09 module as prerequisite
so it can be loaded by:
[name@server ~]$ module load nixpkgs/16.09 gatk/4.1.2.0
Or, given that nixpkgs/16.09 is loaded by default, simply:
[name@server ~]$ module load gatk/4.1.2.0
General usage
The later versions of GATK (>=4.0.0.0) provide a binary wrapper over the java executables (.jar). Loading the GATK modules will automatically set most of the environmental variables you will need to successfully run GATK.
The module spider command also provides you with usage and examples of that wrapper:
Usage
=====
gatk [--java-options "-Xmx4G"] ToolName [GATK args]
Examples
========
gatk --java-options "-Xmx8G" HaplotypeCaller -R reference.fasta -I input.bam -O output.vcf
As you probably notice, there are some arguments to be passed directly to java through the --java-options such as the maximum heap memory (-Xmx8G in the example, reserving 8 Gb of memory for the virtual machine). We recommend that you always use -DGATK_STACKTRACE_ON_USER_EXCEPTION=true since it will give you more information in case the program fails. This information can help you or us (in case you needed support) to solve the issue. Note that all options passed to --java-options have to be within quotation marks.
Earlier versions than GATK 4
Earlier versions of GATK do not have the gatk command. Instead, one has to call the jar file:
java -jar GenomeAnalysisTK.jar PROGRAM OPTIONS
However, GenomeAnalysisTK.jar must be in PATH. In Compute Canada systems, the environmental variables $EBROOTPICARD for Picard (included in GATK >= 4) and $EBROOTGATK for GATK contain the path to the jar file, so the appropriate way to call GATK <= 3 is:
module load gatk/3.8 java -jar java -jar $EBROOTGATK/GenomeAnalysisTK.jar PROGRAM OPTIONS
You can find the specific usage of GATK <= 3 in the GATK3 guide.
Frequently asked questions
How do I add a read group (RG) tag in my bam file?
Assuming that the read group you want to add is called tag to the file input bam, you can use the GATK/PICARD command AddOrReplaceReadGroups:
gatk AddOrReplaceReadGroups \
-I input.bam \
-O output.bam \
--RGLB tag \
--RGPL ILLUMINA
--RGPU tag \
--RGSM tag \
--SORT_ORDER 'coordinate' \
--CREATE_INDEX true
This assumes that your input file is sorted by coordinates and will generate an index along with the annotated output (--CREATE_INDEX true)
How do I deal with java.lang.OutOfMemoryError: Java heap space
Oftentimes the subprograms of GATK require more memory to process your files. If you were not using the -Xms command, add it to the --java-options. For example, let's imagine that you run the following command:
gatk MarkDuplicates \
-I input.bam \
-O marked_duplicates.bam \
-M marked_dup_metrics.txt
But it gives you the java.lang.OutOfMemoryError: Java heap space error. Try:
gatk MarkDuplicates \
--java-options "-Xmx8G DGATK_STACKTRACE_ON_USER_EXCEPTION=true"
-I input.bam \
-O marked_duplicates.bam \
-M marked_dup_metrics.txt
If it fails again, keep increasing the memory until you find the required memory for your particular data set. If you are using any of our systems, remember to request enough memory for this.
If you are interested in knowing more about java heap space, you can start here.
Increasing the heap memory does not fix the java.lang.OutOfMemoryError: Java heap space
There are cases in which the memory issue cannot be fixed with increasing the heap memory. This often happens with non-model organisms, and you are using too many scaffolds in your reference. In this case it is recommended to remove small scaffolds and create subsets of your reference. This implies that you have to map multiple times and run the pipelines in each of the subsets. This approach does not work in all pipelines so review your results carefully. GATK is designed with the human genome in mind, and therefore other organism will require adjustment in many parameters and pipelines.
Using more resources than asked for
Sometimes GATK/JAVA applications will use more memory or cpus/threads than the ones requested. This is often generated by the JAVA garbage collection. To add control for this, you can add -XX:ConcGCThreads=1 to the --java-options argument.
FAQ on GATK
You can find GATK's FAQ's in their website.