Semantic Mapping
Overview
Semantic Mapping (aka. Terminology Mapping, Code Mapping) streamlines the process of mapping values in your local data to standardized coding systems or vocabularies. It takes all unique values from a chosen source field and maps each one to a standardized dictionary entry that includes a concept ID, a display name, or both.
Rhino's built-in model generates mapping recommendations for each unique value. Since accuracy in data mapping is critical, the process is designed with a human-in-the-loop approach — you review, correct, and approve each recommendation before it is applied.
Rhino FCP includes built-in support for OMOP and FHIR-related standard vocabularies. When these don't cover your data, you can define a Custom Vocabulary and use it as the mapping target.
Once reviewed, Semantic Mappings can be incorporated into a Syntactic Mapping and used as part of a Data Harmonization ETL to transform values in datasets imported to your Rhino Client.
Note: if strict privacy protections are needed, the project's K-Anonymization parameter should be set to a value greater than 1 at the time of project creation. This controls which source values can be sent to external services during recommendation generation — only values that appear at least K times in the field will be eligible.
Accessing Semantic Mappings
The table below defines each field in this page.
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: - Queued: The recommendation generation task will begin as soon as resources are available on the Rhino Client. - Processing: Recommendations for mapping source dataset field values to the target vocabulary are being generated. - Needs Review: Recommendations have been generated and are ready for your review, and not all entries have been approved. - Approved: All entries in the Semantic Mapping have been approved. - Error: There was some error in the mapping process.
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 New Semantic Mapping
Prerequisites
You must have the "Manage Data Mappings" permission.
The dataset that you want to use must have been imported into FCP.
Steps
Enter the mapping information
Enter the following information.
Name of the semantic mapping.
Description of the semantic mapping. This is optional, but highly encouraged to improve the quality of recommendations.
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
FHIR HDP_0.4.0
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.
Create the 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.
Editing a Semantic Mapping
Prerequisites
You must have the "Manage Data Mappings" permission.
A semantic mapping must have already been created. This is covered in the Creating a New Semantic Mapping section above.
Steps
Open the Semantic Mapping Review page
In the Data Mappings > Semantic Mappings page, click the entry for the semantic mapping that you would like to review. The Semantic Mapping Review page appears. In the example below, the Semantic Mapping being reviewed is called "Procedures". A list of unique source values and their selected target values appears.
The following information appears for each mapping entry:
Frequency indicates how many times the source value appears in the source data.
Source Value is the unique term in the source dataset that requires mapping.
Selected Target Value is the currently selected value to map the source value to. The FCP generates mapping recommendations and shows you the top five recommendations. The top recommendation appears first and is selected by default to be the Target Value. To see the other recommendations, click on the drop down menu.
Status: Indicates whether the recommendation has been approved. Click on the slider to approve the recommendation.
Confidence is a number, expressed as a percentage, that represents the likelihood that the mapping recommendation is accurate. Higher percentages indicate a higher likelihood of accuracy than lower percentages. The confidence number reflects the likelihood for the selected target value.
You can also use the filters to view a subset of records, based on the values you specify.
Reviewing Semantic Mapping Recommendations
After Creating a New Semantic Mapping, the Rhino FCP can generate mapping recommendations for each unique value in the selected source dataset field. Once generated, you can review, edit, and approve the proposed mappings.
Mapping recommendations can be reviewed and approved individually or in bulk. Bulk review is especially useful when working with a large number of mapping entries.
Supported Languages
The Semantic Mapping recommendation engine generates recommendations in the same language as the source terminology. Cross-language translation is not currently supported.
Currently supported languages:
English – for source and target terminology in English
Hebrew – for source and target terminology in Hebrew
Reviewing Recommendations Individually
Before you review an entry, first look at its frequency, source value, and confidence value. The higher the value, the more confident the FCP is that the recommended mapping is correct. Do one or more of the following steps to review and select a recommendation.
Enter your own target value
If you do not see the recommendation that you want, add your own by typing information into the field. Once you type at least 3 letters, you will see values from the target vocabulary that contain the letters that you typed. You must select a valid value from the target vocabulary. Once a value is selected, the status of the mapping entry automatically changes to Approved.
Reviewing Recommendations in Bulk
Sometimes, you might have many semantic mapping entries that you want to review in bulk to streamline the process. To do so, complete the following steps.
Choose an action
You can now select an action to perform on all selected mapping entries from the action ribbon that appears at the bottom of the page:
Approve All will set the status of all selected entries to Approved
Set to in review will set the status of all selected entries to In review
Set Target Value will open a page in which you can search for a target value from the target vocabulary. The selected target value will be set for all selected mappings, and their status will be set to Approved.
Exporting a Semantic Mapping
To export a semantic mapping to a CSV or JSON file, complete the following steps.
Choose the export location
Note the Export Location. You can adjust this if you need to.
(Mounting Storage to Your Rhino Client explains how to create or review client mounted storage that you can use for your export location)
Creating a New Semantic Mapping Version
You can create a new version of an existing Semantic Mapping from new data that was not originally used to create the current version of the mapping. This is particularly helpful because it allows you to quickly make updates without you having to review the entire mapping again.
Once you've created the new version:
Already approved mappings are kept as is and are not re-run by the Large Language Model.
Unique values and mapping coverage are recalculated.
Source terms that didn’t exist in the previous version of the mapping are added with mapping recommendations.
You can continue to edit the mapping until a code object is created.
Open the Create New Version page
In the Semantic Mapping page, select the New Version button for the mapping that you want. The Create New Version page opens.
Field/Button
Description
Name
Name of the Semantic Mapping. This cannot be changed.
Description
Description of the mapping. The description is optional but can be useful, particularly to document changes to the version.
Dataset
Indicates the dataset that you want to use. You can select a different dataset for the new version.
Select Field to Map
Should include terms from a single vocabulary, target set, or target OMOP Domain.
Target
Target vocabulary or data model to map to. This cannot be changed.
Target Domain
Target domain; this cannot be changed.
Removing a Semantic Mapping
To remove a semantic mapping that was previously created, complete the following steps.
In the Data Mappings > Semantic Mappings page locate the Semantic Mapping you want to remove. Click the three-dot (meatball) menu at the end of the entry and select Remove semantic mapping.
You will be prompted with a message asking whether you want to delete the mapping. Select Yes. The semantic mapping is removed.
Last updated
Was this helpful?