Correlation Analysis Cell: Installation Guide

Plugin Version 1.0

i2b2 Version 1.3

The guide provides installation 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

If you do not already have a copy of the i2b2Workbench, download it from https://www.i2b2.org/software/repository.html?t=demo&p=14. Follow installation and configuration instructions for the binary distribution as given in the i2b2 Workbench User’s Guide which can be found under the Docs tab.

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

a. Downloading the JAR archive and Configuration Files

This project software is contained in an Eclipse archive file called CA_1.0.0.jar which can be downloaded from the i2b2 web site. There will be another, clearly marked ZIP archive which contains configuration files. Its name is Configuration.ZIP.

b. Copy JAR archive to the plugins directory

As a first step, identify the location of your i2b2workbench executable file. It will contain i2b2workbench.exe file and the i2b2workbench.properties file (see the screen shot below)
Unpack the JAR archive file CA_1.0.0.jar. Locate the i2b2workbench plugins directory and move it there.

In the case shown here, the main i2b2 Workbench directory is C:\e3.3\i2b2w1.3\CorrDeploy\eclipse.

Unpack the configuration files in a temporary location and move them to this directory. This will allow the Correlation Analysis plug-in to find its necessary configuration files at run-time. This is the list of files you will find in the configuration archive that need to be moved to the workbench directory:

corr_cell.properties
corr_cell_chronicdgns.txt
DEMO_LABS.xml

c. Modify Java Run-time memory configuration

Open the file i2b2Workbench.ini located in the main directory of the i2b2 Workbench. Edit its content to reflect the memory configuration needed for this application.

-vmargs
-Djava.endorsed.dirs=endorsed_lib
-Xms40m
-Xmx1G

The –Xms and –Xmx settings correspond 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 1G 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.

d. Run the Workbench.

Log into the Harvard Demo target location.

Select the Correlation Analysis view: Window->Show Views->Other->i2b2->Correlation Analysis Cell

One should see a similar to this screen shot configuration of windows.

Please consult the Correlation Analysis Cell User’s Guide and / or Tutorial for assistance in using this plugin.

References

1. Original document (for all releases) https://www.i2b2.org/software/files/PDF/current/Correlation_Analysis_Cell_Installation_Guide.pdf