Correlation Analysis Cell: Developer’s Guide

Version 1.0

The guide provides installation and source code compilation and building steps for the Correlation Analysis Cell of the i2b2 hive. This specialized analysis cell uses mutual information theory to calculate observed correlations within the data of the hive. This type of cell represents an important achievement of the hive.

1. Prerequisites and Third-Party Software

Downloads and Installation

a. i2b2 Workbench version 1.2.1

Download i2b2 Workbench version 1.2.1 (i2b2Workbench-src-121.zip) from https://www.i2b2.org/software/repository.html?t=demo&p=14 Follow installation and configuration instructions as given in the i2b2 Workbench Developers’ Guide v1.2.1 which can be found under the Docs tab.

b. Java JDK 5.0 – needed for i2b2 Workbench

This version of the DJK is needed for running the Eclipse Workbench.

Download JDK 5.0 Update 11 (jdk-1_5_0_11-windows-i586-p.exe) from http://java.sun.com/products/archive/un the installer. Set up JAVA_HOME and CLASSPATH environment variables after installation.

c. Eclipse

You will need to use version 3.2.1 of the Eclipse SDK (eclipse-SDK-3.2.1-win32.zip), which can be found at http://archive.eclipse.org/eclipse/downloads. If you install Eclipse, be sure to install it in an area separate from any previous Eclipse installations.

To install, extract the zip file into a directory on local disk. Create a local desktop shortcut to eclipse.exe.

d. yEd Graph Editor

The Correlation Analysis Cell uses the yWorks’ yED Graph Editor for viewing and editing Relevance Networks graph files. Download the most recent version for your platform available at http://www.yworks.com/en/products_yed_about.html. After installing, make sure the GRAPHML file format is opened by default by yEd.

2. Install & Configure

Setting up the Correlation Analysis Cell within the i2b2Workbench 1.2.1

You should have already installed the Eclipse 3.2.1 environment and imported the i2b2 Workbench v1.2.1 set of projects into it as detailed in the i2b2 Workbench Developers’ Guide v1.2.1.

Importing the Correlation Analysis project

This project software is contained in the Eclipse archive file called “edu.harvard.i2b2.eclipse.plugins.CorrelationAnalysis.zip” which can be downloaded from the i2b2 web site.

From the File Menu of the i2b2 Workbench select Import->General->Existing Project into Workspace and navigate to the place where the archive was saved to disk. The archive contains a single Eclipse plug-in Project called “CorrelationAnalysis”.

Click Finish and let the i2b2 Workbench import the Correlation Analysis archive. When done, you should see something similar to the screen-shot below.

Building the Correlation Analysis Project within the i2b2 Workbench

Check your Java Complier settings. Choose Project->Properties from the main drop down menu. Click on ‘Java Compiler’ next. Verify that Compiler compliance level is set to 5.0. If not, select it from the drop-down menu and select Apply->OK.

Running the Correlation Analysis plug-in within the i2b2Workbench

Change amount of memory allocated to JVM

Display current run-time configuration parameters by selecting Run from the i2b2 Workbench menus and choosing the Run… option. Select the Arguments tab on the right. Add these suggested memory management settings to the VM arguments area:

-Xms96M -Xmx1024M

First corresponds to the starting and second to maximum size of the heap size the JVM operates with. When not enough heap space, JVM will throw following error: Exception in thread "main" java.lang.OutOfMemoryError: Java heap space.

NOTE: the maximum heap size of 1024 M would normally correspond to a total of 1.5 GB or more physical RAM available on a Windows-based platform. For other platforms or when different amount of physical memory is available, please make changes to these suggested numbers accordingly.

Select Apply and Close.

Move configuration files to the working directory of edu.harvard.i2b2.eclipse

Move the following configuration files to the edu.harvard.i2b2.eclipse directory:

corr_cell.properties
corr_cell_chronicdgns.txt
DEMO_LABS.xml

The files are be located in the folder Configuration Files under the root of the archive for the Correlation Analysis project or will be supplied as a separate downloadable archive clearly marked “Configuration Files” off the main download URL for the package.

Update the plugin.xml file in the edu.harvard.i2b2.eclipse directory.

Make the following change to the plugin.xml file in the main working directory so that the Correlation Analysis Cell is selectable from the Window->Show view menu of the i2b2 Workbench.

Add

<viewShortcut
id="ca.views.CAView"/>

in the section

<perspectiveExtension targetID="edu.harvard.i2b2.eclipse.perspective">

Run the application by clicking on the Run menu button. One should see a similar to this screen shot configuration of windows.

4. License

The Correlation Analysis source code is licensed under the i2b2 Software License Program.
For the i2b2 Workbench source code agreement and coverage consult the i2b2 Workbench Developers’ Guide v1.2.1.

References

1. The original document is available at https://www.i2b2.org/software/files/PDF/current/Correlation_Analysis_Cell_Developers_Guide.pdf