Using GenePattern from Java  Print-icon

Using Java as a GenePattern client allows you to run GenePattern modules and visualizers from within a Java application. This section describes how you can use the GenePattern Java library to run GenePattern analyses as easily as calling a routine. It contains the following topics:

Getting Started in Java

If you are not familiar with Java, see the http://java.sun.com website, which provides downloadable programs, samples, tutorials, and book suggestions.

GenePattern Java Library

The GenePattern Java library allows you to invoke a GenePattern module as if it were a local Java method running on your client and to get back from the module a list of result files. A zip file containing the Java library (and Javadoc that describes the API for accessing the server and running modules) is available on your GenePattern server.

To download the GenePattern Java library to your computer:

  1. Start GenePattern.
  2. Select Downloads>Programming Libraries.
  3. Under Java, click zip to download the zip file for the GenePattern Java library.
  4. After downloading the zip file, unzip it into the directory where you will be doing your Java development.

Running a Java Program

This section explores a simple Java application that preprocesses a dataset and displays it using the HeatMapViewer. The included code can be copied and pasted into your Java program so that you can try it out, modify it, and create your own solutions. The full source code of the sample application is available here.

The first statements in the application initialize various settings, which you must do once in every application that accesses GenePattern. You will need to customize the italicized GenePattern server URL and GenePattern user name (typically, your e-mail address) with values appropriate for your GenePattern server.

import org.genepattern.matrix.Dataset;
import org.genepattern.client.GPClient;
import org.genepattern.webservice.JobResult;
import org.genepattern.webservice.Parameter;
import org.genepattern.io.IOUtil;
import java.io.File;
public class MyProgram 
{
   public static void main(String[] args) throws Exception 
   {
      GPClient gpClient = new GPClient("http://localhost:8080", "your email address");
 

After initializing the required settings, the application runs the PreprocessDataset module to preprocess a dataset. This example references the dataset using a publicly-accessible URL, but a filename would be equally valid. When you invoke the runAnalysis method, the GenePattern library invokes the appropriate module on the server, passing all of the input parameters and input files. Control returns to your application when the module completes. (To run a module asynchronously, invoke the runAnalysisNoWait method or use the runAnalysis method in a separate thread.)

 String inputDataset = "ftp://ftp.broadinstitute.org/pub/genepattern/all_aml/all_aml_train.res";
 JobResult preprocess = gpClient.runAnalysis("PreprocessDataset", 
    new Parameter[] {
       new Parameter("input.filename", inputDataset)
 }); 

When the module completes, you can query the JobResult object for an array of filenames that are the output from the module. You can download the result files or leave them on the server and refer to them by URL. Referring to result files by URL is especially useful for intermediate results. In this example, the JobResult object named preprocess contains a list of filenames (of length 1, in this case), which the application displays in a heat map:

 // view results in a HeatMapViewer visualizer
 gpClient.runVisualizer("HeatMapViewer", 
    new Parameter[] {
       new Parameter("dataset", preprocess.getURL(0).toString())
 }); 

The last statements in the application download the preprocessed data and load it into a matrix for further analysis:

 String downloadDirName = String.valueOf(preprocess.getJobNumber());
 // download result files
 File[] outputFiles = preprocess.downloadFiles(downloadDirName);
 // load data into matrix for further manipulation
 Dataset dataset= IOUtil.readDataset(outputFiles[0].getPath());
 }

}

You can combine GenePattern analyses with any capabilities that the Java environment has to offer. Use Java's 2-D and 3-D graphics libraries to create graphic output, or summarize and report on the data using your own code. The basic idea to remember is that GenePattern modules create result files and those files are available to the Java application for processing.

For more information:

Using LSIDs from Java

Life Science Identifiers (LSIDs) can be used instead of module names to identify modules for GenePattern to run. An LSID may be submitted in place of the module name in the methods runAnalysis and runVisualizer. When an LSID is provided that does not include a version, the latest available version of the module identified by the LSID will be used. If a module name is supplied, the latest version of the module with the nearest authority is selected. The nearest authority is the first match in the sequence: local authority, Broad authority, other authority.

If you are unfamiliar with LSIDs and GenePattern versioning, see Concepts.

<< Writing MATLAB Modules Up Using GenePattern from MATLAB >>

Updated on June 07, 2013 13:56