Ontology Tools
Space shortcuts
Space Tools

Informatics for Integrating Biology and the Bedside

 

 

 

 

 

 

User Guide

Ontology Mapping Tools

for PCORI

 

 

 

 

 

 

 

 

 

Document Version:

1.0

i2b2 Software Version:

1.0

 

Table of Contents

Document Management

Abstract

1. before YOu Begin

1.1 Prerequisites

2. InstallATION and Preparation

2.1 Data installation

2.2 MAP cell installation

2.2.1 Using the VM’s hive

2.2.2 Using Your Local Hive

2.3 Workbench installation

2.3.1 Plugins

3. START the WORKBENCH

3.1 Starting the workbench

3.2 Familiarize yourself with the Mapping tool

3.2.1 Integration Tool tab

3.2.2 Export Tool tab

3.2.3 Import Tool tab

3.3 The Mapped Terms Viewer

Document Management

 

Revision Number

Date

Author

Description of change

1.0

08/05/14

Lori Phillips

Original document

1.1

01/13/15

Lori Phillips

Export tool tab options

 

 

Abstract

This is a User’s Guide for the Ontology Mapping Tools.  It is meant to be used in conjunction with the Mapping Tools Overview power point slides. 

 

 

  1. before YOu Begin

The use case shown in this guide represents the map demo data that is provided in both the data package and on the VM.  It does not match the use case shown in the overview slides. 

1.1         Prerequisites

If not using the Mapping demo VM, a working 1.7 i2b2 hive instance is required.  It is recommended that you create a project for mapping purposes but it is not mandatory.  Any user assigned to and expected to use the mapping tools must have EDITOR role privileges.

A 1.7 workbench is also required.  Two mapping plugins are provided in this package.

 

  1. Install ATION and Preparation

 

The MAP cell is provided in two formats:

  1. A VM with demo mapping data.
  2. A set of MAP cell jars.

 

As a user you have two choices:

  1. Use the VM’s hive, but direct it to your own database tables.
  2. Update your hive to include the MAP cell.

 

The VM is seeded with demo mapping data.  You may use this to sanity check the installation of the workbench plugins &/or use it as a training platform. 

 

2.1         Data installation

      Refer to the i2b2 Ontology Mapper Data Installation Guide for PCORI.

 

2.2         MAP cell installation

2.2.1 Using the VM’s hive

The VM is pre-configured with the MAP cell and demo mapping data. If you decide to use the VM as your MAP cell source, you need to redirect it to your database. It is recommended that you first validate the installation of the workbench plugins (section 2.3) before doing so.

Login credentials to the VM are tomcat/demouser.  The VM has a postgresql database residing on it.   All database passwords on the VM are ‘demouser’.  Map data is provided in schema i2b2mapdata.  Database credentials are i2b2mapdata/demouser.

To direct the VM to your database, edit the following file.

Datasources

cd /opt/jboss-as-7.1.1.Final/standalone/deployments

Edit the file ontmap-ds.xml  

Modify the OntologyMapDemoDS datasource to point to your database.

Do not modify the entry for OntologyMapperBootStrapDS.

 

2.2.2 Using Your Local Hive

Included in this package is a folder called edu.harvard.i2b2.ontology.mapper.  This folder contains ant scripts to deliver MAP cell jars and information to the hive.

Please consult the PCORI Ontology Mapping Installation Guide to install and configure the MAP cell and plugins.

When complete, return to section 3.2 of this document.

 

2.3         Workbench installation

Start with a working 1.7 workbench.  If you don’t have one, it can be found here https://www.i2b2.org/software/#downloadables under Client Software.

If not previously done, configure the workbench to connect to the hive where the MAP cell was installed.  To do this add a line to the i2b2workbench.properties file

I2b2.2=i2b2demo,REST,http://yourHost/i2b2/services/PMService/

If you are using the VM, the VM’s start up page provides this line of information.

2.3.1 Plugins

Two plugins are provided in this package.  Drop them into the plugins directory of your workbench.

The plugins are:

edu.harvard.i2b2.eclipse.plugins.mappingTool_1.7.0.jar

edu.harvard.i2b2.eclipse.plugins.mappingViewer_1.7.0.jar

 

 

 

 

 

 

 

 

 

 

  1. START the WORKBENCH
    1.     Starting the workbench

Double click on the i2b2workbench application.

The first time you start up the workbench you will see a welcome screen. Click on the arrow.

The views you need to perform mapping tasks (those shown in the Overview slides) can be brought to focus by selecting:

Windows->Show view->Other-> Mapping category->Mapping Tool

and

Windows->Show view->Other->Mapping Viewer category->Mapped Terms Viewer

It is recommended to close all other views (Previous Queries, Query Tool, Workplace, Timeline, etc).  Map demo data provided on the vm is shown in the summary below. For ease of use, arrange your workbench window as shown. 

 

3.2         Familiarize yourself with the Mapping tool

The Map demo data package on the VM and provided in the data package is very small. When you click on tab 1.Mapping Tool, you will see a navigation tree on the left and a list of 4 unmapped terms on the right.  Both mapped and unmapped Diabetes-related terms are in this demo package. 

To find the Mapped terms traverse down the tree as follows:

ICD9CM->Diseases and injuries->Endocrine,nutritional and metabolic diseases…->

Diseases of other endocrine glands -> Diabetes mellitus

-OR-

Type Diabetes in the Jump To term field and select ‘Diabetes mellitus’ in the pop up window.  The tree will open directly to that term.

 

Open some of the folders under Diabetes mellitus and you will see mapped terms in bold prefaced by a purple flag.

 

As shown in the Overview slides, the mapped terms can be moved, copied and pasted, mapped, unmapped, verified, etc. Practice mapping some of the unmapped terms and play with the functions.  Bold face concepts are unverified mappings; once they are verified they change to regular type face.

One thing to remember in this exercise is that we are not equating or mapping terms in the true sense; i.e. we are not necessarily saying the terms are equal.  We are placing the terms in their proper hierarchical order, such that if we selected the parent term for a query, the mapped term would be included.   

 

3.2.1 Integration Tool tab

Once mappings are completed and have been verified, the next step is to merge the mapped terms into your destination ontology located in the INTEGRATION table.

 

 

The lone input to this process is the choice of a path symbol format (S, M, L).  A sample path symbol is highlighted below.  It can be Short (4 chars), Medium (20-chars) or Long (32 chars). The example below is Long.

\i2b2\Diagnoses\Metabolic and immunity disorders (270-279)\

(277) Other and unspecified disor~ \(277-0) Cystic fibrosis\

 

To activate the integration process, simply click the Start Integration button and then Refresh Process Status until the status displays complete as shown below.

 

  • Note: There is an additional PCORI-specific step that has to performed to update the PCORI_BASECODE for all mapped terms.  We will be releasing a separate script/tool to perform this task.

 

 

3.2.2 Export Tool tab

When the integration process is complete you may export your merged ontology as a delimited text file. This file may then be used to populate a metadata table. The data exported by this tool is the INTEGRATION table content.

 

 

The input parameters on this screen are output file name, EOL (end-of-line) qualifier, column delimiter, text qualifier and output format.  Be sure to set the output format to PCORNET.  This will ensure that the PCORI_BASECODE column is populated.  All other inputs are up to you.

Begin the export process by clicking on ‘Start Export’. The progress bar will let you know when the process is complete.  The resulting output file may then be loaded into an i2b2 metadata table.

 

 

3.2.3 Import Tool tab

The Import tool may be used to import local data into the project_ont_mapping table.  The data must be entered in manually so it is intended for small data sets.  All entered data will appear in the unmapped terms table. 

 

 

 

Enter data into either the table on the left directly or into the staging area on the right.  The staging area is provided for those cutting and pasting tab-delimited data from another source. If using the staging area, click on the Transfer button to move the data into the table on the left.

Once the table on the left is populated to your satisfaction, click on the ‘Upload’ button.  Refresh the Unmapped Terms table on tab 1 by clicking on the ‘Get All’ button. The terms you just uploaded will appear.

 

3.3         The Mapped Terms Viewer

The Mapped Terms Viewer allows to you look at the content of the project_ont_mapping table.  It is intended as a companion tool of the Mapping Tool and provides another method to review your mappings.

You may acquire the entire content of the project_ont_mapping table (Get All) or search for terms of interest by Standard code or Standard Name; Local code or Local name.  In this tool ‘Standard’ refers to the target/destination ontology and ‘Local’ refers to the terms you are mapping. You may also sort the table content clicking on the table’s column headings. For instance to sort the table by Local Name, click on the column heading “Local Name’ 

One handy use for this tool is look up mapped terms similar to ones you have left to map.  Our example, although small, shows that prior Diabetes-related terms were mapped to Standard code ICD9:250.00 and ICD9:250.01.  This information may be used as a suggestion on where to map the remaining unmapped terms.