> For the complete documentation index, see [llms.txt](https://docs.rhinofcp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rhinofcp.com/data-harmonization/semantic-mapping.md).
# 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](/data-harmonization/semantic-mapping/custom-vocabularies.md) 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.
{% hint style="info" %}
**Use this when:** Your source field contains free-text or coded values that need to be translated to a standard or custom vocabulary.
{% endhint %}
{% hint style="warning" %}
**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.
{% endhint %}
***
## Accessing Semantic Mappings
{% stepper %}
{% step %}
#### Select Semantic Mappings
Select **Data Mappings** from the **Main Menu**. The **Data Mappings** page appears.
{% endstep %}
{% step %}
#### Open the Semantic Mappings page
Select the **Semantic Mappings** tab. The **Semantic Mappings** page appears. To search for a Semantic Mapping, use the text box located at the top right corner of the page.
{% endstep %}
{% endstepper %}
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: - 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 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
{% stepper %}
{% step %}
#### Create the Semantic Mapping
In the **Data Mapping** > **Semantic Mappings** page, select the **Create Semantic Mapping** button.
{% endstep %}
{% step %}
#### Open the Create Semantic Mapping page
The **Create Semantic Mapping** page appears.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% endstepper %}
***
## 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](https://app.gitbook.com/o/SKrkLtXReIPmOZjXnWZA/s/ydySyCBmy6F7NnGn4bPa/~/edit/~/changes/333/data-harmonization/semantic-mapping#creating-a-new-semantic-mapping) section above.
#### Steps
{% stepper %}
{% step %}
#### 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.
{% endstep %}
{% endstepper %}
***
## Reviewing Semantic Mapping Recommendations
After [Creating a New Semantic Mapping](https://app.gitbook.com/o/SKrkLtXReIPmOZjXnWZA/s/ydySyCBmy6F7NnGn4bPa/~/edit/~/changes/333/data-harmonization/semantic-mapping#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
{% hint style="info" %}
Need support for another language? Contact us at [support@rhinofcp.com](mailto:support@rhinohealth.com)!
{% endhint %}
### 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.
{% stepper %}
{% step %}
#### Approve the top recommendation
By default, the top recommendation is shown in the Target Value field. Examine the recommendation; if you decide to approve it, move the status slider to the right. It turns green, and the status changes to Approved.
{% endstep %}
{% step %}
#### Select another recommendation
To see other recommendations, click the arrow in the Target Value field and select another recommendation. Once you select the other recommendation, the status automatically changes to Approved.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% step %}
#### Repeat for remaining entries
Repeat this process for each remaining "In Review" entry.
{% endstep %}
{% endstepper %}
### 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.
{% stepper %}
{% step %}
#### Filter the entries
Use the filters at the top of the table to filter your view to the mapping entires you want to change. For example, you might choose to show only entries that have a confidence below 97%.
{% endstep %}
{% step %}
#### Select the entries
Select the mapping entries you would like to change by clicking the checkboxes at the beginning of each line. To select all entries on a page, click the checkbox next to **Frequency** header at the top of the table.
{% endstep %}
{% step %}
#### 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.
{% endstep %}
{% endstepper %}
***
## Exporting a Semantic Mapping
To export a semantic mapping to a CSV or JSON file, complete the following steps.
{% stepper %}
{% step %}
#### Open Export Semantic Mapping
In your project, select Data Mappings, then the Semantic Mappings tab.
Select the three-dot menu on the right side of a Semantic Mapping with a status of **Needs Review** or **Accepted**.
Select **Export Semantic Mapping** to open the Export Semantic Mapping page.
{% endstep %}
{% step %}
#### Choose the export location
Note the Export Location. You can adjust this if you need to.
([Mounting Storage to Your Rhino Client](/settings/mounting-storage-to-your-rhino-client.md) explains how to create or review client mounted storage that you can use for your export location)
{% endstep %}
{% step %}
#### Export the file
Select the format (CSV or JSON), then select Export Semantic Mapping.
When complete, a note appears indicating that the mapping has been exported.
{% endstep %}
{% step %}
#### Download the exported mapping
Go to the place where you exported the semantic mapping and download it.
Use a tool of your choice to view the CSV or JSON file.
{% endstep %}
{% endstepper %}
***
## 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.
{% stepper %}
{% step %}
#### 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. |
| {% endstep %} | |
{% step %}
#### Enter version details
Enter information in the Description field, if desired.
{% endstep %}
{% step %}
#### Select the dataset and field
Select the dataset from the drop down menu.
Select the field to map.
{% endstep %}
{% step %}
#### Create the new version
When complete, click Create New Version.
{% endstep %}
{% endstepper %}
***
## Removing a Semantic Mapping
To remove a semantic mapping that was previously created, complete the following steps.
1. 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**.
2. You will be prompted with a message asking whether you want to delete the mapping. Select **Yes**. The semantic mapping is removed.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.rhinofcp.com/data-harmonization/semantic-mapping.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
