User Tools

Site Tools


documentation:software:usagi

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revision Both sides next revision
documentation:software:usagi [2017/02/28 17:20]
schuemie [Reviewing Source Code to OMOP Vocabulary Concept Maps]
documentation:software:usagi [2020/05/03 11:30]
maximmoinat
Line 15: Line 15:
 Source codes that needs mapping are loaded into the Usagi (if the codes are not in English additional translations columns are needed). ​ A term similarity approach is used to connect source codes to Vocabulary concepts. However these code connections need to be manually reviewed and Usagi provides an interface to facilitate that.  ​ Source codes that needs mapping are loaded into the Usagi (if the codes are not in English additional translations columns are needed). ​ A term similarity approach is used to connect source codes to Vocabulary concepts. However these code connections need to be manually reviewed and Usagi provides an interface to facilitate that.  ​
  
-Usagi currently does not currently ​translate non-English codes to English. ​ We suggest using Google Translate ([[https://​translate.google.com/​]]). ​ You can paste an entire column of non-English terms into Google Translate, and it will return that same column translated to English.+Usagi currently does not translate non-English codes to English. ​ We suggest using Google Translate ([[https://​translate.google.com/​]]). ​ You can paste an entire column of non-English terms into Google Translate, and it will return that same column translated to English.
  
 Usagi will only propose concepts that are marked as **standard concepts** in the Vocabulary. Usagi will only propose concepts that are marked as **standard concepts** in the Vocabulary.
Line 59: Line 59:
 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. 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 ​/ ATC code//.  If there is information that you can use to restrict the search, you can do so by providing a list of CONCEPT_IDs ​or an ATC code in the column indicated in the //Auto concept ID column// (semicolon-delimited). ​ For example, in the case of drugs there might already ​be ATC codes assigned to each drug. 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. ​To use the ATC code, follow these steps: 
 + 
 +  - In the Column mapping section, switch from 'Auto concept ID column' to 'ATC column'​ 
 +  - In the Column mapping sectionselect the column containing the ATC code as 'ATC column'​.  
 +  - Turn on the 'Filter by user selected concepts / ATC code' on in the Filters section. 
 + 
 +You can also use other sources ​of information ​than the ATC code to restrict as well.  In the example ​shown in the figure ​above, we used a partial mapping derived from UMLS to restrict ​the Usagi searh. In that case we will need to use 'Auto concept ID column'​.
  
 {{ :​documentation:​software:​usagiimport3.png?​direct |}} {{ :​documentation:​software:​usagiimport3.png?​direct |}}
Line 90: Line 96:
 **Figure 6:  Searching for a New Concept** **Figure 6:  Searching for a New Concept**
  
-There will be cases where Usagi suggests a map and the user will be left to either try to find a better mapping or set the map to no concept (CONCEPT_ID = 0).  In the example given in Figure 6, we see for the Dutch Term “Symptomen/​klachten potentie [ex. P07,P08]”, which was translated to “Impotence NOS”.  Usagi was unable to make a proper map because ​the UMLS derived mapping ​used a non-valid concept, and therefore mapped it to CONCEPT_ID = 0.  In the Search Facility, we could search for other concepts using either the actual term itself or a search box query.+There will be cases where Usagi suggests a map and the user will be left to either try to find a better mapping or set the map to no concept (CONCEPT_ID = 0).  In the example given in Figure 6, we see for the Dutch Term “Hoesten”, which was translated to “Cough”.  Usagi's suggestion ​was restricted by the concept identified in our automatically ​derived mapping ​from UMLS, and the result might not be optimal.  In the Search Facility, we could search for other concepts using either the actual term itself or a search box query.
  
-When using the manual search box, there are some things to keep in mind:  ​Usagi’s search ​algorithm is based on complete wordsso the search ​‘cardi’ will not find terms containing the word ‘cardiac’. ​ To use partial words you can insert a wildcard ‘*’, so for example ​‘cardi*’ will find both ‘cardiac’ and ‘cardiology’. ​ Usagi is able to deal with plurals, so ‘child’ will also find ‘children’. ​ You can use simple ​boolean ​logic in the search box, for example ‘cardiac ​AND arrest’ will find only those terms containing both words, whereas ‘cardiac ​OR heart’ will find all terms containing one or both of the two words.+When using the manual search box, one should ​keep in mind that Usagi uses a fuzzy search, ​and does not support structured ​search ​queries, so for example ​not supporting ​boolean ​operators like AND and OR.
  
-To continue our example, suppose we used the search term “Impotence NOS” to see if we could find a better mapping. ​ On the right of the //Query// section of the Search Facility, there is a //Filters// section, this provides options to trim down the results from the OMOP Vocabulary when searching for the search term.  In this case we know we want to only find SNOMED terms, we only want valid concepts, and we are looking for concepts in the CONDITION domain   +To continue our example, suppose we used the search term “Cough” to see if we could find a better mapping. ​ On the right of the //Query// section of the Search Facility, there is a //Filters// section, this provides options to trim down the results from the OMOP Vocabulary when searching for the search term.  In this case we know we want to only find standard ​concepts, and we allow concepts to be found based on the names and synonyms of source ​concepts in the vocabulary that map to those standard concepts  ​
  
-When we apply these search criteria we find “4216771-Impotence” and feel this may be an appropriate Vocabulary concept to map to our Dutch code, in order to do that we can hit the “Replace concept”, which you will see the Selected Source Code section update, followed by the “Approved” button. ​ There is also an “Add concept” button, this allows for multiple standardized Vocabulary concepts to map to one source code (e.g. some source codes may bundle multiple diseases together while the standardized vocabulary may not).+When we apply these search criteria we find “254761-Cough” and feel this may be an appropriate Vocabulary concept to map to our Dutch code, in order to do that we can hit the “Replace concept”, which you will see the Selected Source Code section update, followed by the “Approved” button. ​ There is also an “Add concept” button, this allows for multiple standardized Vocabulary concepts to map to one source code (e.g. some source codes may bundle multiple diseases together while the standardized vocabulary may not)
 + 
 +=== Concept information === 
 + 
 +When looking for appropriate concepts to map to, it is important to consider the '​social life' of a concept. The meaning of a concept might depend partially on its place in the hierarchy, and sometimes there are '​orphan concepts'​ in the vocabulary with few or no hierarchical relationships,​ which would be ill-suited as target concepts. Usagi will often report the number of parents and children a concept has, and it also possible to show more information by pressing ALT + C, or selecting //view// --> //Concept information//​ in the top menu bar.  
 + 
 +{{ :​documentation:​software:​conceptinformation.png?​direct |}} 
 +**Figure 7:  Concept information panel** 
 + 
 +Figure 7 shows the concept information panel. It shows general information about a concept, as well as its parents, children, and other source codes that map to the concept. Users can use this panel to navigate the hierarchy and potentially choose a different target concept.
  
 === Auto Mapped === === Auto Mapped ===
Line 102: Line 117:
 When you import your source codes there is an option to add information about “Auto concept ID column”. ​ If there is information already known that will allow you to map your source data to a CONCEPT_ID, you can include that in the file you upload into Usagi. ​ Once loaded, the Overview Table will list these codes with a status of “Auto mapped to 1” if only one CONCEPT_ID was provided, or just “Auto mapped” if there were more.  You still will be required to approve these auto mappings using the “Approve” button, or if you really trust the underlying information,​ you can sort by status, select all codes with status ‘Auto mapped to 1”, and click //Edit --> Approve selected//. When you import your source codes there is an option to add information about “Auto concept ID column”. ​ If there is information already known that will allow you to map your source data to a CONCEPT_ID, you can include that in the file you upload into Usagi. ​ Once loaded, the Overview Table will list these codes with a status of “Auto mapped to 1” if only one CONCEPT_ID was provided, or just “Auto mapped” if there were more.  You still will be required to approve these auto mappings using the “Approve” button, or if you really trust the underlying information,​ you can sort by status, select all codes with status ‘Auto mapped to 1”, and click //Edit --> Approve selected//.
  
 +Continue to move through this process, code by code, until all codes have been checked. ​ In the list of source codes at the top of the screen, by selecting the column heading you can sort the codes. ​ Often we suggest going from the highest frequency codes to the lowest. In the bottom left of the screen you can see the number of codes that have approved mappings, and how many code occurrences that corresponds to. 
  
-Continue ​to move through this processcode by code, until all codes have been checked. ​ In the list of source codes at the top of the screen, by selecting the column heading you can sort the codes. ​ Often we suggest going from the highest frequency codes to the lowest (often you will find the two set of codes cover most of the data)   +It is possible ​to add comments to mappingswhich could be used to document why a particular mapping decision was made.
  
 Best Practices: Best Practices:
Line 109: Line 125:
   * By clicking on a column name you can sort the columns in the Overview Table. ​ It may be valuable to sort on “Match Score”; reviewing codes that Usagi is most confident on first may quickly knock out a significant chunk of codes. ​ Also sorting on “Frequency” is valuable, spending more effort on frequent codes versus non-frequent is important.   * By clicking on a column name you can sort the columns in the Overview Table. ​ It may be valuable to sort on “Match Score”; reviewing codes that Usagi is most confident on first may quickly knock out a significant chunk of codes. ​ Also sorting on “Frequency” is valuable, spending more effort on frequent codes versus non-frequent is important.
   * It is okay to map some codes to CONCEPT_ID = 0, some codes may not be worth it to find a good map and others may just lack a proper map.   * It is okay to map some codes to CONCEPT_ID = 0, some codes may not be worth it to find a good map and others may just lack a proper map.
 +  * It is important to consider the context of a concept, specifically its parents and children.
  
 ==== Export the Usagi Map Created ==== ==== Export the Usagi Map Created ====
Line 117: Line 134:
  
 After selecting the SOURCE_VOCABULARY_ID,​ you give your export CSV a name and save to location. ​ The export CSV structure is in that of the SOURCE_TO_CONCEPT_MAP table. ​ This mapping could be appended to the OMOP Vocabulary’s SOURCE_TO_CONCEPT_MAP table. ​ It would also make sense to append a single row to the VOCABULARY table defining the SOURCE_VOCABULARY_ID you defined in the step above. ​ Finally, it is important to note that only mappings with the “Approved” status will be exported into the CSV file; the mapping needs to be completed in USAGI in order to export it. After selecting the SOURCE_VOCABULARY_ID,​ you give your export CSV a name and save to location. ​ The export CSV structure is in that of the SOURCE_TO_CONCEPT_MAP table. ​ This mapping could be appended to the OMOP Vocabulary’s SOURCE_TO_CONCEPT_MAP table. ​ It would also make sense to append a single row to the VOCABULARY table defining the SOURCE_VOCABULARY_ID you defined in the step above. ​ Finally, it is important to note that only mappings with the “Approved” status will be exported into the CSV file; the mapping needs to be completed in USAGI in order to export it.
 +
 +==== Updating an Usagi mapping ====
 +
 +Often a mapping is not a one-time effort. As data is updated perhaps new source codes are added, and also the vocabulary is updated regularly, perhaps requiring an update of the mapping. ​
 +
 +When the set of source codes is updated the following steps can be followed to support the update:
 +
 +  - Import the new source code file
 +  - Choose //File// --> //Apply previous mapping//, and select the old Usagi mapping file. Note that the format of the previous mapping should be as created by //Save// or //Save As//. Other formats do not work.
 +  - Identify codes that haven'​t inherited approved mappings from the old mapping, and map them as usual.
 +
 +When the vocabulary is updated, follow these steps:
 +
 +  - Download the new vocabulary files from Athena
 +  - Rebuild the Usagi index (//Help// --> //Rebuild index//)
 +  - Open the mapping file
 +  - Identify codes that map to concepts that in the new vocabulary version no longer are Standard concepts, and find more appropriate target concepts. ​
  
 ==== Menu Options ==== ==== Menu Options ====
documentation/software/usagi.txt · Last modified: 2021/04/09 18:56 by maximmoinat