SHRINE Ontology
Mapping Tool
(SHRIMP)
User Guide
SHRIMP User Guide
Document Version
Version
0.1
0.2
Author
Matvey Palchuk
Philip Trevvett
Notes
Initial Draft
Initial Draft Continued
2
SHRIMP User Guide
Table of Contents
Introduction 4
SHRINE Ontology 4
SHRINE Ontology Mapping Tool Overview 5
Authentication 7
Manage Users
3
SHRIMP User Guide
Introduction
Shared Health Research Information Network (SHRINE) allows execution of patient data
queries for research purposes across multiple i2b2 (http://www.i2b2.org) data
warehouses.
SHRINE Ontology
SHRINE currently makes patient demographics, diagnoses, medications and a sample of
laboratory results data available to be searched. SHRINE Core Ontology is a collection of
terms that describe these data and can be used to construct queries. The terms are
arranged into a hierarchy for easy navigation; the ontology can be searched for a
particular terms as well.
A standard terminology was selected (where possible) to represent each type of data
accessible via SHRINE. A terminology was modified as necessary to fit the requirements
of SHRINE. The following standard terminologies provide the baseline for the Core
ontology:




Demographics
o Age
o Gender - HL7 Administrative Gender
o Language - ISO 639-1
o Marital Status - HL7 Marital Status
o Race and Ethnicity - CDC Race & Ethnicity Code Sets
o Religion - HL7 Religious Affiliation
o Vital Status
Diagnoses - ICD-9-CM and CCS hierarchy
Lab Tests (demo) - LOINC and Partners HealthCare hierarchy
Medications - RxNorm and NDF-RT hierarchy
The Core ontology was constructed following recommendations of relevant government
and private sector bodies and relies on the best standards available at the time of
construction. However, the approach to Core ontology was pragmatic - availability of
underlying patient data was taken into account when selecting standards; absence of a
standard in a particular domain required creating our own; various stages of completion
of some standards still in progress of being created also impacts the Core ontology.
The Core ontology is a static snapshot of underlying standards. As they change (for
example, regular updates of ICD-9-CM and RxNorm), we expect that the Core ontology
will follow after a reasonable delay to accommodate the effort of introducing the
changes, resolving issues and quality assurance processes.
Each participating institution's data is loaded with native coding schemes used by local
information technology solutions. In order to understand SHRINE queries issued using
terms from the Core ontology, a mapping is created and maintained for each institution
4
SHRIMP User Guide
which allows a translation from SHRINE Core ontology term to a corresponding local
one in order to perform a query at the institution. While every effort was made during
creation of mapping files and their testing to faithfully preserve the meaning of data, as
with any mapping exercise, there may be instances where the translation between
SHRINE Core ontology and local hospital's data is not perfect.
SHRINE Ontology Mapping Tool
SHRINE Ontology Mapping Tool (SHRIMP) is a web-based tool designed to create and
manage association mappings between standard vocabularies comprising SHRINE Core
Ontology and vocabularies used by individual SHRINE sites.
Fragments
Individual vocabularies used by SHRIMP are referred to as fragments. Fragments can
either be core or local. A core fragment contains the terms from the core ontology to
which local terms are mapped. Each data type (age, gender, diagnoses, etc) has one core
fragment that represents all terms of that type in the core ontology. A local fragment
represents the terms of any data type used by a local institution. Fragments do not
display folders that hold sets of terms and therefore do not represent hierarchies of either
the SHRINE Core ontology or local institutions.
Concepts
Each fragment is made up of a set of items known as concepts. Concepts are the specific
terms or instances between which all mappings in SHRIMP are created. Each concept
may have a set of attributes associated with it, and may also be mapped to any number of
other concepts. 5 different site concepts may be mapped to a single core concept, and
similarly, 5 different core concepts may be mapped to a single site concept, depending on
which fragment contains more granular concepts.
Mapping Files
Association mappings are created that represent mappings FROM terms in local
fragments TO terms in core fragments. These mappings are stored in a mapping table
that contains the unique ID for each term, the relationship type, the mapping source, and
any comments about the mapping. Mappings may be created within SHRIMP or
imported from an already existing file. The set of all mappings between a single local
fragment and a single core fragment can be represented in a single Mapping File.
Interface for Mapping
Mappings between fragment terms can be managed individually through the mapping
interface. This interface allows the user to select a term from a local fragment, search the
corresponding core fragment for relevant terms, view all mappings already created,
destroy old mappings and create new mappings between local and core fragment terms.
Mapping Type
Mappings between local terms and core terms represent specific relationships such as
synonym, has ingredient, etc. New relationships can be created within the tool by
5
SHRIMP User Guide
clicking on the “Manage Mapping Types” link. When creating a new mapping between
terms, the user can select what type of relationship the mapping represents. The user can
also designate a “Default Mapping Type” to represent a certain relationship whenever
mappings are created, unless the user specifies otherwise. The “Default Mapping Type”
can be designated by clicking on the “Users” link and selecting “Edit” for the appropriate
user.
Output
Mapping Files can be downloaded that contain all mappings between any given site and
core fragments. Mapping files are generated as XML files.
6
SHRIMP User Guide
Authentication
7
SHRIMP User Guide
Manage Users
The “Users” page lists currently authorized users and allows for authorized users to be
added or removed as well as for changes to be made to existing user accounts.
Add User
To add a user, click “New User” at the bottom of the page. The following information
can be provided:
 First name
o Required
 Last name
o Required
 E-mail
o Required
 Default Mapping Type
 Username
o Required
o Click “Add Username” to input this information
Click “Create” button when finished to complete adding a new user.
Remove User
To remove a user, click “Destroy” link next to user’s name. A dialog box confirming that
you are intending to remove this user will be presented. Click “yes” to confirm.
Edit User
To edit user account information, click “Edit” next to user’s name. The following
information can be changed:
 First name
 Last name
 E-mail address
 Default Mapping Type
o See Manage Mapping Types for more information
o A user may choose a default mapping type based on the kind of mapping
activity they are performing. For example, if the preponderance of
mappings creates a “synonym” relationship, the default mapping type
should be set accordingly.
o By default, the value is set to “synonym”
8
SHRIMP User Guide
Manage Institutions
The “Manage Institutions” page lists all institutions associated with fragments. Each
fragment must be associated with an institution. Core fragments, as part of the SHRINE
Core ontology, are associated with the institution named “Core”. Each institution can be
associated with multiple fragment types and with multiple fragments of the same type.
Add Institution
To add an instution, click “New institution” at the bottom of the page. The following
information can be provided:
 Institution Name
o Required
Click “Create” button when finished to complete adding a new institution.
Remove Institution
To remove an institution, click “Destroy” link next to Institution’s name.
A dialog box confirming that you are intending to remove this institution will be
presented. Click “yes” to confirm.
Edit Institution
To edit an institution name, click “Edit” next to institution’s name. The following page
will allow the user to change the name of the institution.
Click “Update” to complete changes.
9
SHRIMP User Guide
Manage Fragment Types
The “Manage Fragment Types” page lists all fragment types that may be associated with
fragments. Each fragment must be associated with a fragment type. Mappings are
created between fragments sharing a common fragment type.
Add Fragment Type
To add a fragment type, click “New fragment type” at the bottom of the page. The
following information can be provided:
 Fragment type Name
o Required
Click “Create” button when finished to complete adding a new institution.
Remove Fragment Type
To remove a fragment type, click “Destroy” link next to Fragment type’s name.
A dialog box confirming that you are intending to remove this fragment type will be
presented. Click “yes” to confirm.
Edit Fragment Type
To edit a fragment type name, click “Edit” next to institution’s name. The following page
will allow the user to change the name of the fragment type.
Click “Update” to complete changes.
10
SHRIMP User Guide
Manage Fragments
The “Manage Fragments” page lists all fragments that have been loaded into SHRIMP.
From this page, the user can add or remove fragments, change the associated fragment
type and institution, view fragment attributes, and import, view, and Download
associated mappings.
Import a Fragment
To import a core fragment, a new fragment record needs to be created, and an external
file selected for importing.
Click “New fragment” at the bottom of the page. The following information can be
provided:
 Fragment Name
o Required
 Institution
o Required
o Structured drop-down selection based on Institutions already created
 Fragment type
o Required
o Structured drop-down selection based on fragment types already created
Click “Browse” to find the file to be importing. SHRIMP has the following requirements
for any fragment being imported:
 CSV Format
 First row should specify column names.
 First two columns have already defined names, and files should be ordered
accordingly
 First column is “local key” (unique ID).
 Second column is Concept Name
 At least one additional attribute field is necessary
o As many as needed can be included.
 Following local key and concept name, all other attributes will be ordered for display
first numerically and then alphabetically (1 before A, A before B)
Once the file has been selected to upload, click the “Save” button.
Core Fragments
If the file being uploaded is a core fragment—the set of selected terms to which other
files are being mapped—then select “Core” as the institution.
Site Fragments
11
SHRIMP User Guide
If the file being uploaded is a site fragment—a set of terms that will be mapped to the
standard, core terms—then select the appropriate non-core institution (the source of any
such fragment should already be entered as an Institution so that it may be selected here).
Import Pre-generated Mappings
For any fragment, external mappings may be imported mapping terms in a site fragment
to terms in a core fragment. All external mappings must be in the following format in
order to be imported:
 CSV Format
 No Column headings: the first row of the file should be a data row
 First Column: local key for the site fragment (Fragment being mapped FROM)
o Required
 Second Column: local key for core fragment (Fragment being mapped TO)
 Third Column: Mapping Type ID
o Optional
o Default mapping type is synonym
 Fourth Column: comments
o Optional
 NOTE: if comments are included, it is necessary that the third column is present, even
if blank.
To import externally generated mappings, click the “Import Mappings” link from the row
of the fragment being mapped FROM. On the page that appears, select the fragment
being mapped TO from the drop-down list; then click “Browse” so select the .csv file that
contains the appropriate mappings. Once the file has been selected, click “Import” to
load the mappings.
Additional Notes:
 Multiple mapping files can be imported for the same site and core fragments.
 Mappings from site concepts to core concepts, where the core concept does not exist
are not deleted. They are still stored as mappings associated with the site fragment
o This is noteworthy because of the potential interest in preserving
mappings when updating fragment versions (New fragment version
includes new local keys that match with previously invalid mappings).
 When a fragment is removed, all associated mappings are also deleted.
View Fragment Details
To view details associated with a fragment, click the “Show” link in the row of the
appropriate fragment. The following details will be shown:
 Fragment Name
 Associated Institution
 Fragment Type
12
SHRIMP User Guide

Number of Concepts (rows) in fragment.
Edit Fragment Details
To edit the attributes of a given fragment, click the “Edit” link in the row of the
appropriate fragment. The following details can be edited:
 Fragment Name
 Associated Institution
 Fragment Type
Click the “Update” button to save changes
Note: Changing fragment type will not impact any mappings that have already been
generated (internally or externally): mappings to core fragment of previous fragment type
will not be deleted. However, upon update of fragment type, new mappings will be
limited to the newly selected fragment type.
Remove a Fragment
To remove a fragment, click “Destroy” link in the row of the appropriate Fragment.
A dialog box confirming that you are intending to remove this fragment will be
presented. Click “yes” to confirm.
Note: All mappings associated with a fragment will also be destroyed.
View Mappings
To view existing mappings for a fragment, click the “View Mappings” link in the row of
the appropriate fragment. The subsequent page will show each concept in the selected
fragment for which mappings exist, and each concept in the core fragment to which it has
been mapped.
Download Mappings
To export all existing mappings for a given fragment, click the “Download Mappings”
link in the row of the appropriate fragment. These mappings will be saved as an XML
file.
13
SHRIMP User Guide
Manage Mapping Types
Mapping types are used to represent the relationship between the term being mapped
FROM (in the site fragment) and the term being mapped TO (in the core fragment).
Mapping type can be determined on an individual basis per mapping (when individual
mappings are created through the mapper interface), or by inclusion of a mapping type id
when importing files. A default mapping type can also be set for a given user, so that
individual mappings created with the mapper will have a default mapping type if no other
type is specified. In order to represent a relationship that does not already exist, a new
mapping type must be created in the “Manage_Mapping_Types” window.
Add Mapping Type
To add a mapping type, click the “New mapping_type” link at the bottom of the page. In
the Name box, enter the name of the relationship. Click the “Create” button to save the
new mapping type.
Note: Because these mapping types will define the relationships between all fragments in
SHRIMP, it is useful to limit the types of relationships available, and to remain consistent
with standard and reuseable relationship names and definitions.
Show Mapping Type Details
To view attributes associated with a given mapping type, click the “Show” link next to
the appropriate mapping type. The following details will be provided:
 Mapping Type ID
o This is used when importing mapping and specifying mapping type
 Name
Edit Mapping Type
To edit a mapping type, click the “Edit” link next to the appropriate mapping type. The
Following details can be edited:
 Name
Click the “Update” button to save changes.
Remove Mapping Type
To Remove a mapping type, click the “Destroy” link next to the appropriate mapping
type.
A dialog box confirming that you are intending to remove this mapping type will be
presented. Click “yes” to confirm.
14