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:
ATOM - 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.
NLP - originally designed for NLP work, this is does a more-or-less “exact-ish” search (when not considering whitespace 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”).
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 “ATOM” 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”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.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”.
...
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.
...
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.
...
Relationships - (relationships from this concept). The display includes flags for whether the relationship is part of the logical definition of the concept (green), and information about
Inverse Relationships (relationships to this concept)
...
.