# Writing MATLAB Modules

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:

• Direct approach. In the direct approach, the GenePattern module directly invokes the MATLAB executable, which executes your M-code. This approach is best suited for use on a standalone GenePattern server, where you already have a MATLAB license and you will not redistribute the MATLAB-based GenePattern modules to other users who do not have their own MATLAB licenses. The advantages to this approach are: it is the simplest way to getting your M-code running on GenePattern, it can be used for any MATLAB and GenePattern supported platform, and it allows for easier modification of the M-code files as you modify your analysis. The disadvantages of this approach are: it requires a MATLAB license for each concurrent user on the GenePattern server machine and, if you change platforms, you must change the command line because different platforms have different methods of passing arguments to MATLAB.
• Compiled approach. In the compiled approach, you use the MATLAB Compiler to generate a standalone executable; the GenePattern module then invokes that executable. The advantages to this approach are: it allows redistribution of the module to other GenePattern users who do not have their own MATLAB license and it can be run on a shared server without needing to get a MATLAB license for each concurrent user. The disadvantages are: it requires you to have a MATLAB Compiler license, it can be used only on platforms supported by the MATLAB Compiler, it must be compiled separately for each platform, and the GenePattern server must have the MATLAB Component Runtime (MCR) installed before it can run the compiler-generated executable.

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:

• MATLAB 7.1 (part of Release 14). Earlier versions of MATLAB use a different (deprecated) mechanism for deployment, which is not compatible with the instructions provided in this guide. For Mac OS X, these instructions were tested using MATLAB 7.2.
• MATLAB Compiler 4.0 or later. The MATLAB Compiler is currently available on Windows, Unix, and Mac OS X; therefore, these are the only platforms on which you may deploy a compiled MATLAB-based module. For Mac OS X, these instructions were tested using the MATLAB Compiler 4.4.
The MATLAB Compiler generates executables only for the platform on which it is executing. For example, if you create a MATLAB executable on Windows, the MATLAB-based module that invokes that executable can only be deployed on a GenePattern server running under Windows. Therefore, you need a MATLAB (and MATLAB Compiler) license for each platform on which you wish to deploy your executable.

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.

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 " 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:
  -cp runmatlab.jar RunMatlab analyzeThis

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 /runtime/glnx86: /sys/os/glnx86: /sys/java/jre/glnx86/jre1.4.2/lib/i386/client: /sys/java/jre/glnx86/jre1.4.2/lib/i386: /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 //runtime/mac: //sys/os/mac: //bin/mac: /System/Library/Frameworks/JavaVM.framework/JavaVM: /System/Library/Frameworks/JavaEmbedding.framework/JavaEmbedding: /System/Library/Frameworks/JavaVM.framework/Libraries setenv XAPPLRESDIR //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= 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:  mllaunch.bat  On Linux or Mac OS X, the following command line calls the launcher script, mllaunch.sh:  sh mllaunch.sh  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: • You may not distribute code that uses MATLAB and that competes with any of The MathWorks products. • You may not modify or remove any license file included with the MCR Libraries. • Users of your GenePattern modules must be made aware of the MATLAB license agreement in documentation and accept it before installing your modules. • Your MATLAB application must have an about box or equivalent "visible" location that includes the legend "MATLAB copyright 1984-yyyy the MathWorks Inc.", where yyyy is the year you released your module. 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: • writeToFile.exe (Windows) or writeToFile (Linux, Mac OS X) • writeToFile.ctf 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 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

• For the command line, enter the following:
sh <libdir>mllaunch.bat <libdir> <fname> <txt>
• Define two parameters:
• <fname> for the output file name
• <txt> for the text to write to the file
• Include the following support files:
• mllaunch.bat
• whatToWrite.exe
• whatToWrite.ctf

#### Linux or Mac OS X

• For the command line, enter the following:

sh <libdir>mllaunch.sh <libdir> <fname> <txt>

• Define two parameters:
• <fname> for the output file name
• <txt> for the text to write to the file
• Include the following support files:
• mllaunch.sh
• whatToWrite
• whatToWrite.ctf

### Save the Module and Test It

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

• A stdout file that contains execution information.
• A file with the name and text that you specified.

### 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.

Updated on September 03, 2012 12:45