documentation:software:usagi
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
|
documentation:software:usagi [2017/02/28 12:18] schuemie [Scope and purpose] |
documentation:software:usagi [2017/02/28 17:20] schuemie [Reviewing Source Code to OMOP Vocabulary Concept Maps] |
||
|---|---|---|---|
| Line 41: | Line 41: | ||
| ==== Importing Source Codes into Usagi ==== | ==== Importing Source Codes into Usagi ==== | ||
| - | Export source codes from source system into a CSV or Excel (.xlsx) file. This should at least have the columns SOURCE_CODE and SOURCE_CODE_DESCRIPTION however additional information about codes can be brought over as well (e.g. DOSE_UNIT). In addition to information about the source codes, the frequency of the code should also be brought over as FREQUENCY, this can help prioritize which codes should receive the most effort in mapping (i.e. you can have 1,000 source codes but only 100 are truly used within the system). If any source code information needs translating to English, use Google Translate to do that. Add the English translations to your file. | + | Export source codes from source system into a CSV or Excel (.xlsx) file. This should at least have columns containing the **source code** and an English **source code description**, however additional information about codes can be brought over as well (e.g. dose unit, or the description in the original language if translated). In addition to information about the source codes, the **frequency of the code** should preferably also be brought over, since this can help prioritize which codes should receive the most effort in mapping (e.g. you can have 1,000 source codes but only 100 are truly used within the system). If any source code information needs translating to English, use Google Translate to do that. |
| Note: source code extracts should be broken out by domain (i.e. drugs, procedures, conditions, observations) and not lumped into one large file. | Note: source code extracts should be broken out by domain (i.e. drugs, procedures, conditions, observations) and not lumped into one large file. | ||
| Line 47: | Line 47: | ||
| Source codes are loaded into Usagi from the File --> Import codes menu. From here an “Import codes ...” will display as seen in Figure 1. | Source codes are loaded into Usagi from the File --> Import codes menu. From here an “Import codes ...” will display as seen in Figure 1. | ||
| - | {{ :documentation:loadingscreen1.png?direct |}} | + | {{ :documentation:software:usagiimport.png?direct |}} |
| **Figure 1: Usagi Source Code Input Screen** | **Figure 1: Usagi Source Code Input Screen** | ||
| - | In Figure 1, the source code terms were in Dutch and were also translated into English. Usagi will leverage the English translations to map to the standard vocabulary (SNOMED in this case). | + | In Figure 1, the source code terms were in Dutch and were also translated into English. Usagi will leverage the English translations to map to the standard vocabulary. |
| - | {{ :documentation:loadingscreen2.png?direct |}} | + | {{ :documentation:software:usagiimport2.png?direct |}} |
| **Figure 2: Telling Usagi how to Read Input File** | **Figure 2: Telling Usagi how to Read Input File** | ||
| Seen in Figure 2, the //Column mapping// section is where you define for Usagi how to use the imported CSV. If you mouse hover over the drop downs, a pop-up will appear defining each column. Usagi will not use the //Additional info column(s)// as information to associate source codes to Vocabulary concept codes; however this additional information may help the individual reviewing the source code mapping and should be included. | Seen in Figure 2, the //Column mapping// section is where you define for Usagi how to use the imported CSV. If you mouse hover over the drop downs, a pop-up will appear defining each column. Usagi will not use the //Additional info column(s)// as information to associate source codes to Vocabulary concept codes; however this additional information may help the individual reviewing the source code mapping and should be included. | ||
| - | Finally you can tell Usagi what OMOP Vocabulary terminologies you plan to map into. For example, in Figure 3, the user is mapping the source codes to the SNOMED standard terminology the OMOP Vocabulary. Hover your mouse over the different filters for additional information about the filter. | + | Finally you can set some restrictions for Usagi when mapping. For example, in Figure 3, the user is mapping the source codes only to concepts in the Condition domain. By default, Usagi only maps to Standard Concepts, but if the the option 'Filter standard concepts' is turned off, Usagi will also consider Classification Concepts. Hover your mouse over the different filters for additional information about the filter. |
| One special filter is //Filter by automatically selected concepts//. If there is information that you can use to restrict the search, you can do so by providing a list of CONCEPT_IDs in the column indicated in the //Auto concept ID column// (semicolon-delimited). For example, in the case of drugs there might be a mapping available to ATC codes. Even though an ATC code does not uniquely identify a single RxNorm drug code, it does help limit the search space to only those concepts that fall under the ATC code in the Vocabulary. By providing this list of CONCEPT_IDs in the //Auto concept ID column//, and turning on //Filter by automatically selected concepts//, Usagi will make use of this information. In the example above, we used a partial mapping derived from UMLS to restrict Usagi to this mapping when available. | One special filter is //Filter by automatically selected concepts//. If there is information that you can use to restrict the search, you can do so by providing a list of CONCEPT_IDs in the column indicated in the //Auto concept ID column// (semicolon-delimited). For example, in the case of drugs there might be a mapping available to ATC codes. Even though an ATC code does not uniquely identify a single RxNorm drug code, it does help limit the search space to only those concepts that fall under the ATC code in the Vocabulary. By providing this list of CONCEPT_IDs in the //Auto concept ID column//, and turning on //Filter by automatically selected concepts//, Usagi will make use of this information. In the example above, we used a partial mapping derived from UMLS to restrict Usagi to this mapping when available. | ||
| - | {{ :documentation:loadingscreen3.png?direct |}} | + | {{ :documentation:software:usagiimport3.png?direct |}} |
| - | **Figure 3: Defining OMOP Vocabulary Terminology Usagi Should Plan to Map to** | + | **Figure 3: Defining filter rules when mapping** |
| Once all your settings are finalized, click the "Import" button to import the file. The file import will take a few minutes as it is running the term similarity algorithm to map source codes. | Once all your settings are finalized, click the "Import" button to import the file. The file import will take a few minutes as it is running the term similarity algorithm to map source codes. | ||
| ==== Reviewing Source Code to OMOP Vocabulary Concept Maps ==== | ==== Reviewing Source Code to OMOP Vocabulary Concept Maps ==== | ||
| - | Once you have set up your input file of source codes, the mapping process begins. | + | Once you have imported your input file of source codes, the mapping process begins. |
| - | {{ :documentation:usagiscreen1.png?direct |}} | + | {{ :documentation:software:usagiscreen1.png?direct |}} |
| **Figure 4: Usagi Matching Screen** | **Figure 4: Usagi Matching Screen** | ||
| Line 78: | Line 78: | ||
| === Approving a Suggested Mapping === | === Approving a Suggested Mapping === | ||
| - | In the Overview Table, Usagi tries to make suggested related concepts to the source codes it was provided. In the example in Figure 4, the English names of Dutch condition codes were mapped to SNOMED conditions; Usagi searches for concept names and synonyms (taken from UMLS) based on whatever English text it is given. If Usagi is unable to make a mapping, it will map to the CONCEPT_ID = 0. If you noticed all the suggested mappings are 0 there may be an issue with the initial index generated by Usagi, use the //Help --> rebuild index// option to rebuild the index. | + | The Overview Table shows the current mapping of source codes to concepts. Right after importing source codes, this mapping contains the automatically generated suggested mappings based on term similarity and any search options. In the example in Figure 4, the English names of Dutch condition codes were mapped to standard concepts in the Condition domain, because the user restricted the search to that domain. Usagi compared the source code descriptions to concept names and synonyms to find the best match. Because the user had selected 'Include source terms' Usagi also considered the names and synonyms of all source concepts in the vocabulary that map to a particular concept.If Usagi is unable to make a mapping, it will map to the CONCEPT_ID = 0. |
| - | {{ :documentation:usagiscreen2.png?direct |}} | + | {{ :documentation:software:usagiscreen2.png?direct |}} |
| **Figure 5: Reviewing an Usagi Match** | **Figure 5: Reviewing an Usagi Match** | ||
| - | It is suggested that someone with experience with coding systems help map source codes to their associated standard vocabulary. That individual will work through code by code in the Overview Table to either accept the mapping Usagi has suggested or choose a new mapping. For example in Figure 5 we see that the Dutch term “Pijn toegeschreven aan hart” which was translated to the English term “Heart pain”. Usagi used “Heart pain” and mapped it to the OMOP Vocabulary concept of “4145057-Cardiac chest pain”. There was a matching score of 0.39 associated to this matched pair (matching scores are typically 0 to 1 with 1 being a confident match), a score of 0.39 signifies that Usagi is not very sure of how well it has mapped this Dutch code to SNOMED. Let us say in this case, we are okay with this mapping, we can approve it by hitting the green “Approve” button in the bottom right hand portion of the screen. | + | It is suggested that someone with experience with coding systems help map source codes to their associated standard vocabulary. That individual will work through code by code in the Overview Table to either accept the mapping Usagi has suggested or choose a new mapping. For example in Figure 5 we see that the Dutch term “Hoesten” which was translated to the English term “Cough”. Usagi used “Cough” and mapped it to the OMOP Vocabulary concept of “4158493-C/O - cough”. There was a matching score of 0.58 associated to this matched pair (matching scores are typically 0 to 1 with 1 being a confident match), a score of 0.58 signifies that Usagi is not very sure of how well it has mapped this Dutch code to SNOMED. Let us say in this case, we are okay with this mapping, we can approve it by hitting the green “Approve” button in the bottom right hand portion of the screen. |
| === Searching for a New Mapping === | === Searching for a New Mapping === | ||
| - | {{ :documentation:usagiscreen3.png?direct |}} | + | {{ :documentation:software:usagiscreen3.png?direct |}} |
| **Figure 6: Searching for a New Concept** | **Figure 6: Searching for a New Concept** | ||
documentation/software/usagi.txt · Last modified: 2021/04/09 18:56 by maximmoinat
Page Tools
