User guide on searching and browsing content.
TODO: local:true trick
...
| Table of Contents |
|---|
General Details
To browse content, select the “Terminology” tab, choose a terminology (e.g. SNOMEDCT_US), and open the “Content” accordion. You should see something like this:
...
It is in this section that you can perform searches across the content and visualize concepts and navigate around. Specific features of this section are described below.
Searching
The searching in this tool is designed to be like Google. There’s a search box into which you can type concept codes or textual phrases and it attempts to find the most useful matches for content browsing.
There are five parts to the concept search form:
Search textbox (e.g. “Enter search”) into which a text search can be typed.
Handler - one of a set of predefined search handlers that perform different searching algorithms in the background
Autocomplete - a checkbox that when selected will make suggestions for searches as you type. This is NOT enabled by default because it interferes with related features that some browsers have, which can make the experience somewhat confusing.
Expression (e.g. “Enter expression, or semantic type …”) into which a SNOMED ECL-like expression can be used and/or searching within either UMLS or terminology-specific semantic type categories. e.g. “procedure” vs “disorder” in SNOMEDCT_US.
“Search” button - performs the requested search (as does typing “enter” when in either of the search text boxes)
This button also has an accompanying “X” icon which will clear the search form.
Performing a search causes “Search Results” to be populated. For example:
...
The search results show up to 50 results at a time with paging available all the way to the last result. The search results themselves are a concept id and the preferred name of that concept.
The first search result is automatically selected and displayed in the area to the right. Clicking on any of the other rows will cause that corresponding concept to get loaded. See the “Concept Report” section below for more information on how to read that report.
Search Handlers
The application has a flexible searching architecture in the background that allows additional searching algorithms to be implemented and incorporated into the application. By default, three choices are offered:
STANDARD - tuned to be the most useful search for general concept browsing. The background algorithm is complex and out-of-scope to fully document here. By default, this is configured to find only “active” concepts.
EXACT - this is does a more-or-less “exact-ish” search (when not normalizing for whitespace, some stop words, and punctuation)
NGRAM - useful for when you’re not sure of the spelling of something, or not sure whether the terminology uses noun-like or adjective-like language to label concepts (e.g. “cervical” vs “cervix”).
SNOMED - this only shows when browsing SNOMED terminologies and is a pass-through to the search API of the SNOMED International browser at browser.ihtstdotools.org. It can be used to return concepts in the same way that browser would.
If you encounter unexpected search results under certain circumstances, let us know! We’re always looking to refine and improve the searching algorithms and understand different use-cases require different approaches.
Lucene Searching “Tricks”
The “STANDARD” search handler also allows for use of “lucene syntax” within the query, where if you understand the underlying data model - you can tune searches to specific aspects of the content. Here are some examples of queries making use of the Lucene syntax:
local:true- Performs a search for ONLY locally created content.heart AND active:false- performs a search for inactive concepts matching the word “heart” (note the “active only” checkbox will have to be deselected).attributes:CUI=C0412010- performs a search for concepts in the selected terminology associated with the UMLS CUI C0412010Other examples will be provided in the future - as will more documentation on the complete indexing model.
Searching with Expressions
One of the most powerful aspects of the searching in the application is the ability to use SNOMED ECL expressions (described more completely here https://confluence.ihtsdotools.org/display/DOCECL/Expression+Constraint+Language+-+Specification+and+Guide).
At the moment, the tool does not fully support all possible ECL expressions, but it does support the most useful operators (AND, OR, MINUS, descendants/ancestors, and refinement). Additionally, we have relaxed the ECL grammar to support identifiers from other terminologies, this things like ICD10CM, LNC, RXNORM and other terminologies can be similarly searched in an ECL-like way.
When using this feature of the search form, you do not need to combine it with a textual element, you can simply search to resolve the results of an expression. For example this search finds all of the descendants of the SNOMEDCT_US “Procedure” concept:
...
Here are some other fun examples of the ECL searching you can try with SNOMEDCT_US:
< 71388002 | Procedure | : has_indirect_procedure_site = <<64033007 | Kidney structure |- Procedures with a direct procedure site of “kidney” or any of it’s descendants.< 71388002 : has_indirect_procedure_site = <<64033007- Same as the query above, but with the name portions removed.< 71388002 : 405814001 = <<64033007- Same as the query above, but using the SNOMEDCT_US concept id for the relationship name instead of the metadata label.^723264001 | Lateralizable body structure reference set |- members of the “Lateralizable body structure reference set”^723264001 | Lateralizable body structure reference set | AND << 362837007 | Entire cell |- members of that refset that are also descendants (or self) of “Entire Cell”<< I11 | Hypertensive heart disease |- an ECL expression used with ICD10CM to find I11 and all of it’s descendants.* : MAPPING=B20- an (enhanced) ECL expression used to find concepts with mappings to a particular code (e.g. in this case SNOMED concepts with B20 as an ICD10 code)Other examples will be provided in the future - as will more documentation on the complete model of what ECL is supported
NOTE: when using ECL expressions with terminologies that have alphanumeric characters in the codes, then case-sensitivity is important.
Concept Report
Performing a search will cause the first search result to get loaded into a display to the right of the search results (or underneath in the mobile experience). Here is an example of a basic concept report.
...
There are some key things to understand about this report
The bar at the top shows the concept id and the preferred name of the concept
Each of the bold sections can be clicked on to expand or hide that information (NOTE: “Hierarchy” is hidden in the view showing above)
The labels on each section can be tuned to the specific terminology (NOTE: where it says “Descriptions”, the default terminology label is “Atoms”. The idea is that the names that show for a particular terminology can be tuned to the “natural way” of talking about those constructs in that terminology. SNOMED talks about “Descriptions” and “Refsets” instead of talking about “Atoms” and “Subsets”. The default naming conventions come from the UMLS).
Overall, there are 9 sections to the report - with only those having actual contents showing up in general (listed here with their default names).
...
Semantic Types - Includes semantic types from the UMLS Semantic Network (e.g. “Diagnostic Procedure”) as well as semantic types defined by individual sources (such as the SNOMEDCT “semantic tag” - the value in parentheses associatied with fully specified names). These values can be searched.
...
Hierarchy - A visualization of the tree position of the concept in the corresponding terminology hierarchy.
For poly-hierarchies (like SNOMEDCT_US), there may be more than one tree position, in which case this includes paging controls (this example shows 25 separate tree positions)
The “plus” icons can be clicked on to load the other children of that node not displayed by default (e.g. 362937008 in the example below has 3 other children besides 27832009).
The “down” icons show expanded children and can be clicked to collapse that part of the view.
The “right” icons can be clicked to further expand children for that given node.
The links can be clicked on to load the corresponding concept into the view.
The highlighted portion represents the current focus concept.
...
Attributes - Generally terminology-specific attributes (or properties) associated with the concept. This example shows three attributes loaded from SNOMEDCT_US and an additional computed attribute for the UMLS CUI information. Exactly what shows up here depends on the nature of what data was loaded.
...
Definitions - Narrative textual definitions intended for human readers.
<TODO: need example>
...
Atoms - Individual names (and associated metadata) that are synonymous with the concept’s underlying conceptual “meaning”.
In brackets is show the term type, the language, and any label related to where the synonym came from.
Term types of INDEX_SY reflect generated or manually added synonyms.
Atoms themselves may have attributes (or properties) which can be seen by expanding the “plus” icon next to each entry.
...
Subsets - Shown in the report are the subsets that the focus concept is a member of. Conceptually, subsets are collections of concept codes from a terminology that are labeled and used for a specific use-case.
This examples shows the concept belonging to two anatomy related subsets.
...
Maps - Organized into “sets”, these can be thought of as cross-terminology relationships. A way of linking codes in one terminology to codes in another.
This example shows a concept with a number of maps to ICD10CM.
The links can be clicked and will load the corresponding concept into the view.
...
Relationships - (relationships from this concept).
Inverse Relationships are relationships to this concept from the indicated concept.
The green “D” flags indicate that the relationship is part of the logical definition of the concept (e.g. part of the necessary and sufficient conditions)
The green numbers indicate the SNOMEDCT “relationship group”
The next label is the high-level relationship type (mousing over it will provide more info). This corresponds to the UMLS REL field.
The longer label is the more detailed relationship type (e.g. “has_finding_site”). This corresponds to the UMLS RELA field.
The longer labels can be used in ECL queries in place of the concept ids for those relationships (this is particularly useful when using ECL with non-SNOMED terminologies).
Some concepts have large number of relationships - so remember clicking the header collapses the view to prevent the need for massive scrolling.
...
.