N3C-Formatted OMOP2OBO Mappings

OMOP2OBO Mappings - N3C OMOP to OBO Working group

This repository stores OMOP2OBO mappings which have been processed for use within the National COVID Cohort Collaborative (N3C) Enclave. The version of the mappings stored in this repository have been specifically formatted for use within the N3C Enclave.

N3C OMOP to OBO Working Group: https://covid.cd2h.org/ontology

Accessing the N3C-Formatted Mappings 

You can access the three OMOP2OBO HPO mapping files in the Enclave from the Knowledge store using the following link: https://unite.nih.gov/workspace/compass/view/ri.compass.main.folder.1719efcf-9a87-484f-9a67-be6a29598567.

The mapping set includes three files, but you only need to merge the following two files with existing data in the Enclave in order to be able to create the concept sets:

OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv

OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv

The first file OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv, contains columns for the OMOP concept ids and codes as well as specifies information like whether or not the OMOP concept’s descendants should be included when deriving the concept sets (defaults to FALSE). The other file OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv, contains details on the mapping’s label (i.e., the HPO curie and label in the concept_set_id field) and its provenance/evidence (the specific column to access for this information is called intention).

Creating Concept Sets

Merge these files together on the column named codeset_id and then join them with existing Enclave tables like concept and condition_occurrence to populate the actual concept sets. The name of the concept set can be obtained from the OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv file and is stored as a string in the column called concept_set_id. Although not ideal (but is the best way to approach this currently given what fields are available in the Enclave), to get the HPO CURIE and label will require applying a regex to this column.

An example mapping is shown below (highlighting some of the most useful columns):

codeset_id: 900000000
concept_set_id: [OMOP2OBO] hp_0002031-abnormal_esophagus_morphology
concept: 23868
code: 69771008
codeSystem: SNOMED
includeDescendants: False
intention:

Mixed - This mapping was created using the OMOP2OBO mapping algorithm (https://github.com/callahantiff/OMOP2OBO).

The Mapping Category and Evidence supporting the mappings are provided below, by OMOP concept:

23868
*******

Mapping Category: Automatic Exact - Concept
------------------------------------------------

Mapping Provenance
------------------
OBO_DbXref-OMOP_ANCESTOR_SOURCE_CODE:snomed_69771008 | OBO_DbXref-OMOP_CONCEPT_SOURCE_CODE:snomed_69771008 | CONCEPT_SIMILARITY:HP_0002031_0.713

Release Notes - v2.0.0

Preparation

In order to import data into the Enclave, the following items are needed:

Obtain API Token, which will be included in the authorization header (stored as GitHub Secret)

Obtain username hash from the Enclave

OMOP2OBO Mappings (v1.5.0)

Data

Concept Set Container (concept_set_container): CreateNewConceptSet

Concept Set Version (code_sets): CreateNewDraftOMOPConceptSetVersion

Concept Set Expression Items (concept_set_version_item): addCodeAsVersionExpression

Script

n3c_mapping_conversion.py

Generated Output

Need to have the codeset_id filled from self-generation (ideally, from a conserved range) prior to beginning any of the API steps. The current list of assigned identifiers is stored in the file named omop2obo_enclave_codeset_id_dict_v2.0.0.json. Note that in order to accommodate the 1:Many mappings the codeset ids were re-generated and rather than being ampped to HPO concepts, they are mapped to SNOMED-CT concepts. This creates a cleaner mapping and will easily scale to future mapping builds.

To be consistent with OMOP tools, specifically Atlas, we have also created Atlas-formatted json files for each mapping, which are stored in the zipped directory named atlas_json_files_v2.0.0.zip. Note that as mentioned above, to enable the representation of 1:Many mappings the filenames are no longer named after HPO concepts they are now named with the OMOP concept_id and label and additional fields have been added within the JSON files that includes the HPO ids, labels, mapping category, mapping logic, and mapping evidence.

File 1: concept_set_container

Generated Data: OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_container.csv

Columns:

concept_set_id

concept_set_name

intention

assigned_informatician

assigned_sme

project_id

status

stage

n3c_reviewer

alias

archived

created_by

created_at

File 2: concept_set_expression_items

Generated Data: OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv   

Columns:

codeset_id

concept_id

code

codeSystem

ontology_id

ontology_label

mapping_category

mapping_logic

mapping_evidence

isExcluded

includeDescendants

includeMapped

item_id

annotation

created_by

created_at

File 3: concept_set_version

Generated Data: OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv   

Columns:

codeset_id

concept_set_id

concept_set_version_title

project

source_application

source_application_version

created_at

atlas_json

most_recent_version

comments

intention

limitations

issues

update_message

status

has_review

reviewed_by

created_by

provenance

atlas_json_resource_url

parent_version_id

is_draft

Generated Output:

OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_container.csv

OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv

OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv

atlas_json_files_v2.0.0.zip

omop2obo_enclave_codeset_id_dict_v2.0.0.json