Qualifier Relations | emtelligent Documentation

In this section, we explain how structured data for medications relations is represented in the NLP API JSON output and in the Output Database schema. We also provide sample queries to illustrate the key aspects of the data schema.

After reading this page, we hope you will:

Understand what qualifier relations are.
Know how to retrieve data for qualifier relations.

The content in this section builds on the concepts and data models explained in earlier sections (see Entity-level Tables, and Document-level Tables).

What are Qualifier Relations?

Some ontologies, such as SNOMED CT, contain adverbial or adjectival terms. These terms are collectively referred to as qualifier values. Qualifier values are frequently used to convey important details about a patient’s condition, observed abnormalities and disorders, and hence are vital to the physician’s understanding of the patient’s medical report. For example, a finding of ‘a very large intraparenchymal hemorrhage’ will necessitate a very different course of action than a finding of ‘small intraparenchymal hemorrhage’.

The NLP API extracts qualifier values and the subjects they refer to, as qualifier relations. A qualifier relation, is a one-to-one relation between: a subject being qualified, and a qualifier argument.

For example, consider this observation:

Mild-to-moderate stenosis at the origin of the right internal carotid.

From the above sentence, the NLP API recognizes the qualifier mild-to-moderate and the qualifies argument stenosis as illustrated below. Note that the qualifies argument is the subject of the relation:

Qualifier relation required and optional arguments

The subject being modified by a qualifier, is a regular the NLP API entity. In the NLP API data model, entities are associated with concepts and entity types. For example, in the SNOMED CT ontology, the subject of a qualifier relation may have a semantic type of disorder, finding, morphologic abnormality, or body structure, and the qualifier value can be one from an extensive list of carefully curated concepts that NLP API recognizes (over 400 at last count).

The NLP API supports several types of qualifier relations: status, size/severity, duration/time, location, stage/grade and compliance. For the most up-to-date list, please refer to the Qualifier type property in the NLP API JSON result specification. The following table provides a few examples of qualifier values to illustrate the descriptive function of each qualifier type.

Qualifier Type	Qualifier values (SNOMED CT concepts)
status	Stable, Healed, Active, Worsening, Improved, Evolving, Controlled, Uncontrolled
size/severity	Small, Medium, Large, Massive, Advanced, Severe, Mild to Moderate, Moderate to Severe
location	Right, Left, Right sided, Left sided, Right and left
duration/time	Acute, Subacute, Chronic, Old, New
compliance	Non-compliant, Compliant, Refused, Noncompliance with medication (finding)
stage/grade	Stage, Grade, End stage, Early stage

The examples provided in this table represent a tiny subset of all recognized qualifier values. The best way to assess the usefulness of qualifiers is to explore their occurrence in your data set. You can do this by processing reports using the qualifier-relation feature and reviewing the qualifier types and values that were extracted. SQL queries that retrieve this information from an Output Database are provided in the Utility Functions section.

If your reports use qualifiers we do not recognize, please contact support@emtelligent.com. It is possible to extend the recognized set, and optimize the qualifier extraction for customer-specific use cases.

Qualifier relation types such as size/severity and status are ubiquitous in medical text, where as qualifier relation types like stage and compliance have more specialized uses. The stage/grade qualifier relation type, is extracted for explicit mention of cancer staging terms, for example Stage IV colon cancer, using SNOMED concepts. The compliance qualifier relation type, relates terms describing the patient’s compliance, non-compliance, or refusal of treatment or plan of care. SNOMED contains several concepts such as Poor drug compliance (finding), Vaccine refused by patient (situation), Patient self-discharge against medical advice (procedure) that are used in these qualifier relations. Note, compliance are complex concepts to express and present many challenges for general purpose information extraction. If you are interested in using cancer staging or compliance qualifier relations, we recommend that you contact us in advance to discuss the specifics of your data extraction use case.

The emtelligent ontology includes an extensive collection of qualifier terms building on the robust set of qualifier values provided by the SNOMED CT ontology. Hence, you should use either the emtelligent or SNOMED CT ontology when working with qualifier values in the Output Database. In both ontologies, qualifiers have a semantic type of qualifier value. In the UMLS metathesaurus, however, qualifiers have semantic type of Qualitative Concept.

JSON Data Model

Consider the following sentence:

Mild-to-moderate stenosis at the origin of the right internal carotid.

The JSON output for the qualifier relation extracted from this sentence is shown below:

{
      "relations": {
           "qualifiers": [
                {
                     "label": "RQ0",
                     "attributes": {
                          "confidence": 1,
                          "qualifier_type": "size/severity"
                     },
                     "args": {
                          "qualifier": {
                               "ref": "E0",
                               "text": [
                                    "Mild-to-moderate"
                               ]
                          },
                          "qualifies": {
                               "ref": "E3",
                               "text": [
                                    "stenosis"
                               ]
                          }
                     },
                     "concept_links": []
                }
           ]
      }
}

Notice the following:

The qualifiers array is an element of the relations object. Each element of this array is a single object representing a qualifier relation.
A qualifier relation instance has two types of named arguments: qualifier and qualifies.
The qualifies argument is a reference to an entity representing the subject of the relation.
The qualifier argument is a reference to an entity that represents the qualifier value.
A qualifier relation has a qualifier_type attribute.

Qualifier Relation Tables

In the Output Database schema, qualifier relations are stored in the qualifierrelation table.

The following ER diagram shows the relationship between these tables:

Entity-Relation diagram showing qualifierrelation and its associated tables.

From the ER diagram above, observe that:

The qualifierrelation table has qualifier_id and qualifies_id columns which contain foreign key references to the primary key column of the entity table.
1. The qualifies_id refers to an entity that is the subject of the relation: for example, the entity extracted for the text stenosis.
2. The qualifie(r)_id refers to an entity that is the qualifier value: for example, the entity extracted for the text mild-to-moderate.
The entity table has a foreign key reference to the foundentity table which stores many entity attributes. By joining the foundentity with other entity-related tables, you can retrieve information associated with the concepts, entity types and locations for the entity. See Entity-level Tables.
The qualifierrelation table has a qualifier_type column. This column contains the attribute of the qualifier relation. Examples of valid qualifier types are: status, size/severity, duration/time, stage/grade and compliance.

Sample Queries

In this section, we present queries to illustrate how to write SQL queries to retrieve information about qualifier relations. The SQL queries will be discussed in order as follows:

Note: Because qualifier relations such as size/severity and status are most prevalent in Radiology reports, it may be helpful to use a database containing output from Radiology reports.

Query: List qualifier terms and concepts

This query shows the qualifier values present in your data. It returns the annotated text for qualifiers extracted by the NLP API and the concepts they mapped to.

To find information about qualifier relations we start at the qualifierrelation table. Then we perform a series of joins to retrieve the concept ID from the concept table, and the annotated text from the foundentity table. For more complete explanation of how to work with these tables, see Entity-level Tables.

In the WHERE clause, we then filter for the qualifier relation type and ontology of interest. In the example below, we search for qualifier relations where the type is size/severity and for concepts from the snomed ontology.

SELECT qualifierrelation.qualifier_type,
       qualifier_fe.text AS qualifier_term, qualifier_c.description AS qualifier_concept
  FROM qualifierrelation
           JOIN entity qualifier_e
           ON qualifier_e.id = qualifierrelation.qualifier_id AND qualifier_e.type_='found'
           JOIN foundentity qualifier_fe
           ON qualifier_fe.id = qualifier_e.entity_id   -- IMPORTANT *entity_id* column NOT primary key of the entity table
           JOIN foundentityconcept qualifier_fec
           ON qualifier_fec.found_entity_id = qualifier_fe.id
  -- join on concept table to retrieve concept description 
           JOIN concept qualifier_c
           ON qualifier_c.concept_id = qualifier_fec.concept_id 
              AND qualifier_c.ontology = qualifier_fec.concept_ontology -- REQUIRED conditional statement
 WHERE qualifierrelation.qualifier_type = 'size/severity'               -- possible values: 'size/severity', 'status', 'duration/time'
   AND qualifier_c.ontology = 'snomed'                                  -- possible values:  'snomed' or 'emtelligent'
   AND qualifier_fe.text <> ''
 GROUP BY qualifierrelation.qualifier_type, qualifier_fe.text, qualifier_c.description
 ORDER BY 1
 LIMIT 5;

qualifier_type	qualifier_term	qualifier_concept
size/severity	advanced	Advanced (qualifier value)
size/severity	decreased	Decreased (qualifier value)
size/severity	decreasing	Decreasing (qualifier value)
size/severity	elevated	High (qualifier value)
size/severity	enlarged	Enlarged (qualifier value)

Query: Retrieve subject and qualifier values for qualifier relations

This query shows how to retrieve both the subject being qualified, and the qualifier value for qualifier relations. This query appears complex due to the large number of joins involved. However, it is actually straight-forward. The query involves the following steps:

Start with the qualifierrelation table.
Perform a series of joins on the qualifie(s)_id column of the qualifierrelation table to get the foundentity, foundentitytype and concept tables for the subject of the relation.
1. The foundentity contains the annotated text for an entity.
2. The concept contains data about the concept such as its parent ontology, ID and fully-qualified description.
3. The foundentitytype table contains the entity type name and entity type ontology.
Next, perform a series of joins similar to step 1 for the qualifier value but joining on the qualifie(r)_id. Note: we do not retrieve the entity type for the qualifier value because we know that all qualifier values will have the same semantic type representation for a given ontology.
Last, we filter for the parameters of interest in the WHERE clause.

Note, there are many options of ontologies to use for retrieving information about qualifier relations in the Output Database. Although a common scenario is to use the SNOMED CT ontology for classifying both the qualifier value and subject entities, you are not limited to SNOMED CT. The following query uses three different ontologies: the emtelligent ontology for qualifier values, and the MEDCIN ontology for the concept of subject entities, and the SNOMED CT ontology for the semantic type classification of subject entities.

SELECT qualifies_fet.type_name AS qualifies_entity_type, qualifies_c.concept_id AS qualifies_concept_id,
       qualifies_c.description AS qualifies_concept, qualifies_fe.text AS qualifies_term,
       qualifier_fe.text AS qualifier_term, qualifier_c.description AS qualifier_concept
  FROM qualifierrelation
       -- joins to retrieve annotated term for the SUBJECT
           JOIN entity qualifies_e
           ON qualifies_e.id = qualifierrelation.qualifies_id AND qualifies_e.type_='found' -- JOIN on qualifie(s)_id column
           JOIN foundentity qualifies_fe
           ON qualifies_fe.id = qualifies_e.entity_id
      -- joins to retrieve the concept for the SUBJECT
           JOIN foundentityconcept qualifies_fec
           ON qualifies_fec.found_entity_id = qualifies_fe.id
           JOIN concept qualifies_c
           ON qualifies_c.concept_id = qualifies_fec.concept_id AND
              qualifies_c.ontology = qualifies_fec.concept_ontology
      -- joins to retrieve the entity_type for SUBJECT
           JOIN foundentitytype qualifies_fet
           ON qualifies_fet.found_entity_id = qualifies_fe.id AND qualifies_fet.ontology = 'snomed' -- 'snomed', 'umls', or 'medcin'
      -- joins to retrieve the annotated term for the QUALIFIER VALUE
           JOIN entity qualifier_e
           ON qualifier_e.id = qualifierrelation.qualifier_id AND qualifier_e.type_='found'-- JOIN on qualifie(r)_id column
           JOIN foundentity qualifier_fe
           ON qualifier_fe.id = qualifier_e.entity_id
      -- joins to retrieve the concept for the  QUALIFIER VALUE
           JOIN foundentityconcept qualifier_fec
           ON qualifier_fec.found_entity_id = qualifier_fe.id
           JOIN concept qualifier_c
           ON qualifier_c.concept_id = qualifier_fec.concept_id AND
              qualifier_c.ontology = qualifier_fec.concept_ontology
 WHERE qualifierrelation.qualifier_type = 'status' -- supported qualifier types e.g. 'status', 'size/severity', 'duration/time'
   AND qualifier_c.ontology = 'snomed'             -- for qualifier values use 'snomed' or 'emtelligent'
   AND qualifies_c.ontology = 'medcin'             -- for subject entities use any supported ontology e.g. 'snomed', 'umls_nci', 'umls_loinc'
 ORDER BY 1
 LIMIT 5;

qualifies_entity_type	qualifies_concept_id	qualifies_concept	qualifies_term	qualifier_term	qualifier_concept
body structure	296407	Examination Of Female Genitalia (Gynecology, Oncology): vulva (physical exam)	vulva	normal-appearing	Normal (qualifier value)
body structure	7427	Examination Of Abdomen (Cardiology, Gastroenterology): liver (physical exam)	liver	within normal limits	Normal (qualifier value)
body structure	169812	Examination Of Musculoskeletal System (Oncology, Orthopedics, Rheumatology): lumbar / lumbosacral spine (physical exam)	lumbar spine	otherwise normal	Borderline normal (qualifier value)
body structure	7433	Examination Of Abdomen (Gastroenterology, Cardiology): spleen (physical exam)	spleen	within normal limits	Normal (qualifier value)
body structure	7552	Pelvic Exam (Internal) (Gynecology, Obstetrics, Oncology, Urology): vagina (physical exam)	vagina	normal-appearing	Normal (qualifier value)

Query: Rank by qualifier concepts

Many qualifier relation types contain ordinal values, for example size/severity. In this query, we count the qualifier relations pertaining to the term stenosis, and then return the count in the order of descending size or severity.

This query uses the CASE statement in the ORDER BY clause to map the qualifier concept ID to a string value that can be sorted. A preparatory step is required to get a list of qualifier value concept IDs. The SQL query we used to get the IDs is given in the Utility Functions section.

  WITH stenosis_severity AS (SELECT qualifies_c.description AS qualifies_concept,
                                    qualifier_c.description AS qualifier_concept,
                                    qualifier_c.concept_id  AS qualifier_concept_id, count(*) AS count
                               FROM qualifierrelation
                                   -- joins to retrieve the annotated text for the SUBJECT
                                        JOIN entity qualifies_e
                                        ON qualifies_e.id = qualifierrelation.qualifies_id  AND qualifies_e.type_='found' -- JOIN on qualifie(s)_id column
                                        JOIN foundentity qualifies_fe
                                        ON qualifies_fe.id = qualifies_e.entity_id
                                   -- joins to retrieve the concept for the SUBJECT
                                        JOIN foundentityconcept qualifies_fec
                                        ON qualifies_fec.found_entity_id = qualifies_fe.id
                                        JOIN concept qualifies_c
                                        ON qualifies_c.concept_id = qualifies_fec.concept_id AND
                                           qualifies_c.ontology = qualifies_fec.concept_ontology
                                   -- joins to retrieve the entity_type for the SUBJECT
                                        JOIN foundentitytype qualifies_fet
                                        ON qualifies_fet.found_entity_id = qualifies_fe.id AND
                                           qualifies_fet.ontology = 'snomed' -- 'snomed', 'umls', or 'medcin'
                                   -- joins to retrieve the annotated text for the QUALIFIER 
                                        JOIN entity qualifier_e
                                        ON qualifier_e.id = qualifierrelation.qualifier_id AND qualifier_e.type_='found' -- JOIN on qualifie(r)_id column
                                        JOIN foundentity qualifier_fe
                                        ON qualifier_fe.id = qualifier_e.entity_id
                                   -- joins to retrieve the concept for the QUALIFIER
                                        JOIN foundentityconcept qualifier_fec
                                        ON qualifier_fec.found_entity_id = qualifier_fe.id
                                        JOIN concept qualifier_c
                                        ON qualifier_c.concept_id = qualifier_fec.concept_id AND
                                           qualifier_c.ontology = qualifier_fec.concept_ontology
                              WHERE qualifierrelation.qualifier_type = 'size/severity' -- supported qualifier types e.g. 'status', 'size/severity', 'duration/time'
                                AND qualifier_c.ontology = 'snomed'      -- for qualifier values use 'snomed' or 'emtelligent'
                                AND qualifier_c.concept_id IN
                                    ('24484000', '371924009', '6736007', '6736007', '255603008', '255604002',
                                     '255606000', '255605001', '255507004', '371923003')
                                AND qualifies_c.ontology = 'snomed'      -- for subject entities use any supported ontology e.g. 'medcin', 'umls_nci', 'umls_loinc'
                                AND qualifies_c.concept_id = '267038008' -- Edema (finding) SNOMED CT Concept ID '267038008'
                              GROUP BY qualifies_c.description, qualifier_c.description, qualifier_c.concept_id)
SELECT qualifies_concept, qualifier_concept, count
  FROM stenosis_severity
 ORDER BY CASE WHEN qualifier_concept_id = '24484000'  THEN '9-Severe' -- Severe (severity modifier)
               WHEN qualifier_concept_id = '371924009' THEN '8-Moderate to Severe' -- Moderate to Severe (qualifier value)
               WHEN qualifier_concept_id = '255603008' THEN '7-Major' -- Major (qualifier value)
               WHEN qualifier_concept_id = '6736007'   THEN '6-Moderate' -- Moderate (severity modifier)
               WHEN qualifier_concept_id = '371923003' THEN '5-Mild-to-Moderate' -- mild-to-moderate (qualifier value);
               WHEN qualifier_concept_id = '255604002' THEN '4-Mild' -- Mild (qualifier value)
               WHEN qualifier_concept_id = '255606000' THEN '3-Minor' -- Minor (qualifier value)
               WHEN qualifier_concept_id = '255507004' THEN '2-Small' -- Small (qualifier value)
               WHEN qualifier_concept_id = '255605001' THEN '1-Minimal' -- Minimal (qualifier value)
          END DESC;

qualifies_concept	qualifier_concept	count
Edema (finding)	Severe (severity modifier) (qualifier value)	1
Edema (finding)	Small (qualifier value)	1
Edema (finding)	Minimal (qualifier value)	1

Utility Functions

Below are some helpful data exploration queries for qualifier relations.

-- List of qualifier types
SELECT Distinct( qualifier_type ) FROM qualifierrelation;
-- Count of qualifier values by qualifier type
SELECT qualifier_type, count(*)
  FROM qualifierrelation
 GROUP BY qualifier_type;
-- Show Concepts by qualifier type
SELECT DISTINCT qualifierrelation.qualifier_type,
              string_agg(qualifier_c.description, ',')
              OVER (PARTITION BY qualifierrelation.qualifier_type) AS qualifier_fsn
FROM qualifierrelation
       JOIN entity qualifier_e
            ON qualifier_e.id = qualifierrelation.qualifier_id AND qualifier_e.type_='found'
       JOIN foundentity qualifier_fe
            ON qualifier_fe.id = qualifier_e.entity_id
       JOIN foundentityconcept qualifier_fec
            ON qualifier_fec.found_entity_id = qualifier_fe.id
       JOIN concept qualifier_c
            ON qualifier_c.concept_id = qualifier_fec.concept_id AND
               qualifier_c.ontology = qualifier_fec.concept_ontology
WHERE qualifier_c.ontology = 'snomed' -- 'snomed' or 'emtelligent'
GROUP BY qualifierrelation.qualifier_type, qualifier_c.description;
-- Retrieve one sentence for each recognized qualifier term
-- Note: This query assumes the --store-sections-and-sentences option was enabled during processing
SELECT  qualifierrelation.qualifier_type,
        qualifier_fe.text as term,
        qualifier_c.concept_id AS qualifier_concept_id,
        qualifier_c.description AS qualifier_concept,
        Max(sl.text)
FROM qualifierrelation
          JOIN entity qualifier_e
          ON qualifier_e.id = qualifierrelation.qualifier_id AND qualifier_e.type_='found'
          JOIN foundentity qualifier_fe
          ON qualifier_fe.id = qualifier_e.entity_id
          JOIN foundentityconcept qualifier_fec
          ON qualifier_fec.found_entity_id = qualifier_fe.id
          JOIN concept qualifier_c
          ON qualifier_c.concept_id = qualifier_fec.concept_id AND
               qualifier_c.ontology = qualifier_fec.concept_ontology
          -- retrieve sentence
          JOIN foundentitylocation fel ON qualifier_fe.id = fel.found_entity_id
          JOIN location l ON fel.location_id = l.id AND l.type_='sentence'
          JOIN sentencelocation sl ON l.location_id = sl.id AND l.type_='sentence'
WHERE qualifier_c.ontology = 'snomed' -- 'snomed' or 'emtelligent'
GROUP BY qualifierrelation.qualifier_type, qualifier_fe.text, qualifier_c.concept_id, qualifier_c.description