GATK

From CC Doc
Jump to: navigation, search
This page is a translated version of the page GATK and the translation is 39% complete.

Outdated translations are marked like this.
Other languages:
English • ‎français


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


Vous recevrez de l'information sur GATK et les 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

Pour plus d'information sur une version particulière, utilisez

  [name@server ~]$ module spider gatk/4.1.2.0


Comme vous pouvez voir, seul le module nixpkgs/16.09 est prérequis; chargez-le avec

  [name@server ~]$ module load nixpkgs/16.09 gatk/4.1.2.0


Ou, puisque nixpkgs/16.09 est chargé par défaut, simplement

  [name@server ~]$ module load gatk/4.1.2.0


General usage

The later versions of GATK (>=4.0.0.0) provide a 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.

Versions antérieures à GATK 4

Les versions antérieures n'offrent pas la commande gatk; invoquez plutôt le fichier jar :

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 "${EBROOTGATK}"/GenomeAnalysisTK.jar PROGRAM OPTIONS

Pour les particularités de GATK <= 3 voyez le guide GATK3.

Multicore usage

Most GATK (>=4) tools are not multicore by default. This means that you should request only one core when calling these kind of tools. Some tools use threads in some of the computations (e.g. Mutect2 has the --native-pair-hmm-threads) and therefore you can require more cpus (most of them with up to 4 threads) for these computations. GATK4, however, does provides some SPARK commands:

Not all GATK tools use Spark
Tools that can use Spark generally have a note to that effect in their respective Tool Doc.

- Some GATK tools exist in distinct Spark-capable and non-Spark-capable versions
The "sparkified" versions have the suffix "Spark" at the end of their names. Many of these are still experimental; down the road we plan to consolidate them so that there will be only one version per tool.

- Some GATK tools only exist in a Spark-capable version
Those tools don't have the "Spark" suffix.

For the commands that do use spark, you can request multiple cpus. NOTE: please provide the exact number of cpus to the spark command, so if you requested 10 cpus, use --spark-master local[10] instead of --spark-master local[*]. If you want to scale the spark calls with multinode SPARK cluster, you have to first deploy an SPARK cluster and then set up the appropriate variables in the GATK4 spark command.

Running GATK via Singularity

If you encounter errors like "IllegalArgumentException" while using the installed modules on our clusters, we recommend you to try another workflow by using the program via Singularity.

A Docker image of GATK can be found here and other versions are available at this page. You will need first to build a Singularity image from the Docker image.

For example, to get the latest version, you can run the following commands on the cluster:

module load singularity
singularity build gatk.sif docker://broadinstitute/gatk

or to get a particular version:

module load singularity
singularity build gatk_VERSION.sif docker://broadinstitute/gatk:VERSION

In your SBATCH script, you should use something like this:

module load singularity
singularity exec -B /home -B /project -B /scratch -B /localscratch \
    <path to the image>/gatk.sif gatk [--java-options "-Xmx4G"] ToolName [GATK args]

For more information about Singularity, you can watch the recorded Singularity webinar.

Frequently asked questions

How do I add a read group (RG) tag in my bam file?

Assuming that you want to add a read group called tag to the file called 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.

Foire aux questions

Voyez Troubleshooting GATK4 Issues.

Références

Site web GATK

GATK et SPARK

Make GATK run faster

Catégorie : Bioinformatics Catégorie : Software