Using GenePattern from MATLAB  Print-icon

Using MATLAB as a GenePattern client allows you to run GenePattern modules and to manipulate and visualize the results in a powerful, commercial technical computing application that works on most major platforms. Using GenePattern allows you to invoke methods written in many other languages without having to worry about how to launch them. This section describes how you can use the GenePattern MATLAB library to run GenePattern analyses:

Getting Started in MATLAB

Resources and documentation for MATLAB are available at http://www.mathworks.com/.

GenePattern MATLAB Library

The GenePattern MATLAB library allows you to invoke a GenePattern module as if it were a local MATLAB function running on your client and to get back from the module a list of result files. A zip file containing the MATLAB library is available on your GenePattern server.

To download the GenePattern MATLAB library to your computer:

  1. Start GenePattern.
  2. Select Downloads>Programming Libraries.
  3. Under MATLAB, click zip to download the zip file for the GenePattern MATLAB library.
  4. After downloading the zip file, unzip it into your MATLAB7/toolboxes directory. If you do not have permission to put files in that directory, unzip into any other directory.
  5. After downloading and unzipping the files, add the directories to your MATLAB path:
    1. At a MATLAB prompt, open the pathtool:
      >>pathtool
    2. Use the MATLAB pathtool to add the GenePatternServer and GenePatternFileSupport directories, with subfolders, to the MATLAB search path.

Note: MATLAB 7.0.4 (R14SP2) and later use Java Virtual Machine (JVM) 1.5. If you are using an earlier version of MATLAB, you must change the JVM that MATLAB is using to JVM 1.5. For instructions, see http://www.mathworks.com/support/solutions/data/1-1812J.html?solution=1-1812J.

Running a MATLAB Program

This section explores a simple MATLAB program that runs a module, displays the resulting output, and loads it into a MATLAB matrix for further analysis. The included code can be copied and pasted into your MATLAB client so that you can try it out, modify it, and create your own solutions.

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, GenePattern user name (typically, your e-mail address) and password (if required) with values appropriate for your GenePattern server.

% Create a GenePattern server proxy instance
gp = GenePatternServer('http://localhost:8080','my.email@my.domain', 'mypassword');

After initializing the required settings, the application runs the TransposeDataset module to transpose a dataset. This example references the dataset using a publicly-accessible URL, but a filename would be equally valid. As shown below, you can call the GenePattern methods directly or by calling the runAnalysis method. When you call a GenePattern method, such as TransposeDataset, the GenePattern library invokes the 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 method in a separate thread.)

% input dataset for transpose operation
params.output_file_name = 'transposed.out'
params.input_filename='http://www.broadinstitute.org/mpr/publications/projects/Leukemia/
ALL_vs_AML_train_set_38_sorted.res'
 
% transpose the dataset
transposeResult = gp.TransposeDataset(params)
% alternate call to transpose the dataset
transposeResult = runAnalysis(gp, 'TransposeDataset', params)

When the module completes, it returns a MATLAB structure that contains a list of filenames that are the output from the module. In this example, transposeResult is a structure with a list of filenames (of length 1, in this case). The application displays the results in a file viewer window and also loads them into a matrix so that further manipulation can be performed:

% display the transposed results
edit 'transposed.out.gct'
 
% now read the output into a matrix
% so we can do further manipulation in MATLAB
myData = loadGenePatternExpressionFile('transposed.out.gct')

You can combine GenePattern analyses with all of the rich functionality of MATLAB. For example, you can use MATLAB's plotting methods to create graphic output, save modified matrices to files using save, 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 MATLAB client for processing.

For a list of the GenePattern modules available on your server, run the listMethods function on your GenePatternServer object. To view the names of the input parameters for a module, use the describeMethod function on your GenePatternServer object, passing it the module name.

% display the available GenePattern modules
listMethods(gp)
 
% now look at the parameters for the TransposeDataset module
describeMethod(gp, 'TransposeDataset')

Alternatively, to get the parameters with their default values filled in, use the getMethodParameters function of the GenePatternServer object. This returns a MATLAB structure with named elements for each parameter, filled in with the default value if one exists. After filling in the missing parameters and overriding defaults if desired, this structure can then be passed on to the runAnalysis method.

% display the available GenePattern modules
params2 = getMethodParameters(gp, 'TransposeDataset')
params2.input_filename='http://www.broadinstitute.org/mpr/publications/projects/Leukemia/ALL_vs_AML_train_set_38_sorted.res'
 
% transpose the dataset
transposeResult = gp.TransposeDataset(params2)

The GenePattern MATLAB library also has convenience methods to read and write GenePattern files (such as res, gct, and odf files). Even if you choose not to look in the library, you can extend the techniques shown above to implement your own analyses.

For more information:

Using LSIDs from MATLAB

You can use Life Science Identifiers (LSIDs) to identify a module when executing GenePattern code in MATLAB. An LSID may be submitted in place of the module name to getMethodParameters or runAnalysis. When providing an LSID to a method in addition to a module name, the LSID alone is used to determine what module to run. 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 you are unfamiliar with LSIDs and GenePattern versioning, see Concepts.

% Example using LSIDs from MATLAB
params = getMethodParameters(gp, 'urn:lsid:broad.mit.edu:cancer.software.genepattern.module.analysis:00026:3');

params.output_file_name = 'transposed.out'
params.input_filename='http://www.broadinstitute.org/mpr/publications/projects/Leukemia/ALL_vs_AML_train_set_38_sorted.res'
 
% transpose the dataset
transposeResult = runAnalysis(gp, 'urn:lsid:broad.mit.edu:cancer.software.genepattern.module.analysis:00026:3', params)

 

<< Using GenePattern from Java Up Using GenePattern from R >>

Updated on June 28, 2013 17:48