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.
Prerequisites
- A semantic mapping must have already been created. This is covered in the Creating a Semantic Mapping article.
- You must have Manage Data Mappings permission.
What You'll Learn
In this topic you will learn about:
- Accessing the Semantic Mappings page
- Reviewing and Editing a Semantic Mapping
- Creating a New Version of a Semantic Mapping
Accessing the Semantic Mappings 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. |
Reviewing and Editing a Semantic Mapping
Once the Semantic Mapping has been created and the mapping recommendations have been generated by FCP, you can review and approve them or edit them until a code object for the semantic mapping has been created.
To do this, complete the following steps.
- 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 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.
- 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.
- 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.
- 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.
- Repeat this process for each remaining "In Review" entry.
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.
- 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%.
- 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.
- 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.
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.
To create a new version of the semantic mapping, do the following.
- 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. |
- Enter information in the Description field, if desired.
- Select the dataset from the drop down menu.
- Select the field to map.
- When complete, click Create New Version.
When you are finished go to Reviewing and Approving Semantic Mapping Recommendations to finish editing and reviewing the new mappings.
Related Topics
About the Harmonization Copilot