> 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/creating-reviewing-editing-and-removing-a-semantic-mapping.md).
# Creating, Reviewing, Editing, and Removing a Semantic Mapping
## Creating a Semantic Mapping
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 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
{% 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** link. The **Semantic Mappings** page appears. To search for a Search Semantic Mapping, use the Semantic Mapping 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 \ **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.
* **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.
{% 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 %}
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 Rhino Data Harmonization Engine (RhinoDHE)](/data-harmonization/about-the-rhino-data-harmonization-engine-rhinodhe.md)
* [Reviewing and Editing a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md)
* [Removing a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md)
* [Creating a Custom Vocabulary](/data-harmonization/creating-editing-and-removing-a-custom-vocabulary.md)
## Reviewing and Editing a Semantic Mapping
After you have created a Semantic Mapping, which is covered in detail in the *Creating a Semantic Mapping* topic, the FCP generates several mapping recommendations for each unique value in the source dataset field. Once the recommendation generation process is complete, you can review and edit the semantic mapping. This topic explains how to do this.
### Supported Languages for Recommendations
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
### Prerequisites
* A semantic mapping must have already been created. This is covered in the [Creating a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md) article.
* You must have Manage Data Mappings permission.
### Accessing the Semantic Mappings Page
{% stepper %}
{% step %}
#### Select the Semantic Mappings page
To access the **Semantic Mappings** page, complete the following steps.
1. Select **Data Mappings** from the **Main Menu**. The **Data Mappings** page appears.
2. Select the **Semantic Mappings** link. The **Semantic Mappings** page appears. To search for a Search Semantic Mapping, use the Semantic Mapping text box located at the top right corner of the page.
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 \ **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 and Approving Semantic Mapping Recommendations
You can review and approve each semantic mapping entry individually or in bulk. Reviewing recommendations in bulk can be quite helpful if you have a lot of semantic mapping entries.
### 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 for a semantic mapping that has 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](/getting-started/quick-start-guide/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 Version of a Semantic Mapping
You can create a new version of a 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 %}
When you are finished go to [Reviewing and Approving Semantic Mapping Recommendations](#reviewing-and-approving-semantic-mapping-recommendations) to finish editing and reviewing the new mappings.
#### Related Topics
* [About the Rhino Data Harmonization Engine (RhinoDHE)](/data-harmonization/about-the-rhino-data-harmonization-engine-rhinodhe.md)
* [Creating a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md)
* [Removing a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md)
* [Creating a Custom Vocabulary](/data-harmonization/creating-editing-and-removing-a-custom-vocabulary.md)
## Removing a Semantic Mapping
This topic explains how to remove a semantic mapping that you've previously created.
### Prerequisites
* A semantic mapping must have already been created.
* You must have Manage Data Mappings permission.
### Accessing the Semantic Mappings Page
To access the **Semantic Mappings** page, complete the following steps.
1. Select **Data Mappings** from the **Main Menu**. The **Data Mappings** page appears.
2. Select the **Semantic Mappings** link. The **Semantic Mappings** page appears. To search for a Search Semantic Mapping, use the Semantic Mapping text box located at the top right corner of the page.
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 \ **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.
## Related Topics
* [About the Rhino Data Harmonization Engine](/data-harmonization/about-the-rhino-data-harmonization-engine-rhinodhe.md)
* [Creating a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md)
* [Reviewing and Editing a Semantic Mapping](/data-harmonization/creating-reviewing-editing-and-removing-a-semantic-mapping.md)
* [Removing a Custom Vocabulary](/data-harmonization/creating-editing-and-removing-a-custom-vocabulary.md)