Temporality Relations

In this section, we explain how structured data for temporality 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 temporality relations are.
• Understand what attributes are extracted.
• Know how to find temporality relations and their attributes.

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

The current implementation extracts historical mentions such as phrases containing history of, or pmh of (past medical history) and specific mentions like day one, 6 months, or 10/07/2017.

What are Temporality Relations

Temporality relations relate a subject to a temporal entity, where the subject can be any disorder, finding or other target concept in sentences where there are terms which provide some temporal information about the subject. Currently the NLP API recognizes 2 categories of temporal information: historical and specific.

Historical Temporality

Temporal qualifiers like history of or status post indicate that an event or disease process occurred in the past, often without giving a specific date of when the event happened. Being able to detect to distinguish that the disease had occurred in the past is relevant for the patient’s current care. The historical context of a disease mention or event may assist in understanding the velocity of disease progression, and provides important context for understanding the patient’s current state of health.

Temporality relations are extracted when the subject term is mentioned in conjunction with a historical temporal term within a clause. Temporality relations relate a subject entity (e.g. disorders, findings or other target concepts) to an entity which provides temporal context. A temporal entity represents terms like h/o, longstanding history of, and s/p, and many other lexical variants. Consider the following sentence:

The temporality relation attributes extracted by the NLP API are:

• Subject: the subject modified by the temporal context. In the example above, the subject is FALL.
• Temporal_entity: the entity which describes the temporal status of the subject. In the example above, the temporal entity is extracted for the term S/P.
• Polarity: the polarity attribute for this relation indicates whether the temporality status itself is negated or asserted e.g. polarity is negated for the phrase NO FALL.
• Category: for the example above, the category is historical.

Found vs Assumed Temporal Entities

The temporal entity which represents the historical term can be represented by a found entity (an entity with type_ found in the entity table) or an assumed entity (an entity type of assumed in the assumedentity table).

Consider this example:

PAST MEDICAL HISTORY
Coronary artery disease with previous MI.

In this case, the temporal relations extracted is an assumed temporal entity with a value of past medical history. The temporal entity for Coronary artery disease and MI in this example is an assumed entity because it occurs within a section that is categorized as historical.

Specific Temporality

Medical reports are rich sources of date mentions because they record when a patient experienced medically significant events, when tests and procedures were performed, and when medications were administered. We see a very large variety of ways in which dates are recorded, for example in structured forms like these:

• 2024/12/22 - 12/16/2010: Admitted with UTI and pneumonia; had a gout flare.
• Discharge Date: 2015 JUNE 10th
• Pulmonary hypertension (PA pressure 35/15 by RHC in 3/2022)
• 6/6/2018 12:10PM BLOOD Glucose-463* UreaN-20 Creat-1.2* Na-132* K-3.6 Cl-101 HCO3-18* AnGap-17

The NLP API is trained to recognize many date and date-time formats to maximize recall of date terms.

While dates are prevalent in structured and semi-structured sections of medical reports, temporal information is also recorded in narrative text sections in various ways, often more informally. Examples of such sentences are given with the date terms highlighted:

• hernia repair 2020
• Right heart failure with an echocardiogram in Sep of this year showing mild left ventricular hypertrophy
• On 3-25, the patient had another PEA arrest
• The patient had an appendectomy five years ago

Consider the following sentence:

The temporality relation attributes extracted by the NLP API are:

• Subject: the subject modified by the temporal status. In the example above, the subject is appendectomy.
• Temporal_entity: the entity that represents the temporal status of the subject. In the example above, a temporal entity is extracted for the term 1992.
• Polarity: the polarity attribute for this relation indicates whether the temporality status itself is negated or asserted e.g. polarity is asserted for the entity appendectomy, because the patient had an appendectomy.
• Category: the type of temporality relation recognized is specific.

Temporality vs Experiencer Relations

It should also be noted that a historical or specific mention may be experienced by persons other than the patient. For example:

The patient’s mother has a history of breast cancer

In contrast to:

The patient has a history of breast cancer

Likewise for specific temporality relations:

His mother had CABG in 2000 at age 55.

In contrast to:

The patient had CABG in 2019.

The experiencer is extracted as an experiencer relation while the temporal status of the cancer mention is extracted as a temporality relation. To obtain both pieces of information for all temporality relations a query can be written to first retrieve the foundentities for those mentions experienced by an experiencer (e.g. the patient) using the experiencer relation and then retrieve temporality information for that subset of foundentities using the temporality relation. An example of this query pattern is provided here.

JSON Data Model

This section explains the NLP API JSON output for historical and specific temporality relations.

Historical Temporality

The JSON below shows the NLP API’s JSON result output for a historical temporality relation extracted from this statement:

{ 
    "relations": {
        "temporalities": [
            {
                "label": "RT0",
                "attributes": {
                    "confidence": 1,
                    "polarity": "asserted",
                    "category": "historical"
                },
                "args": {
                    "subject": {
                        "ref": "E3",
                        "text": [
                            "FALL"
                        ]
                    },
                    "modifiers": [],
                    "temporal_entity": {
                        "ref": "E1",
                        "text": [
                            "S/P"
                        ]
                    }
                },
                "concept_links": []
            }
        ]
    }
}

From the JSON output above, we see that:

1. The temporalities array is an element of the relations object. Each element of this array is a single object representing a temporality relation instance.
2. A temporality relation instance has several named arguments: the subject and the temporal_entity.
3. Note that both the subject argument and temporal_entity argument are required. Each temporality relation corresponds to exactly one subject and temporal entity pair. However, note that many-to-many relation between subject and temporal entities is possible. For example a procedure could be administered on multiple dates, and conversely it is possible for multiple procedures to be administered for the date.
4. Note that the modifiers property is not currently used.

Specific Temporality

The example below shows the NLP API’s JSON output for a specific temporality relation extracted from the following sentence:

{
    "relations": {
        "temporalities": [
            {
                "label": "RT0",
                "attributes": {
                    "confidence": 1,
                    "polarity": "asserted",
                    "category": "specific"
                },
                "args": {
                    "subject": {
                        "ref": "E1",
                        "text": [
                            "patient"
                        ]
                    },
                    "modifiers": [],
                    "temporal_entity": {
                        "ref": "E0",
                        "text": [
                            "1992"
                        ]
                    }
                },
                "concept_links": []
            },
            {
                "label": "RT1",
                "attributes": {
                    "confidence": 1,
                    "polarity": "asserted",
                    "category": "specific"
                },
                "args": {
                    "subject": {
                        "ref": "E2",
                        "text": [
                            "appendectomy"
                        ]
                    },
                    "modifiers": [],
                    "temporal_entity": {
                        "ref": "E0",
                        "text": [
                            "1992"
                        ]
                    }
                },
                "concept_links": []
            }
        ]
    }
}

From the JSON output above, we see that the temporal_entity RT1 contains all the same the properties as the historical temporality relation example in the previous section except for the following:

1. The category is specific.
2. The subject is appendectomy and the temporal entity is 1992.

Temporality Relation Tables

A few key points about this schema:

1. Each temporality relation relates to exactly one subject term. Each subject mention is represented by an entity in the Output Database schema, and has a corresponding row in the entity and foundentity tables respectively.
2. Each temporality relation also extracts exactly one temporal qualifier term as a temporal entity. Temporal entities may be represented by an entity of type found or assumed in the Output Database schema, which have corresponding rows foundentity or assumedentity tables respectively
3. In addition to the entity attributes stored in the foundentity table, such as in the column section_name, many other attributes about an entity can be found from performing SQL JOINs with entity-related tables. For more information see Entity-level tables .
4. The temporalityrelationmodifier table is currently not populated with modifiers.

Sample Queries

In this section, we present SQL queries that illustrate how to retrieve information about medication relations for initial data exploration. Five queries are provided:

We begin by querying all temporality relations:

• Query: Find All Temporality Relations

Next, we show examples of queries that target historical temporality relations:

• Query: Find All Historical Mentions for Patient
• Query: Find All Assumed Temporality Mentions

Finally, we retrieve data about specific temporality relations:

• Query: Find Temporal Terms Associated with Procedure Mentions
• Query: Find Temporal Terms Associated with Disorder, Findings or Morphologic Abnormality Mentions

Query: Find All Temporality Relations

This query returns all the terms and corresponding sentences for all temporality relations in an Output Database. This query is useful for reviewing the output of the temporality relation extraction feature.

The query uses the temporalityrelation table and JOINs with related foundentity tables to retrieve the term (annotated text), section heading, and sentence. Note that as both the subject and the temporal status are represented by entities, we need to join with the entity table twice, and take care to use the appropriate aliases to reference their entity attributes e.g. sub_fe is the table alias for the subject entity and temporal_e is the table alias for the temporal status entity respectively.

SELECT t.id,
   t.category,
   sub_fe.section_name AS section,
   sub_fe.text        AS subject_term,
   temporal_fe.text   AS temporal_entity_term,
   s.text              AS sentence
FROM temporalityrelation t
       JOIN entity sub_e
       ON t.subject_id = sub_e.id AND sub_e.type_ = 'found'
       JOIN foundentity sub_fe
       ON sub_e.entity_id = sub_fe.id
       JOIN foundentitylocation sub_fel
       ON sub_fe.id = sub_fel.found_entity_id
       JOIN location l
       ON sub_fel.location_id = l.id AND l.type_ = 'sentence'
       JOIN sentencelocation s
       ON l.location_id = s.id
       JOIN entity temporal_e
       ON t.temporal_entity_id = temporal_e.id AND temporal_e.type_ = 'found'
       JOIN foundentity temporal_fe
       ON temporal_e.entity_id = temporal_fe.id
       ON temporal_fe.id = temporal_fes.found_entity_id
ORDER BY l.document_id, sub_fe.start;

Query: Find All Historical Mentions for Patient

This query finds all temporality relations with the following criteria:

• The temporality mention is experienced by the patient himself (whether explicitly referenced or inferred as the subject of the report)
• The relation is positively asserted (i.e. patient has a history of ‘x’)
• The category is historical.

We also want to return the SNOMED concepts for the subject of the relation.

WITH explicitpatients AS (SELECT er.id           AS relation_id,
                               c.description     AS person,
                               er.experienced_id AS experienced_entity_id
                          FROM experiencerrelation er
                                   JOIN entity e
                                   ON er.experiencer_id = e.id -- NOTE: find experience(r) entities
                                   JOIN foundentity fe
                                   ON fe.id = e.entity_id -- IMPORTANT: e.entity_id not e.id
                                   JOIN foundentityconcept fec
                                   ON fe.id = fec.found_entity_id
                                   JOIN concept c
                                   ON c.concept_id = fec.concept_id AND c.ontology = fec.concept_ontology
                         WHERE c.ontology = 'snomed'
                           AND e.type_ = 'found' -- IMPORTANT: this condition is required.
                           AND c.concept_id = '116154003'),
implicitpatients AS (SELECT er.id AS relation_id, ae.value AS person, er.experienced_id AS experienced_entity_id
                          FROM entity e
                                   JOIN experiencerrelation er
                                   ON er.experiencer_id = e.id -- NOTE: experience(r) entities
                                   JOIN assumedentity ae
                                   ON ae.id = e.entity_id
                         WHERE e.type_ = 'assumed'
                           AND ae.value = 'patient'), -- NOTE: must specify value as 'patient' (NOT 'family')
   all_patients AS (SELECT * FROM implicitpatients UNION SELECT * FROM explicitpatients)
SELECT t.id,
   t.category,
   pat.person,
   sub_fe.section_name AS section,
   sub_fe.text        AS subject_term,
   sub_c.description   AS subject_concept,
   sub_c.concept_id    AS subject_concept_id,
   temporal_fe.text   AS temporal_entity_term,
   s.text              AS sentence
FROM temporalityrelation t
       JOIN all_patients pat
       ON t.subject_id = pat.experienced_entity_id AND t.category = 'historical'
       JOIN entity sub_e
       ON t.subject_id = sub_e.id AND sub_e.type_ = 'found'
       JOIN foundentity sub_fe
       ON sub_e.entity_id = sub_fe.id
       JOIN foundentityconcept sub_fec
       ON sub_fe.id = sub_fec.found_entity_id
       JOIN concept sub_c
       ON sub_fec.concept_id = sub_c.concept_id AND sub_fec.concept_ontology = sub_c.ontology AND
          sub_c.ontology = 'snomed' -- IMPORTANT: Use SNOMED
       JOIN foundentitylocation sub_fel
       ON sub_fe.id = sub_fel.found_entity_id
       JOIN location l
       ON sub_fel.location_id = l.id AND l.type_ = 'sentence'
       JOIN sentencelocation s
       ON l.location_id = s.id
       JOIN entity temporal_e
       ON t.temporal_entity_id = temporal_e.id AND temporal_e.type_ = 'found'
       JOIN foundentity temporal_fe
       ON temporal_e.entity_id = temporal_fe.id
WHERE t.polarity = 'asserted'; -- IMPORTANT: exclude 'no history of ...'

Query: Find All Assumed Temporality Mentions

This query returns each temporality relation where the temporal term is assumed based on context, such as from sentences like Diabetic on insulin in the PAST MEDICAL HISTORY section of a clinical note.

Note that this query returns both positively asserted and negated relation instances. Also note that assumed temporal entities are necessarily historical.

SELECT t.id,
   t.category,
   t.polarity,
   sub_fe.text      AS subject_term,
   temporal_ae.value AS temporal_entity_term,
   s.text            AS sentence
FROM temporalityrelation t
        -- Extract subject text, location, and sentence
       JOIN entity sub_e
       ON t.subject_id = sub_e.id AND sub_e.type_ = 'found'
       JOIN foundentity sub_fe
       ON sub_e.entity_id = sub_fe.id
       JOIN foundentitylocation sub_fel
       ON sub_fe.id = sub_fel.found_entity_id
       JOIN location sub_l
       ON sub_fel.location_id = sub_l.id AND sub_l.type_ = 'sentence'
       JOIN sentencelocation s
       ON sub_l.location_id = s.id
        -- Extract assumed temporal entity mentions
       JOIN entity temporal_e
       ON t.temporal_entity_id = temporal_e.id AND temporal_e.type_ = 'assumed'
       JOIN assumedentity temporal_ae
       ON temporal_ae.id = temporal_e.entity_id
ORDER BY sub_l.document_id, sub_fe.start;

Query: Find Temporal Terms Associated with Procedure Mentions

This query finds the temporal information for procedures by searching for the ‘procedure’ entity type information found in the foundentitytype table, and specific temporality relations. Temporal terms include dates in many formats as well as other words and phrases. If you are searching for date-time terms only, some additional post-retrieval data cleaning would be required to exclude non-date temporal terms.

SELECT l.document_id     AS doc_id,
   t.category,
   sub_fe.section_name,
   sub_fe.text      AS procedure_term,
   temporal_fe.text AS temporal_term,
   sl.text           AS sentence
FROM temporalityrelation t
        -- Extract subject text, location, and type
        JOIN entity sub_e
        ON t.subject_id = sub_e.id AND sub_e.type_ = 'found'
        JOIN foundentity sub_fe
        ON sub_e.entity_id = sub_fe.id
        JOIN foundentitytype sub_fet
        ON sub_fe.id = sub_fet.found_entity_id
        JOIN foundentitylocation sub_fel
        ON sub_fe.id = sub_fel.found_entity_id
        JOIN location l
        ON sub_fel.location_id = l.id AND l.type_ = 'sentence'
        JOIN sentencelocation sl
        ON l.location_id = sl.id
    -- Extract temporal entity text
        JOIN entity temporal_e
        ON t.temporal_entity_id = temporal_e.id AND temporal_e.type_ = 'found'
        JOIN foundentity temporal_fe
        ON temporal_e.entity_id = temporal_fe.id
WHERE sub_fet.type_name = 'procedure'
AND sub_fet.ontology = 'snomed'
AND t.category = 'specific'
ORDER BY l.document_id, sub_fe.start;

Query: Find Temporal Terms Associated with Disorder, Findings or Morphologic Abnormality Mentions

This query finds all temporal terms associated with mentions of disorders, findings, and morphologic abnormalities by using the specific temporality relation and JOINs to retrieve concept and entity type information from the concept and foundentitytype tables respectively.

SELECT d.id                   AS doc_id,
   t.category,
   sub_fe.section_name,
   sub_fe.text           AS subject_term,
   temporal_fe.text      AS temporal_term,
   sub_c.description      AS subject_concept,
   temporal_c.description AS temporal_concept,
   s.text                 AS sentence
FROM temporalityrelation t
        -- Extract subject text, location
        JOIN entity sub_e
        ON t.subject_id = sub_e.id AND sub_e.type_ = 'found' AND t.category = 'specific'
        JOIN foundentity sub_fe
        ON sub_e.entity_id = sub_fe.id
        JOIN foundentitytype sub_fet
        ON sub_fe.id = sub_fet.found_entity_id
        JOIN foundentitylocation sub_fel
        ON sub_fe.id = sub_fel.found_entity_id
        JOIN location l
        ON sub_fel.location_id = l.id AND l.type_ = 'sentence'
        JOIN sentencelocation s
        ON l.location_id = s.id
    -- Extract subject SNOMED concept
        JOIN foundentityconcept sub_fec
        ON sub_fe.id = sub_fec.found_entity_id
        JOIN concept sub_c
        ON sub_fec.concept_id = sub_c.concept_id AND sub_fec.concept_ontology = sub_c.ontology AND
            sub_c.ontology = 'snomed'
    -- Extract temporal entity text, location
        JOIN entity temporal_e
        ON t.temporal_entity_id = temporal_e.id AND temporal_e.type_ = 'found'
        JOIN foundentity temporal_fe
        ON temporal_e.entity_id = temporal_fe.id
    -- Extract temporal entity SNOMED concept
        JOIN foundentityconcept temporal_fec
        ON temporal_fe.id = temporal_fec.found_entity_id
        JOIN concept temporal_c
        ON temporal_fec.concept_id = temporal_c.concept_id AND
            temporal_fec.concept_ontology = temporal_c.ontology AND temporal_c.ontology = 'snomed'
    -- Find document filename
        JOIN document d
        ON l.document_id = d.id
WHERE sub_fet.type_name IN ('disorder', 'finding', 'morphologic abnormality')
AND sub_fet.ontology = 'snomed'
ORDER BY regexp_replace(d.filename, '.*/', ''), sub_fe.start;