N3C-Formatted OMOP2OBO Mappings

<p><strong>OMOP2OBO Mappings - N3C OMOP to OBO Working group</strong></p> <p>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.</p> <p><strong>N3C OMOP to OBO Working Group:&nbsp;</strong>https://covid.cd2h.org/ontology</p> <p>&nbsp;</p> <p><em><strong>Accessing the N3C-Formatted Mappings&nbsp;</strong></em></p> <p>You can access the three OMOP2OBO HPO mapping files in the Enclave from the Knowledge store using the following link: <a href="https://unite.nih.gov/workspace/compass/view/ri.compass.main.folder.1719efcf-9a87-484f-9a67-be6a29598567">https://unite.nih.gov/workspace/compass/view/ri.compass.main.folder.1719efcf-9a87-484f-9a67-be6a29598567</a>.</p> <p>The mapping set includes three files, but&nbsp;you only need to merge the following two files with existing data in the Enclave&nbsp;in order to be able to create the concept sets:</p> <ul> <li><em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv</em></li> <li><em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv</em></li> </ul> <p>&nbsp;</p> <p>The first file <em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv</em>, contains columns for the OMOP concept ids and codes as well as specifies information like whether or not the OMOP concept&rsquo;s descendants should be included when deriving the concept sets (defaults to FALSE). The other file <em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv</em>, contains details on the mapping&rsquo;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).</p> <p>&nbsp;</p> <p><em><strong>Creating Concept Sets</strong></em></p> <p>Merge these files together on the column named <em>codeset_id</em>&nbsp;and then join them with existing Enclave tables like concept and <em>condition_occurrence</em>&nbsp;to populate the actual concept sets. The name of the concept set can be obtained from the <em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv</em>&nbsp;file and is stored as a string in the column called <em>concept_set_id</em>. 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.</p> <p>An example mapping is shown below (highlighting some of the most useful columns):</p> <pre><code>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</code></pre> <p>&nbsp;</p> <p><strong>Release Notes - v2.0.0</strong></p> <p><em>Preparation</em></p> <p>In order to import data into the Enclave, the following items are needed:</p> <ul> <li>Obtain API Token, which will be included in the authorization header (stored as GitHub Secret)</li> <li>Obtain username hash from the Enclave</li> <li><a href="https://zenodo.org/record/7250177">OMOP2OBO Mappings (v1.5.0)</a></li> </ul> <p><em>Data</em></p> <ul> <li>Concept Set Container (<em>concept_set_container</em>): <em>CreateNewConceptSet</em></li> <li>Concept Set Version (<em>code_sets</em>): C<em>reateNewDraftOMOPConceptSetVersion</em></li> <li>Concept Set Expression Items (<em>concept_set_version_item</em>): <em>addCodeAsVersionExpression</em></li> </ul> <p><em>Script</em></p> <ul> <li><a href="https://github.com/callahantiff/OMOP2OBO/blob/master/applications/N3C/n3c_mapping_conversion.py">n3c_mapping_conversion.py</a></li> </ul> <p><em>Generated Output</em></p> <p>Need to have the <em>codeset_id</em>&nbsp;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 <em>omop2obo_enclave_codeset_id_dict_v2.0.0.json</em>. 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.</p> <p>&nbsp;</p> <p>To&nbsp;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&nbsp;<em>atlas_json_files_v2.0.0.zip</em>. 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.</p> <p>&nbsp;</p> <p><strong>File 1: concept_set_container</strong></p> <ul> <li><strong>Generated Data:</strong> <em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_container.csv</em></li> <li>Columns: <ul> <li>concept_set_id</li> <li>concept_set_name</li> <li>intention</li> <li>assigned_informatician</li> <li>assigned_sme</li> <li>project_id</li> <li>status</li> <li>stage</li> <li>n3c_reviewer</li> <li>alias</li> <li>archived</li> <li>created_by</li> <li>created_at</li> </ul> </li> </ul> <p>&nbsp;</p> <p><strong>File 2: concept_set_expression_items</strong></p> <ul> <li><strong>Generated Data: </strong><em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv</em>&nbsp; &nbsp;</li> <li>Columns: <ul> <li>codeset_id</li> <li>concept_id</li> <li>code</li> <li>codeSystem</li> <li>ontology_id</li> <li>ontology_label</li> <li>mapping_category</li> <li>mapping_logic</li> <li>mapping_evidence</li> <li>isExcluded</li> <li>includeDescendants</li> <li>includeMapped</li> <li>item_id</li> <li>annotation</li> <li>created_by</li> <li>created_at</li> </ul> </li> </ul> <p>&nbsp;</p> <p><strong>File 3: concept_set_version</strong></p> <ul> <li><strong>Generated Data: </strong><em>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv</em>&nbsp; &nbsp;</li> <li>Columns: <ul> <li>codeset_id</li> <li>concept_set_id</li> <li>concept_set_version_title</li> <li>project</li> <li>source_application</li> <li>source_application_version</li> <li>created_at</li> <li>atlas_json</li> <li>most_recent_version</li> <li>comments</li> <li>intention</li> <li>limitations</li> <li>issues</li> <li>update_message</li> <li>status</li> <li>has_review</li> <li>reviewed_by</li> <li>created_by</li> <li>provenance</li> <li>atlas_json_resource_url</li> <li>parent_version_id</li> <li>is_draft</li> </ul> </li> </ul> <p>&nbsp;</p> <p><strong><em>Generated Output:</em></strong></p> <ul> <li>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_container.csv</li> <li>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_expression_items.csv</li> <li>OMOP2OBO_v2.0.0_N3C_Enclave_CSV_concept_set_version.csv</li> <li>atlas_json_files_v2.0.0.zip</li> <li>omop2obo_enclave_codeset_id_dict_v2.0.0.json</li> </ul>