SHRINE Ontology Mapping Tool (SHRIMP)

walkingceilInternet and Web Development

Oct 22, 2013 (3 years and 7 months ago)

63 views




SHRINE Ontology

Mapping Tool

(SHRIMP)





User Guide



SHRIMP User Guide



2





Document Version


Version

Author

Notes

0.1

Matvey Palchuk

Initial Draft

0.2

Philip Trevvett

Initial Draft Continued



SHRIMP User Guide



3

Table of Contents


Introduction

4

SHRINE Ontology

4

SHRINE Ontology Mapping

Tool

Overview

5

Authentication

7

Manage Users






SHRIMP User Guide



4

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 a
re
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 necessa
ry 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 Ra
ce & 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 foll
owing 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 acc
ount 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 assuran
ce 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 f
or each institution


SHRIMP User Guide



5

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 ca
n
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. F
ragments 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 fragme
nt 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 ar
e created that represent mappings FROM terms in local
fragments TO terms in core fragments. These mappings are stored in
a m
apping
table

that contain
s

the unique ID for each term, the relationship type,
the mapping
source
,
and
any comments

about the mappi
ng.
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
represent
ed

in
a
single Mapping File.


Interface for Mapping

Mappings between f
ragment 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 mappi
ngs and create new mappings between local and core fragment terms.


Mapping

T
ype

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


SHRIMP User Guide



6

clickin
g 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
mappi
ngs are created, unless the user specifies otherwise.

The “Default Mapping Type”
can be designated by clicking on the “Users” link and select
ing “Edit” for the appropriate
u
ser.



Output

Mapping Files can be downloaded that contain all mappings between an
y given site and
core fragments.
Mapping files are generated as XML files.









SHRIMP User Guide



7

Authentication





SHRIMP User Guide



8

Manage Users


The
“Users” page lists currently authorized users and allows

for authorized users

to

be
added
or remove
d

as well as
for

changes
to be made
to

existing user account
s
.


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” t
o 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 prese
nted. Cl
ick

“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 m
ay 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”




SHRIMP User Guide



9

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 institut
ion 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 pro
vided:



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 co
mplete changes.





SHRIMP User Guide



10

Manage Fragment Types



The “Manage Fragment Types” page lists all fragment types that may be associated with
fragments. Each fra
gment must be associated with a

fragment type
.
Mappings are
created between fragments sharing a common fra
gment type.


Add Fragment T
ype


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 Typ
e


To edit a fra
gment 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.



SHRIMP User Guide



11

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 f
ragment, 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 ba
sed 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




SHRIMP User Guide



12

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, externa
l 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 Col
umn: local key for the site fragment (Fragment being mappe
d

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: i
f 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 fragm
ent
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 importe
d 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 in
terest 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



SHRIMP User Guide



13



Number of Concepts (rows) in fragment.


Edit

Fragment

Details


To edi
t 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 selec
ted 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 mappin
gs 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 w
ill be saved as an XML
file.




SHRIMP User Guide



14

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 i
ndividual 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 t
he 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 fragmen
ts 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 th
e “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 yo
u are intending to remove this
mapping type

will be
presented. Click “yes” to confirm.