Java Source Code

From GeneSetEnrichmentAnalysisWiki

GSEA Home | Downloads | Molecular Signatures Database | Documentation | Contact

This page provides the source code for the GSEA algorithm and desktop application. It also provides brief usage instructions, which are supplemented by the JavaDoc.

The source code is a 100% Pure Java implementation of the GSEA Algorithm from Subramanian, Tamayo, et al. (2005), PNAS 102, 15545-15550. The source code, instructions, and JavaDoc are intended for software engineers who want to

• programmatically access the GSEA Java library via its API or
  
• integrate the GSEA java program into their  analysis toolkit.

If you not interested in the source code and simply want to use the GSEA software, go to the Downloads page.

---

Contents 1 Download 2 Files in the GSEA Distribution 3 Setup your CLASSPATH 4 Examples of Usage 5 Helpful Hints 6 Feedback and Questions

Download

• Register and download the gsea2_distrib-xx.zip file from the Downloads  page.
• Unzip gsea2_distrib-xx.zip  using the option to create subdirectories.

This creates the following files and subdirectories:

GSEA2-xx/  
    README.txt
    LICENSE.txt
    build.xml     (an ant script that will build the source)

    src/
        edu/
        org/
        ...
        xexamples/
       
    lib/
        ext_lib_for_gsea.jar
        gsea2_lib-xx.jar
        ext/
            lucene-core-2.0.0.jar
            commons-math-1.1.jar
             ...
    bin/
       gsea2-xx.jar

    example_datasets/
        Leukemia.gct
        Leukemia.cls
        ...

 

Files in the GSEA Distribution

The GSEA distribution contains all files neccessary to build Java GSEA from source, as well as the original 3rd party jar files that GSEA uses. Please check the licenses of the 3rd party jar files to make sure you are in compliance.

The GSEA jar file comes in several flavors which are designed to allow for use as a runtime executeble, a java API library or a view of the source code:

1. "SRC": gsea2_src.jar (which is expanded into the /src directory in the ZIP file above)
2. "EXT": ext_lib_for_gsea.jar (which is a  bundled version of all external (3rd party) jar files that GSEA uses)
3. "LIB": gsea2_lib.jar = (1) + (2). To use the gsea API you only need gsea2_lib.jar.
4. "EXE": gsea2.jar = (runtime optimized)(c - .java). This is the jar that webstart and the desktop client use.
   

 

Setup your CLASSPATH

• Copy lib/gsea2_lib.jar to your java environment.
  
• Add it to your CLASSPATH.
• The gsea2_lib.jar file includes the external libraries; you do not have to include ext_lib_for_gsea.jar.
  
• If you want to be able to view the source code from within your IDE, also link to the gsea2_src.jar file.

Note: The gsea2.jar file you might have downloaded from the website is not the same as gsea2_lib.jar. It is an optimized version of gsea2_lib.jar that has been packaged to minimize download an application startup time. To use the gsea API you only need gsea2_lib.jar.

Tomcat / Using GSEA within a Java Server Environment: If you are working in a java server environment (for instance, Tomcat) and notice jar conflicts, you might need to pick jar files to use from the individual external jar files rather than simply using all of the ext_lib_for_gsea.jar.

 Important: GSEA uses the Jide software library for its GUI. You cannot use the JIDE software library without a JIDE license.

Examples of Usage

See the programs included in the xexamples package for simple usages of the GSEA java library.

To run an example program:
java -cp gsea2_lib.jar xexamples.ParsingExamples

Helpful Hints

1) Logging - to see debugging messages

java -Ddebug=true

The gsea java library uses log4j extensively. Often the log messages are useful to inspect and debug programs. But you might want to turn off or lower the threshold for messages.

2) Logging - to turn off messages

XLogger.setLoggingOff(); // @note this turns logging off

     To disable ONLY debugging messages (recommended) launch as:
     java -Ddebug=false MyProgram ...

3) TOMCAT usages

To eliminate the log4j messages by adding a log4j configuration file to my webapp and setting the level to WARN for edu.mit.broad.genome and edu.mit.broad.vdb
The last two lines are key (if you already have a log4j configuration file).

=======================================================================

# send all (warn, error, and fatal) to the console.
# by default, don't show debug, info
log4j.rootLogger=warn, stdout

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

# Pattern to output just the time and the message to the console
log4j.appender.stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss.SSS} %m%n

# limit logging information levels here
log4j.logger.edu.mit.broad.genome=WARN
log4j.logger.import edu.mit.broad.vdb=WARN

4) JAR CONFLICTS

If your application uses some 3rd party jar files that are in common with those that GSEA2 uses, you might see jar conflicts. To resolve these, email James Gosling and ask him why he didnt architect into Java a solution to this problem. Alternatively, you can resolve these conflicts by inspecting the common 3rd party jar files and using only 1 version of those.

Documentation

• The source code itself is currently the best source of documentation.
• Make sure to read the scripts in the xexamples package.
• The JavaDoc is also available.
  

License

Please see the GSEA License.

If you use the gsea java library within your application you also need to review and accept the license of each 3rd party jar file that GSEA uses. Please see the ext_lib_for_gsea.jar for a complete list.

IMPORTANT: You cannot use the JIDE software library without a JIDE license.

 

Feedback and Questions

If you have issues or questions with the API usage, contact gsea@broad.mit.edu. Please include in your email the source code of your program that is causing the error.