Terminology Mapping

Terminology Domain Mapping

FHIR Codings are generally defined by a "system", "code", and "description". Records in the OMOP CONCEPT table are mapped to a "vocabulary_id". There currently is not an official blessed mapping of FHIR "system" values to OMOP "vocabulary_id" values. A draft status list has been provided as described in this Stackoverflow post. The mapping file we are using is available here.

Code Mapping

FHIR codes are mapped to OMOP Concepts during the creation of the OmopPerson object by the OmopPersonFactory class.

The OmopPerson object is a simple Data Value Object with trivial getters and setters and a small number of convenience getters. All of the logic for how the OmopPerson object is created is in the OmopPersonBuiler class. The OmopPerson object is composed of Data Value Objects (DVOs) that are exactly mapped one-to-on to OMOP tables. The DVOs are created using a code generator by the GenerateOrm class. The DVOs are in the dvo package. The Builder classes for each of the OMOP tables are used to perform the mappings. These classes are in the builder packages.

All standard mappings are done by the FhirToOmopConceptMapper class. Race and Ethnicity mappings are a special case as FHIR has defined its own vocabulary for Race and Ethnicity and OMOP has defined their own vocabulary for Race and Ethnicity. Race and Ethnicity are mapped using a simple mapping of these terminologies to each other as described here.

FHIR systems and codes are mapped to OMOP concepts by the FhirToOmopConceptMapper class according to the following.

The FHIR System is resolved to an OMOP vocabulary_id using the mapping described above.
An OMOP standard concept matching the vocabulary_id and the code is queried for using the getStandardConcept method.
The following query is used:
```
select * from concept where vocabulary_id = ? and concept_code = ? and standard_concept = 'S'
```

A mapping to a standard concept matching the vocabulary_id and the code is queried for using the getStandardConceptFromMapping method. The following query is used:

select 
  con2.* 
from 
  concept_relationship rel 
  join concept con1 on con1.concept_id = rel.concept_id_1 
  join concept con2 on con2.concept_id = rel.concept_id_2 
where 1=1 
  and relationship_id = 'Maps to' 
  and con1.vocabulary_id = ? 
  and con1.concept_code = ? 
  and con2.standard_concept = 'S'

A non-standard concept matching the vocabulary_id and the code is queried for using the getNonStandardConcept method.
The following query is used:
```
select * from concept where vocabulary_id = ? and concept_code = ?
```
If no matching concept is found by any of the above methods, a new concept is created as one of the so called two-billionaires. (the new concept is given a concept_id that is > 2000000000).

Caching

A cache for FHIR to OMOP terminology mapping has been put in place. Concepts are added to the cache as they are found. The cache is queried prior to going to the database to get the concept. The cachc is implemented in the ConceptCache class.