Additional Tips: !TERM! Syntax
Updated November 3, 2023
This is an article in the series about how to write ESSENCE free-text queries. We thank Senior Data Analyst Zachary Stein for developing this series.
Part 1. Wildcards
Part 2. Underscores_and Brackets [ ]
Part 3. Inclusionary Terms
Part 4. Exclusion Terms and Parentheses
Part 5. A “Starter” Fall-related Injury Query and Examples of Complex Queries
Part 6. Free-text Coding in NSSP–ESSENCE
Part 7. Additional Tips: ISBLANK and ISNULL
Introduction
The use of free-text queries sets syndromic surveillance apart from other surveillance methods. NSSP-ESSENCE allows free-text querying for all users, and the BioSense Platform is adaptable to different data sources and topics. Free-text queries help analysts and epidemiologists produce customized results. They can quickly code free-text queries and rapidly respond to outbreaks, disasters, and health events by adjusting queries as events unfold. Such capabilities empower users to customize queries to fit their level of data, ensuring more accurate results.
Free-text coding follows distinct patterns. Once users learn to read these patterns, they can repurpose queries used elsewhere to suit their unique needs. This increases the speed and efficiency with which one can create and share free-text queries. To repurpose queries others have created, practitioners must understand the language. This series covers the search criteria language for ESSENCE free-text queries in depth.
Know the Language
The search criteria for ESSENCE free-text queries are built around Boolean logical operators and may contain “^” for wildcards; “,” for multiple entries; “ISBLANK” to look for blanks; “ISNULL” to look for nulls; [COMMA] to look for commas; and operators “and,” “or,” “andnot,” and parentheses “()” to define order and grouping.
Part 8. Additional Tips: !TERM! Syntax
In Part 1. Wildcards, we covered the importance of spaces within a query. ESSENCE users can position spaces to make sure specific characters appear alone. For example, a query for animal bites might want to find the term “CAT,” but how do we make sure we don’t pick up terms like loCATion, CATheter, compliCATions, intoxiCATion, or mediCATion? A query for ^CAT^ with a caret on either side will pick up all these examples and more. After seeing the results, users often try to correct the problem by attempting to:
- Add specific negations for each false detection of “cat,” but this can be tedious and may yield unexpected results. For example, the negation ^cat^,ANDNOT,^medication^ would avoid pulling in Chief Complaints (CCs) with “mediCATion” but would also remove Chief Complaints like “Needs medication after cat bite.”
- Exclude terms that have letters on either side of the term of interest, such as “^cat^,andnot,(,^[a-z]cat^,or,^cat[a-z]^,),” but doing this prevents detection of Chief Complaints that have both the word “cat” and words containing “cat.”
- Add spaces around the term to make ^ CAT ^. This is another logical step, but Chief Complaints rarely start or end with a space, meaning this query can’t pick up CCs like “Cat bite” or “Bit by cat.”
How do we make our query specific to CAT while allowing for edge cases where it starts, ends, or is the entirety of the Chief Complaint? Previously, we had to query or write out all the different forms our term could take. In our example, this would look like the following: ^ Cat ^,or,^ Cat,or,Cat ^,or,Cat .
^ Cat ^—for when the term is in the middle of a CC, we use spaces to make sure the three letters are separate from other letters.
^ Cat—to pick up any time the term of interest is at the end of the CC.
Cat ^—to pick up any time the term of interest is at the beginning of the CC.
Cat—for when the term of interest is the entirety of the CC.
The ESSENCE team at Johns Hopkins University Applied Physics Laboratory took pity on us using this method of creating four terms each time we wanted to insert a unique term into the Chief Complaint. So they created a shorthand method to simplify the process. !TERM! is the shorthand that, when queried in ESSENCE free text, is understood by ESSENCE to mean ^ TERM ^,or,^ TERM,or,TERM ^,or,TERM.
That means for our example above, we can run the query !CAT! and be assured we only capture visits where CAT stands by itself in the Chief Complaint and includes edge cases like starting, ending, or comprising the total of the Chief Complaint field. It also means we can be more specific in our inclusion criteria and avoid adding numerous negations for all the strange places the term CAT can appear within other words.
!CAT! is equivalent to the query string (,^ CAT ^,or,^ CAT,or,CAT ^,or,CAT,).
Also, take note of the parentheses around the above string of four terms. ESSENCE automatically surrounds !TERM! in parentheses so AND and ANDNOT statements will be accurately applied to each variation of the term, just as the user intends.
Keep in mind that if we were creating a real query for CAT, !CAT! wouldn’t pick up the term “Cats” in the unfortunate case of a patient being attacked by more than one feline friend. See Table 1 for CCDD Categories that use this !TERM! syntax.
| CCDD Category | Syntax | Use of !TERM! Syntax Avoids Capturing These and Similar Terms |
| Change in Taste or Smell v1 | …!loss!,or,!lost!… | weightLOSS, fLOSSing, and cLOSTridium |
| CDC Respiratory Syncytial Virus v1 | …!RSV!… | summeRSVille, tayloRSVille, hunteRSVille |
| Fire and Smoke Inhalation v1 | …!meth!… | soMETHing, METHadone, METHicillin, METHodist * |
| CDC Opioid Overdose v4 Parsed | …!nod!….!hod!… | NODules, HODgkins, immuNODeficiency, metHODs |
*In this scenario, the epidemiologist wants to negate “Smoking Meth” and avoid negating a phrase such as “Something caught on fire.”
Try it out!
- Compare the two queries below (they should return the same visits):
- !CAT!
- ^ CAT ^,or,^ CAT,or,CAT ^,or,CAT
- Run this query to view all the edge cases that ^ CAT ^ syntax would miss:
- !CAT!,ANDNOT,^ CAT ^
We thank Senior Data Analyst Zachary Stein for volunteering to write a series of articles about free-text coding. Stein, formerly with the Kansas Department of Environment and Health, does epidemiological work to support NSSP efforts. Stein is an active participant in the NSSP–CoP. He initially wrote about free-text coding as an entry on the NSSP–CoP Syndrome Definition Committee forum. The forum generated considerable interest, inspiring this series. Stein acknowledges input provided by others who contributed to the forum post.
