This topic explains how to create and approve a semantic mapping. Semantic Mappings streamlines the process of mapping your data to specific coding systems or vocabularies. For example, mapping procedure names entered in your local data to standard concepts in the OMOP (Observational Medical Outcomes Partnership) Procedure domain.
Prerequisites
- You must have Manage Data Mappings permission.
- The dataset that you want to use must have been imported into FCP.
What You'll Learn
In this topic, you will learn about:
- What is a Semantic Mapping?
- Accessing the Semantic Mapping Page
- Creating a Semantic Mapping
What is a Semantic Mapping?
Semantic Mappings map the contents of your data - mapping from any input values to a specific coding system (e.g. OMOP) or vocabulary. The Semantic Mapping uses a Generative AI model, which is run on your Rhino Client so that data is never sent anywhere outside of your network, to create mapping recommendations. You can then review these recommendations, or provide another team member access to review the recommendations, and approve them or change the mapped value.
The Semantic Mappings can then be used as part of a Syntactic Mapping and a Data Harmonization ETL to perform the mapping of values within select datasets that have been imported to your Rhino Client.
Accessing the Semantic Mapping Page
To access the Semantic Mappings page, complete the following steps.
- Select Data Mappings from the Main Menu. The Data Mappings page appears.
- Select the Semantic Mappings link. The Semantic Mappings page appears.
The table below defines each field in this page.
| Field | Description |
| Semantic Mapping Name | Name of the semantic mapping, such as "Normalize Service Type", "Condition", or "Drug [OMOP]" |
| Version | Version of the semantic mapping. This increments each time you make a change to the semantic mapping. |
| Information Icon (on hover) | The information icon shows a summary of the semantic mapping information. Information shown includes the Dataset, Field, Target, Status, Mapping Coverage and Creator. It also includes the number of unique values and approved mappings, as well as the percentage of approved mappings and mapping coverage. |
| Status |
Status of the recommendation and approval process. Statuses are:
|
| Sources | Name of the original dataset(s) and field(s) used as sources for mapping. |
| Target | Name of the Target Vocabulary to map to. For OMOP, this will also list the target domain (e.g., OMOP - Person). |
| Mapping Coverage | Percent of values with approved mappings, calculated as the number of non-empty values that have an approved mapping divided by the number of non-empty values. In order to preserve K-Anonymity, if there are <K non-empty values, this percent will be omitted. K is set by the K-Anonymization parameter configured at the project level in the project permissions. |
| Creator | Name of the person who created the mapping. |
| Three-Dot Menu | The three-dot menu (also known as the “context menu”) provides access to other options: Copy UID, Show Configuration, Export Semantic Mapping, and Remove Semantic Mapping. |
Creating a Semantic Mapping
To create a Semantic Mapping, complete the following steps.
- In the Data Mapping > Semantic Mappings page, select the Create Semantic Mapping button.
- The Create Semantic Mapping page appears.
- Enter the following information.
- Name of the semantic mapping.
- Description of the semantic mapping.
- Dataset that has the field you want to use as the source for mapping. The dataset should have already been imported into FCP.
- Field to Map. The field that you want to use as the source for the semantic mapping.
-
Target vocabulary that you want to map the field to. Options are:
- OMOP v5.4
- Custom Vocabulary
- Target Domain within OMOP v5.4 to map the field to. This option is not available for Custom Vocabulary mapping.
- Custom Vocabulary to map the field to. This option is not available for OMOP mapping.
- When complete, select Create Data Mapping. The page closes and the Semantic Mappings page is displayed again, with an entry for the mapping you just created. Here is what happens next.
- The FCP sends a request to your Rhino Client to generate a new Semantic Mapping with recommendations.
- The Rhino Client calculates the unique terms within the source dataset field, and for each term uses a Generative AI model to find the top five mapping recommendations to the selected target vocabulary and domain.
- In the case of OMOP mapping, the proposed recommendations include target concept names and target concept IDs.
- In the case of Custom Vocabulary mapping, the proposed recommendations include the target term and the target identifier (if your custom vocabulary includes identifiers).
- The automatic generation of the mapping recommendations runs on the Rhino Client, where the dataset is stored.
- If during this process, any queries are required to a Rhino service that isn’t hosted on that Rhino Client, only source values that appear at least K times in the field can be sent to this external service so as to preserve K-Anonymity.
- The status changes to “Processing”. The amount of processing time depends on the number of terms to map and the other workloads running on the Rhino Client. For example, a small vocabulary might take a few minutes, but a large one could take several hours.
- The number of times each source value appears in the field is calculated.
- The confidence of the model recommendation for each of the top 5 recommended mapping values is calculated.
- Once processing is complete, the mapping suggestions are ready for review.
Next Steps
After you complete these steps, go to the Reviewing and Editing Semantic Mapping topic to learn how to review and approve semantic mapping recommendations.
Related Topics
About the Harmonization Copilot