Writing MATLAB Modules  Print-icon

If you are writing MATLAB code to be invoked as a GenePattern module, follow the guidelines in Writing Modules for GenePattern. In addition, for MATLAB code, you must address licensing and distribution issues, as described in this section:

Two Approaches: Direct and Compiled

You can invoke a MATLAB executable from a GenePattern module using one of two approaches: the direct approach or the compiled approach. Following are brief descriptions of each approach, including its advantages and disadvantages:

If you are simply using your M-code on your standalone GenePattern server, the direct approach is simpler; however, if you want to give copies of your M-code to other people or deploy your M-code on a shared GenePattern server, the compiled approach is preferred. The compiled approach may provide slightly better performance for fast running modules since the startup delay will be shorter, but the actual execution time will be approximately the same for either approach.

MATLAB Versions

The instructions in this section are based on the following MATLAB versions:

Adapting Your MATLAB Code

When you create a module in GenePattern, you specify the command line that invokes the program that performs the desired function. Generally, the command line includes arguments, such as the parameters for the algorithm and the data file to analyze.

Calling script M-code from a command line is possible, but generally not useful because you cannot pass arguments to the script. To pass arguments to your M-code, create a no-return entry function to serve as the top level call into MATLAB. The following example defines a no-return entry function that accepts two parameters:

function analyzeThis ( filename, whatToWrite )
... (your M-code here)

Writing Modules for GenePattern provides additional guidelines for writing code that will run as a GenePattern module.

Compiling Your MATLAB Code

If you do not plan to use the compiled M-code approach, skip this section and continue with Distributing Your MATLAB Code.

Compiling your MATLAB M-code into a standalone executable is described in the MATLAB Compiler Documentation. Please refer to this documentation to understand all of the options available to you. To summarize the simplest case, from within MATLAB, at the MATLAB prompt, execute the following command:

mcc -m analyzeThis

where analyzeThis is the name of your entry function. This command generates the following files in your $MATLAB_ROOT/work directory:

analyzeThis (Linux, Mac OS X) or
analyzeThis.exe (Windows)
Executable file
analyzeThis.ctf Component Framework file
analyzeThis.c (Linux, Windows) C language Source Code
analyzeThis.h (Linux, Windows C Language Header file
analyzeThis_main.c C language Source Code
analyzeThis_mcc_component_data.c C language Source Code

Note: To use the MATLAB compiler on Mac OS X, you must have Xcode 2.2 installed; minimally, the Developer Tools, gcc 4.0, gcc 3.3, Mac OS X SDK, and BSD SDK. These instructions were tested using Xcode 2.2.1.

Distributing Your MATLAB Code

After writing your MATLAB code, create a GenePattern module that invokes the code that you have written. Creating Modules in GenePattern describes how to create a GenePattern module. This section provides supplemental information for MATLAB:

Direct Approach Distribution

Creating Modules in GenePattern describes how to create a GenePattern module that invokes the code that you have written. This section provides additional information that applies when you are directly calling the MATLAB executable from the GenePattern module:

Windows Command Line

On Windows, your GenePattern module definition form can contain a simple command line that calls MATLAB with the -r flag to execute your function; for example:

matlab -nosplash -r "analyzeThis <p1> <p2>"

This example invokes MATLAB without the splash screen (-nosplash) and directs it to execute the quoted command, where p1 and p2 are parameters that you specify in the GenePattern module definition form and that are passed to the MATLAB command line as Strings. MATLAB looks for the function analyzeThis on the MATLAB path; therefore, it is not necessary to upload the function as a support file, although it is recommended.

To ensure that the GenePattern server can call the MATLAB executable, you typically add the MATLAB directory to your PATH system environment variable. (Alternatively, you can enter the full path to the MATLAB executable on the command line, but this makes it more difficult to deploy the module on other GenePattern servers.)

To check that MATLAB is on your path:

  1. Open a DOS window.
  2. Type matlab and press Enter.

If the MATLAB application starts, MATLAB is on your path.

If MATLAB is not on your path, add it:

  1. Select Start>Settings>Control Panel.
  2. Double-click System.
  3. Select the Advanced tab.
  4. Click the Environment Variables button.
  5. Select or create the PATH variable.
  6. Add the $MATLAB_ROOT/bin directory to the path.

Open a new DOS window and check again that MATLAB is on your path.

Preferred Command Line

On platforms other than Windows, the execution of the command line differs slightly due to variations in the Java Virtual Machines (VMs) that GenePattern is running. If you use the simple matlab command, as described for Windows, the Java VMs on these platforms attempt to parse and quote the command line resulting in MATLAB generating errors in its eval function.

On these platforms, you must use a wrapper Java class to launch MATLAB. This wrapper class also works on Windows and does not rely on the PATH variable, which makes it the preferred method for implementing the direct approach on any platform.

To use the wrapper Java class:

  1. On the GenePattern module definition form, add the runmatlab.jar file as a support file. To request a copy of this file, send e-mail to gp-help (at) broadinstitute.org; alternatively, the java source code for the RunMatlab wrapper class is included here: RunMatlab.java.
  2. Write your command line as follows:
    <java> -cp <libdir>runmatlab.jar RunMatlab <libdir> analyzeThis <p1> <p2>

    Where analyzeThis is the name of your MATLAB entry function name and <p1> and <p2> are the arguments to the function. The RunMatlab class ensures that the arguments are correctly written out and calls MATLAB with the -nosplash and -nodisplay arguments.

Compiled Approach Distribution

Creating Modules in GenePattern describes how to create a GenePattern module that invokes the code that you have written. This section provides additional information that applies when you are compiling your M-code into a standalone executable and invoking that executable from the GenePattern module:

Preparing the GenePattern Server

To run a standalone executable generated by the MATLAB Compiler, the GenePattern server must have the MATLAB Component Runtime (MCR) installed. This is a collection of shared libraries, which contains the runtime code for MATLAB, that is used by the standalone application. If the GenePattern server has MATLAB installed, you do not need to install the MCR; it is already installed.

Full details for installing the MCR can be found in the MATLAB Compiler documentation, in the section titled "Deploying Components to Other Machines". To summarize this documentation, on the GenePattern server machine, you need to run the MCRInstaller:

On Windows, to run the MCRInstaller:

  1. Copy <matlabroot>\toolbox\compiler\deploy\win32\MRCInstaller.exe to the server machine.
  2. Run MCRInstaller.exe.

On Linux, to run the MCRInstaller:

  1. In MATLAB, at the MATLAB prompt, execute the command buildmcr.
  2. Copy <matlabroot>/toolbox/compiler/deploy/MCRInstaller.zip to the server machine.
  3. On the server machine, unzip MCRInstaller.zip into a directory (<mcr_root>).
  4. Update the dynamic library path for the user running the GenePattern server:

    setenv LD_LIBRARY_PATH
    <mcr_root>/runtime/glnx86:
    <mcr_root>/sys/os/glnx86:
    <mcr_root>/sys/java/jre/glnx86/jre1.4.2/lib/i386/client:
    <mcr_root>/sys/java/jre/glnx86/jre1.4.2/lib/i386:
    <mcr_root>/sys/opengl/lib/glnx86:${LD_LIBRARY_PATH}

On Mac OS X, to run the MCRInstaller:

  1. In MATLAB, at the MATLAB prompt, execute the command buildmcr.
  2. Copy <matlabroot>/toolbox/compiler/deploy/MCRInstaller.zip to the server machine.
  3. On the server machine, unzip MCRInstaller.zip into a directory (<mcr_root>).
  4. Update the library path for the user running the GenePattern server:

    setenv DYLD_LIBRARY_PATH
    <mcr_root>/<ver>/runtime/mac:
    <mcr_root>/<ver>/sys/os/mac:
    <mcr_root>/<ver>/bin/mac:
    /System/Library/Frameworks/JavaVM.framework/JavaVM:
    /System/Library/Frameworks/JavaEmbedding.framework/JavaEmbedding:
    /System/Library/Frameworks/JavaVM.framework/Libraries
    setenv XAPPLRESDIR <mcr_root>/<ver>/X11/app-defaults

Writing the Launcher Script

When the MATLAB Compiler generates a standalone executable, it also generates a Component Framework (.ctf) file. The .ctf file must be on the path when you run the standalone executable. The easiest way to address this requirement is to create a launcher script (.bat or .sh file) that adds the .ctf file to the PATH or LIBPATH and then runs the standalone executable.

On Windows, for example, to launch the MATLAB executable analyzeThis.exe, create a launcher script, mllaunch.bat, that contains the following lines:

set LIBDIR=%1
set PATH=%LIBDIR%;%PATH%
analyzeThis %2 %3

On Linux, for example, to launch the MATLAB executable analyzeThis.exe, create a launcher script, mllaunch.sh, that contains the following lines:

#!/bin/csh
export MCR_ROOT=<path where you installed the files from MCRInstaller.zip>
export LD_LIBRARY_PATH=$1:$MCR_ROOT/runtime/glnx86:$MCR_ROOT/sys/os/glnx86:\
$MCR_ROOT/sys/java/jre/glnx86/jre1.4.2/lib/i386/client:\
$MCR_ROOT/sys/java/jre/glnx86/jre1.4.2/lib/i386:\
$MCR_ROOT/sys/opengl/lib/glnx86
 
export PATH=$1:$PATH
chmod a+x $1/analyzeThis
analyzeThis $2 $3

The chmod line sets the executable permission on the executable file; by default, the GenePattern server does not set this permission for uploaded files.

On Mac OS X, for example, to launch the MATLAB executable analyzeThis.exe, create a launcher script, mllaunch.sh, that contains the following lines:

#!/bin/sh
export MCR_ROOT=/Volumes/os9/gpserv
export LD_LIBRARY_PATH=$1:/Volumes/os9/matlab7.2/sys/os/mac:
/Volumes/os9/matlab7.2/bin/mac/
export DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH
export PATH=$1:$PATH
chmod a+x $1/writeToFile
writeToFile $2 "$3"

The chmod line sets the executable permission on the executable file; by default, the GenePattern server does not set this permission for uploaded files.

Writing the Module Command Line

On the GenePattern module definition form, write a command line calls the launcher script, passing the <libdir> parameter as the first argument (so that it can be added to the path).

On Windows, the following command line calls the launcher script, mllaunch.bat:

<libdir>mllaunch.bat <libdir> <param1> <param2>

On Linux or Mac OS X, the following command line calls the launcher script, mllaunch.sh:

sh <libdir>mllaunch.sh <libdir> <param1> <param2>

In both command lines, the first <libdir> sets the path to the mllaunch script. The second <libdir> is passed as the first argument to the script so that the script can add this directory to the appropriate environment variables. The <param1> and <param2> variables are parameters to the MATLAB application, which you define in the module definition form and specify in the command line as usual.

Adding Support Files

For the compiled approach, you must specify at least two support files for the MATLAB application: the executable file and .ctf file. If your application requires additional files for its execution, also add those files as support files.

Distribution Licensing

Should you choose to distribute your MATLAB based module to others, you must ensure you are in compliance with the MATLAB licensing agreement:

http://www.mathworks.com/company/aboutus/policies_statements/agreement.pdf

Following are a few key points for GenePattern developers:

Please refer to the MATLAB licensing agreement for exact details. You are responsible for reviewing and complying with the MATLAB software license. The above summary does not exempt you from this responsibility.

Example: Deploying a Compiled MATLAB Application

This section provides a step-by-step example of deploying a simple M-file application as a GenePattern module on a GenePattern server. Where the instructions are platform specific, the example shows instructions for Windows, Linux, and Mac OS X.

Writing the M-file

The first step is writing the MATLAB M-file that you want to share. For this example, write a simple application that takes a filename and a String and writes the String out to a file with the given name. This application consists of the following lines:

% write the variable whatToWrite to a file called filename in the current directory
fid = fopen(filename,'w');
fprintf(fid,'#writing to a file\n\n');
fprintf(fid,whatToWrite);
fclose(fid);

Adapting the M-file

To call the M-file from the command line and pass it parameters, you must turn this script into a no-return function. To do this, add a function definition line at the start of the M-file and save the file using the name of the function (for example, writeToFile.m).

function writeToFile( filename, whatToWrite)
% write the parameter whatToWrite to a file called filename in the current directory
fid = fopen(filename,'w');
fprintf(fid,'#writing to a file\n\n');
fprintf(fid,whatToWrite);
fclose(fid);

Compile the M-file

Within the MATLAB environment, call the MATLAB Compiler to convert this function into an application:

>> mcc -m writeToFile

Within the current working directory, this creates a number of files, including the following:

Note: To use the MATLAB compiler on Mac OS X, you must have Xcode 2.2 installed; minimally, the Developer Tools, gcc 4.0, gcc 3.3, Mac OS X SDK, and BSD SDK. These instructions were tested using Xcode 2.2.1.

Prepare the GenePattern Server

Install the MATLAB Component Runtime (MCR) on the GenePattern server, if you have not done so already. If the GenePattern server has MATLAB installed, it also has the MCR installed.

Windows

To install the MCR:

  1. Copy <matlabroot>\toolbox\compiler\deploy\win32\MRCInstaller.exe to the GenePattern server machine.
  2. At the DOS prompt, or from Windows Explorer, run the following:

    MCRInstaller.exe

Linux or Mac OS X

To install the MCR:

  1. Within the MATLAB environment, create the MCRInstaller zip file:
    >> buildmcr mcrdir
    This creates a directory, mcrdir, beneath the current working directory and creates a file within that directory called MCRInstaller.zip.
  2. Copy the zip file to your GenePattern server (if it is a different machine) and install it into a directory. For example, add a directory, matlab, under the GenePattern server directory and install the library files in MCRInstaller.zip into that directory:

    cd GenePatternServer
    mkdir matlab
    cd matlab
    cp <path to mcrinstaller.zip>MCRInstaller.zip .
    unzip MCRInstaller.zip

Create the Launcher Script

Create the launcher script that sets the environment variables and then calls the MATLAB application.

Windows

Create the launcher script as a batch file that sets the PATH variable for the environment and then calls the MATLAB application. To do so, in a text editor, create the following mllaunch.bat file:

set LIBDIR=%1
set PATH=%LIBDIR%;%PATH%
writeToFile %2 %3

Linux

Create the launcher script as an .sh file that sets the PATH and LD_LIBRARY_PATH variables for the environment, ensures that the application is executable, and then calls the MATLAB application. To do so, in a text editor, create the following mllaunch.sh file:

#!/bin/csh
export MCRROOT=/home/username/GenePatternServer/matlab/v70
export LD_LIBRARY_PATH=$1:$MCRROOT/runtime/glnx86:$MCRROOT/sys/os/glnx86:$MCRROOT/sys/java/ jre/glnx86/jre1.4.2/lib/i386/client:$MCRROOT/sys/java/jre/glnx86/jre1.4.2/lib/i386:$MCRROOT/ sys/opengl/lib/glnx86
export PATH=$1:$PATH
chmod a+x $1/testTwo
writeToFile $2 $3

Note that the MCR_ROOT variable is set to the v70 directory, which you created by unzipping MCRInstaller.zip.

Mac OS X

Create the launcher script as an .sh file that sets the LD_LIBRARY_PATH and DYLD_LIBRARY_PATH variables for the environment, ensures that the application is executable, and then calls the MATLAB application. To do so, in a text editor, create the following mllaunch.sh file:

#!/bin/sh
export MCR_ROOT=/Volumes/os9/gpserv
export LD_LIBRARY_PATH=$1:/Volumes/os9/matlab7.2/sys/os/mac:/Volumes/os9/matlab7.2/bin/mac/
export DYLD_LIBRARY_PATH=$LD_LIBRARY_PATH
export PATH=$1:$PATH
chmod a+x $1/writeToFile
writeToFile $2 "$3"

Create the GenePattern Module

Use GenePattern to create a module that executes the launcher script.

Windows

Linux or Mac OS X

Save the Module and Test It

Save the module and execute it. The module should create two files:

Debugging (Linux Only)

If the following error appears in the stdout file, you have not correctly set the path to the libraries that you installed from MCRInstaller.zip:

error while loading shared libraries: libmwmclmcrrt.so.7.0: cannot open shared object file: No such file or directory

Double check the path. If it is correct, you may be using a different Unix shell than the one used in this example. Check that the mllaunch.sh file uses the correct command (export in this example) to set PATH and LD_LIBRARY_PATH.

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

Updated on September 03, 2012 12:45