Gaggle Components
Geese
Data Standards
Boss

MatGoose (Matlab goose)

> Top > Installing MatGoose > Using MatGoose > MatGoose and Octave

Currently in beta release...

The MatGoose is a java class and m-file script library that connects MATLAB to the Gaggle. It is based heavily on the R-Goose, the Gaggle connector for the statistical analysis environment R. As such, use of MatGoose is similar in many ways. Bringing MATLAB into the suite of Gaggled applications will hopefully extend the systems based analysis methods promoted by the Gaggle to a broader audience.

Screencast demo

Here is a video that demonstrates the basic functionality of MatGoose by going through a simple data exploration using common Gaggle tools. (no audio)

Created with ScreenToaster

Requirements and Installation

Preparing MATLAB

MatGoose was developed using JDK-5.0 and therefore requires the Java Runtime Environment (JRE) version 1.5.x or higher. MatGoose was tested on MATLAB R2006b (7.3.0) ships with JRE 1.5.x. If you are using this version of MATLAB, or higher, then you can jump to the MatGoose installation steps below. Otherwise, before using MatGoose, you must change the default JRE/JVM used by MATLAB. Instructions for doing so can be found here:

http://www.mathworks.com/support/solutions/data/1-1812J.html

Be warned that doing the above steps may produce unpredictable behavior in MATLAB - e.g. various functions/toolboxes that use specific "features" of previous JREs may not work.

Getting and Installing MatGoose

> Top > Installing MatGoose > Using MatGoose > MatGoose and Octave

Download the MatGoose package HERE (Source code for MatGoose can be obtained from the Gaggle Subversion Repository)

To install MatGoose, first download the MatGoose package (.zip file) and extract it into a new folder named 'MatGoose' on your computer, preferably in a location where you keep all of your MATLAB related code. The installation steps below assumes that this folder is the default MATLAB 'work' directory,

C:\Program Files\MATLAB\R2006b\work

Within this folder you should see the following items

./m/
./matgoose.jar
./goose.jar

The "m" directory contains functions and scripts that MATLAB will need to access MatGoose's features. MatGoose.jar contains the MatGoose Java code, while goose.jar defines the Gaggle API - e.g. core objects, interfaces, and data types required for connecting to the Gaggle. Both are required to run MatGoose. As MatGoose improves, you should only have to replace MatGoose.jar and/or files in the "m" directory to upgrade to the latest available version.

Quit MATLAB if it is currently running. Using a text editor, add the full directory listing to the above .jar files to the end of the classpath.txt file. This is usually found in:

C:\Program Files\MATLAB\R2006b\toolbox\local

For example, the end of the classpath.txt file should look like:

.
.
.
$matlabroot/java/jarext/xml-apis.jar
glnxa64=$matlabroot/java/jarext/jogl.a64.jar
$matlabroot/java/jarext/jogl.jar
mac=/System/Library/Java
C:/Program Files/MATLAB/R2006b/work/MatGoose/matgoose.jar
C:/Program Files/MATLAB/R2006b/work/MatGoose/goose.jar

Note, that on Windows systems, all back slashes ("\") need to be converted to forward slashes ("/").

Start MATLAB. At the command prompt, verify that you are currently in the default MATLAB 'work' folder by typing the command pwd and hitting enter. MATLAB should return the following output (note this may vary depending on your installation).

>> pwd

ans =

C:\Program Files\MATLAB\R2006b\work

Add the MatGoose package directory to MATLAB's search path by typing the following commands.

addpath(genpath(fullfile(pwd, 'MatGoose')));
savepath

MatGoose is now installed.

Using MatGoose

> Top > Installing MatGoose > Using MatGoose > MatGoose and Octave

As a caution to prospective users, the MatGoose is currently in beta development and there may be a few bugs. If you find any, or have feature suggestions, please do not hesitate to report them in the Gaggle Issue Tracking System. That said, it is still quite functional, and should be equivalent to the current status of the RGoose. To ease usability, a graphical user interface written using MATLAB's GUIDE (GUI Development Environment) is planned for the official release.

For our intrepid beta testers ...

First, create an instance of the MatGoose object and connect to the Gaggle by issuing the following command in the MATLAB command window.

gaggleInit

You should now see a MatGoose object called mg in your base workspace. This should also autostart and connect to a Gaggle Boss (if one isn't already running). "Matlab" should now appear as an available goose in the Gaggle Boss.

Note it is important that you DO NOT issue a clear, or clear all command in MATLAB. This will destroy the instance of the MatGoose without terminating it's connection to the Gaggle. It will therefore become unavailable by both, while continuing to consume system memory. Instead use,

MatGooseClear

which is provided with the MatGoose package. The planned GUI interface will hopefully address this issue more elegantly.

To get a list of other active geese, type the following at the command line.

geese = getGeeseNames

This will produce a MATLAB cell array of strings containing the available geese names. By default, the initial target goose is set to 'all'. To change this to a specific goose use:

setTargetGoose(goosename)

You can verify that the target goose has been reset using

getTargetGoose

From another goose, say the DMV, broadcast a namelist. At the MATLAB command prompt, you should receive notification that a namelist has been received, along with its length. To retrieve the namelist type:

list = getNameList

You should see something similar as the following output at the command prompt.

list = 

    gaggleType: 'Namelist'
          name: []
      metadata: []
         names: {173x1 cell}
       species: 'Halobacterium sp. NRC-1'

To get other data types you can use the following methods.

matrix      = getDataMatrix
network     = getNetwork
cluster     = getCluster
gaggleTuple = getGaggleTuple

To rebroadcast the above namelist back to the Gaggle, type:

broadcast(list)

For that matter, the broadcast() method in MatGoose is overloaded, meaning it accepts all Gaggle data types as its sole argument. So all of the following lines will work.

broadcast(matrix)
broadcast(network)
broadcast(cluster)
broadcast(gaggleTuple)

Note, all MatGoose data retrieval and broadcast methods strictly work with Gaggle data types. Any new data that is generated in MATLAB that you wish to broadcast to the Gaggle must be cast into one of the predefined types. To do so you can use the following functions to create empty data containers that you can later fill.

list        = CreateNameList
matrix      = CreateDataMatrix
network     = CreateNetwork
cluster     = CreateCluster
gaggleTuple = CreateGaggleTuple

Note, the functions in red are not yet fully implemented at the time of this writing.

So a typical command sequence would look like the following.

% initialize MatGoose
gaggleInit;

% retrieve a namelist, say from the DMV
stList = getNameList;
.
.
% lines to process the namelist
.
.
% send the process namelist back, say to Cytoscape
setTargetGoose('Cytoscape');
broadcast(stList);

% terminate MatGoose session and clear the object from memory
disconnectFromGaggle;
clear mg;

The above example is admittedly an oversimplified scenario. For more advanced processing, all the utility functions from the RGoose have been ported to MATLAB with a few revisions. These include:

  • RGoose: allPositiveRowNames = MatGoose: allPositiveRows
  • filterVector is internalized in filterMatrix in MatGoose, and is no longer a stand-alone function
  • Where possible, function outputs are Gaggle data types - e.g. Namelist and DataMatrix - so that results can be immediately be rebroadcast back without extra manipulation.

More utility functions will become available as need arises, and suggestions from the user community during our development process are highly welcomed.

Noted Limitations

Tuple and GaggleTuple objects are only marginally supported at the moment. As such, they remain as their native Java Object classes when broadcast to MATLAB.

Networks broadcast to MatGoose come through as essentially a list of interactions and nodes. We are looking into converting Gaggle network data into GraphViz compatible objects for which there are various MATLAB toolboxes (e.g. the Bioinformatics Toolbox) that provide a rich set of analysis algorithms.

MatGoose and GNU Octave

> Top > Installing MatGoose > Using MatGoose > MatGoose and Octave

MatGoose does work with GNU Octave in the sense that a MatGoose object can be created and data can be broadcast to and from the Gaggle. However, there are various differences between the way Octave and MATLAB creates and accesses Java Objects. These differences, depending on their severity, may warrant a dedicated project for developing an Octave Goose based on MatGoose. For the time being, MatGoose on MATLAB will be the primary focus of development. Once it is more mature and reasonably stable, compatibility with Octave will be revisited.

© 2006, Institute for Systems Biology, All Rights Reserved
validate