SHRINE 4.1.0 Chapter 10.2 - Configuring the Adapter Mappings File

SHRINE uses a mappings file to convert network queries to queries that match your local i2b2. This mappings file maps each term in the SHRINE Demo ontology to a term (or terms) in the i2b2 ontology. This can be a "one-to-one" mapping, when the SHRINE and i2b2 concepts are semantically equivalent, or a "one-to-many" mapping, where one SHRINE concept is equivalent to multiple concepts in the local i2b2 ontology. When the SHRINE ontology and local i2b2 ontology are the same, the adaptermappings file will be made up entirely of one-to-one mappings.

Find the AdapterMappings.csv distributed with your network ontology. You should place it in the /opt/shrine/tomcat/lib directory on the SHRINE host. 

The AdapterMappings.csv file for a default SHRINE install (using the demo ontology) can be downloaded from https://shrine-ontologies.s3.amazonaws.com/demo/releases/AdapterMappings-DEMO-SHRINE-4.0.0.csv .

Depending on the details of your SHRINE network and your local i2b2, you may need to change or edit AdapterMappings.csv.  If terms used by your SHRINE network are different from the demo ontology you will need to start with your network's default AdapterMappings.csv file (or create one). If the terms in your i2b2 differ from your network's terms you will need to modify that default AdapterMappings.csv file for your specific node. (See below to understand the basic steps for editing/customizing the Adaptermappings file)

If you change the name of the ontology file from the default name AdapterMappings.csv, you will need to configure SHRINE to use this file by setting the adapterMappingsFileName value to the name of that file in shrine.conf's adapter section:

shrine { 
...
  adapter {
...
    adapterMappingsFileName = "RenamedAdapterMappings.csv"
...
  }
...
} 

How and When to edit or change an AdapterMappings file.

It is critical that your SHRINE host is using an AdapterMappings file that is specific to the network and local i2b2 that you are working with. If your network ontology and local i2b2 ontology are the same, then you can use a one-to-one mapping file, or create one if one does not already exist. (A one-to-one mapping file should generally be provided by whoever is setting up the network/releasing the network ontology.)

To create a 1-to-1 AdapterMappings file:

(To be used when the SHRINE and i2b2 ontology are the same)

The end product will be a 2 column csv file, with the same strings in both columns (a 1-to-1 mapping).

Column 1 represents concepts in the SHRINE (network) ontology, and is created by prepending “\\” AND the appropriate C_TABLE_CD value from the network ontology’s TABLE_ACCESS table to the C_FULLNAME field from the metadata tables. (These values can be accessed by referring to the SHRINE ontology source files used to generate SHRINE indices.)

For example:

“\i2b2\Demographics\Age\0-9 years old\”

Is preprended with “\\i2b2_DEMO”

Which creates “\\i2b2_DEMO\i2b2\Demographics\Age\0-9 years old\”

Column 2 represents the concepts in your local i2b2 ontology. Where the concepts are the same in the network and local ontology, then the same values that appear in column 1 should appear in column 2.

Here is a example sql query for creating the 1-to-1 Adaptermappings from the ontology and table access tables:

select '\\' || ta.c_table_cd || ont.c_fullname as key,
       '\\' || ta.c_table_cd || ont.c_fullname as local_key
  from ONT_TABLE1 ont
  join table_access ta on substr(ont.c_fullname,1,length(ta.c_fullname)) = ta.c_fullname
  where ont.c_visualattributes not in ('FH','FI','LH','LI')
  UNION
  select '\\' || ta.c_table_cd || ont.c_fullname as key,
       '\\' || ta.c_table_cd || ont.c_fullname as local_key
  from ONT_TABLE2 ont
  join table_access ta on substr(ont.c_fullname,1,length(ta.c_fullname)) = ta.c_fullname
  where ont.c_visualattributes not in ('FH','FI','LH','LI')
  UNION
  select '\\' || ta.c_table_cd || ont.c_fullname as key,
       '\\' || ta.c_table_cd || ont.c_fullname as local_key
  from ONT_TABLE3 ont
  join table_access ta on substr(ont.c_fullname,1,length(ta.c_fullname)) = ta.c_fullname
  where ont.c_visualattributes not in ('FH','FI','LH','LI')

etc.. (continued for each ontology table)

NOTE: If your local concepts are the same, but your local TABLE_ACCESS table uses different C_TABLE_CD values, then you will need to edit the prepended C_TABLE_CD values for column 2

When your local ontology is not the same as the SHRINE network ontology:

If your local ontology does not match the network ontology, then you will need to customize your mappings between the two ontologies. This work will need to be done locally, since it involves mapping to local concepts that wouldn’t be accessible/visible to the rest of the network.

While each customized mapping effort will be unique to the local ontology, here are a few basic practices to keep in mind:

• As with a 1-to-1 mapping file, C_FULLNAME values will need to be prepended with “\\” AND the appropriate C_TABLE_CD value from each TABLE_ACCESS. (Column 1 values will be prepended with the appropriate C_TABLE_CD from the SHRINE Network ontology’s TABLE_ACCESS Table, and Column 2 will be prepended with the appropriate C_TABLE_CD from the local i2b2 TABLE_ACCESS Table.
• 1-to-Many mappings may be necessary when managing a custom mapping file
• When hierarchical folders do not align between ontologies, the hierarchical folders in the network ontology will need to be mapped to the appropriate set of specific concepts. (When a corresponding folder does not exist in the local ontology).
• Concepts that have the following C_VISUALATTRIBUTE values do not need to be mapped: FH, FI, LH, LI.
• These concepts cannot be included in a SHRINE query, so do not need to be mapped.