Bug Bulletin: we have identified a bug that affects indexing when producing gzipped VCFs. This will be fixed in the upcoming 3.2 release; in the meantime you need to reindex gzipped VCFs using Tabix.

(howto) Test your GATK installation

Geraldine_VdAuweraGeraldine_VdAuwera Posts: 5,276Administrator, GSA Member admin
edited July 2013 in Tutorials

Objective

Test that the GATK is correctly installed, and that the supporting tools like Java are in your path.

Prerequisites

  • Basic familiarity with the command-line environment
  • Understand what is a PATH variable
  • GATK downloaded and placed on path

Steps

  1. Invoke the GATK usage/help message
  2. Troubleshooting

1. Invoke the GATK usage/help message

The command we're going to run is a very simple command that asks the GATK to print out a list of available command-line arguments and options. It is so simple that it will ALWAYS work if your GATK package is installed correctly.

Note that this command is also helpful when you're trying to remember something like the right spelling or short name for an argument and for whatever reason you don't have access to the web-based documentation.

Action

Type the following command:

java -jar <path to GenomeAnalysisTK.jar> --help

replacing the <path to GenomeAnalysisTK.jar> bit with the path you have set up in your command-line environment.

Expected Result

You should see usage output similar to the following:

usage: java -jar GenomeAnalysisTK.jar -T <analysis_type> [-I <input_file>] [-L 
        <intervals>] [-R <reference_sequence>] [-B <rodBind>] [-D <DBSNP>] [-H 
        <hapmap>] [-hc <hapmap_chip>] [-o <out>] [-e <err>] [-oe <outerr>] [-A] [-M 
        <maximum_reads>] [-sort <sort_on_the_fly>] [-compress <bam_compression>] [-fmq0] [-dfrac 
        <downsample_to_fraction>] [-dcov <downsample_to_coverage>] [-S 
        <validation_strictness>] [-U] [-P] [-dt] [-tblw] [-nt <numthreads>] [-l 
        <logging_level>] [-log <log_to_file>] [-quiet] [-debug] [-h]
-T,--analysis_type <analysis_type>                     Type of analysis to run
-I,--input_file <input_file>                           SAM or BAM file(s)
-L,--intervals <intervals>                             A list of genomic intervals over which 
                                                       to operate. Can be explicitly specified 
                                                       on the command line or in a file.
-R,--reference_sequence <reference_sequence>           Reference sequence file
-B,--rodBind <rodBind>                                 Bindings for reference-ordered data, in 
                                                       the form <name>,<type>,<file>
-D,--DBSNP <DBSNP>                                     DBSNP file
-H,--hapmap <hapmap>                                   Hapmap file
-hc,--hapmap_chip <hapmap_chip>                        Hapmap chip file
-o,--out <out>                                         An output file presented to the walker. 
                                                       Will overwrite contents if file exists.
-e,--err <err>                                         An error output file presented to the 
                                                       walker. Will overwrite contents if file 
                                                       exists.
-oe,--outerr <outerr>                                  A joint file for 'normal' and error 
                                                       output presented to the walker. Will 
                                                       overwrite contents if file exists.

...

If you see this message, your GATK installation is ok. You're good to go! If you don't see this message, and instead get an error message, proceed to the next section on troubleshooting.


2. Troubleshooting

Let's try to figure out what's not working.

Action

First, make sure that your Java version is at least 1.7, by typing the following command:

java -version

Expected Result

You should see something similar to the following text:

java version "1.7.0_12"
Java(TM) SE Runtime Environment (build 1.7.0_12-b04)
Java HotSpot(TM) 64-Bit Server VM (build 11.2-b01, mixed mode)  

Remedial actions

If the version is less then 1.7, install the newest version of Java onto the system. If you instead see something like

java: Command not found  

make sure that java is installed on your machine, and that your PATH variable contains the path to the java executables.

Post edited by Geraldine_VdAuwera on

Geraldine Van der Auwera, PhD

Comments

  • donfreeddonfreed BaltimorePosts: 3Member

    This article is a little out of date as GATK now requires java version 7. broadinstitute.org/gatk/guide/article?id=2846

    If you an error like this:

    Exception in thread "main" java.lang.UnsupportedClassVersionError: org/broadinstitute/sting/gatk/CommandLineGATK : Unsupported major.minor version 51.0
    

    You'll need to update to java 7

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 5,276Administrator, GSA Member admin

    Indeed, that is correct. Thanks for reporting this, I'll update the article accordingly.

    Geraldine Van der Auwera, PhD

  • sarahhsarahh Posts: 2Member

    when I typed Java -version I had the answer java version "1.6.0_51" but when I wanted to update Java on my Mac, the Java Control Panel tells me I have the up-to date version Java 7.25. What should I do? Thanks.

  • KurtKurt Posts: 110Member ✭✭✭

    I have two Java versions going on since site wide, we have not made the transition to java 1.7. So my default is 1.6, but when I am using GATK 2.6+, I usually provide a full path (and just have it set as a variable in a shell script). e.g.

    JAVA_1_7="/isilon/sequencing/Kurt/Programs/Java/jdk1.7.0_25/bin"

    $JAVA_1_7/java -jar $GATK_DIR/GenomeAnalysisTK.jar ...

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 5,276Administrator, GSA Member admin

    @sarahh, on MacOSX it seems that you have to install the latest JDK package from Sun (as opposed to just the JRE). It's a pain, but blame Apple...

    Geraldine Van der Auwera, PhD

  • sarahhsarahh Posts: 2Member

    Ok, I did it and it indeed changed the version to 1.7.0_25, thank you very much Geraldine!

  • hungstachungstac Posts: 2Member

    I have a Mac OSX 10.6.8 with JRE version 1.6.0_45. I tried to update to java 1.7, but according to the java website, Java 7 is not supported by versions of Mac OS X 10.6 or older. Does this mean I cannot run GATK on my computer? Thanks.

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 5,276Administrator, GSA Member admin

    Hi @hungstac,

    If you cannot upgrade your Mac OS version, that might be a problem. There are some workarounds for this such as this one but I cannot give you any guarantees that it will work or that it is safe to do. Another workaround would be to install a virtual machine on your mac to emulate a different OS, but we can't provide any guidance for that either. I would recommend asking your IT department for help with this issue.

    Geraldine Van der Auwera, PhD

  • dfajar2dfajar2 USAPosts: 2Member

    Hi Geraldine, What if I have all the prerequisites installed to run GATK and still get an error. I am pastiing below the outputs to doublecheck they are installed.

    $ java -version

    java version "1.8.0-ea" Java(TM) SE Runtime Environment (build 1.8.0-ea-b113) Java HotSpot(TM) 64-Bit Server VM (build 25.0-b55, mixed mode)

    $ bwa

    Program: bwa (alignment via Burrows-Wheeler transformation) Version: 0.7.5a-r405 Contact: Heng Li lh3@sanger.ac.uk Usage: bwa [options] Command: index index sequences in the FASTA format mem BWA-MEM algorithm fastmap identify super-max ........

    $ htscmd

    Version: 0.0.1+ Usage: htscmd Commands: -- General and indexing tools: samview SAM<->BAM conv.........

    $ samtools

    Program: samtools (Tools for alignments in the SAM format) Version: 0.1.19-44428cd Usage: samtools [options] Command: view SAM<->BAM conversi............

    $ java -jar /usr/local/bin/picard-tools-1.101/AddOrReplaceReadGroups.jar -h

    Replaces all read groups in the INPUT file with a new read group and assigns all reads to this read group in the OUTPUT BAMVersion: 1.0 Version: 1.101(1580) Option....................

    So everything looks good, but when I try to test GATK installation I get the following error:

    $ java -jar GenomeAnalysisTK.jar --help

    ERROR ------------------------------------------------------------------------------------------
    ERROR stack trace

    java.lang.ExceptionInInitializerError at org.broadinstitute.sting.gatk.GenomeAnalysisEngine.(GenomeAnalysisEngine.java:164) at org.broadinstitute.sting.gatk.CommandLineExecutable.(CommandLineExecutable.java:53) at org.broadinstitute.sting.gatk.CommandLineGATK.(CommandLineGATK.java:54) at org.broadinstitute.sting.gatk.CommandLineGATK.main(CommandLineGATK.java:90) Caused by: java.lang.NullPointerException at org.reflections.Reflections.scan(Reflections.java:220) at org.reflections.Reflections.scan(Reflections.java:166) at org.reflections.Reflections.(Reflections.java:94) at org.broadinstitute.sting.utils.classloader.PluginManager.(PluginManager.java:79) ... 4 more

    ERROR ------------------------------------------------------------------------------------------
    ERROR A GATK RUNTIME ERROR has occurred (version 2.5-2-gf57256b):
    ERROR
    ERROR Please check the documentation guide to see if this is a known problem
    ERROR If not, please post the error, with stack trace, to the GATK forum
    ERROR Visit our website and forum for extensive documentation and answers to
    ERROR commonly asked questions http://www.broadinstitute.org/gatk
    ERROR
    ERROR MESSAGE: Code exception (see stack trace for error itself)
    ERROR ------------------------------------------------------------------------------------------

    What am I missing?

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 5,276Administrator, GSA Member admin

    I think this is because you have Java 1.8 installed. The current version of GATK uses Java 1.7.

    Geraldine Van der Auwera, PhD

  • dfajar2dfajar2 USAPosts: 2Member

    Ha!! You were right, now I get the help screen running it with 1.7. Well, i guess it is not always the best to have the latest versions of some software installed.

    Thanks, I was turning myself crazy.

  • azaleaazalea State College, PAPosts: 1Member

    Hi, maybe this is not the right place to ask, but I was wondering how I can download GATK from the command line. I need to install GATK on a server with no GUI. Thanks.

  • Geraldine_VdAuweraGeraldine_VdAuwera Posts: 5,276Administrator, GSA Member admin

    Hi @azalea,

    That's not currently possible, sorry. You'll need to download it on a workstation with a GUI then transfer it over your network to your server.

    Geraldine Van der Auwera, PhD

  • egeulgenegeulgen USPosts: 3Member

    Hey @dfajar2 I've got to same problem. How did you work around it? uninstall 1.8 and 1.7?

    @dfajar2 said: Ha!! You were right, now I get the help screen running it with 1.7. Well, i guess it is not always the best to have the latest versions of some software installed.

    Thanks, I was turning myself crazy.

  • egeulgenegeulgen USPosts: 3Member

    @dfajar2 nevermind, I figured it out

    @egeulgen said: Hey dfajar2 I've got to same problem. How did you work around it? uninstall 1.8 and 1.7?

    Thanks, I was turning myself crazy.

Sign In or Register to comment.