/resolving-clinical-context

name: resolving-clinical-context
description: "Assign negation, temporality, and uncertainty (the ConText axes) to clinical entities extracted by OpenMed, so \"denies chest pain\" is not counted as chest pain and \"history of MI\" is not counted as an active MI. Use after NER when the user needs assertion status, negation detection, family-history / hypothetical / historical flags, or ConText/NegEx-style classification before grounding entities to FHIR or a problem list. Covers openmed.clinical.resolve_negation / resolve_temporality / resolve_uncertainty / resolve_span_context / assert_context_axes, ClinicalAssertion, and the AFFIRMED/NEGATED, RECENT/HISTORICAL/HYPOTHETICAL, CERTAIN/UNCERTAIN constants. Pairs after extracting-clinical-entities."
license: Apache-2.0
metadata:
  project: OpenMed
  category: clinical-nlp
  pairs: after
  version: "1.0"

Resolving clinical context

NER finds *that* a condition was mentioned; it does not tell you whether the patient **has** it. "Patient denies chest pain," "history of MI," and "rule out PE" all surface entities that must **not** be recorded as active, present findings. OpenMed's `openmed.clinical` ConText layer assigns three deterministic axes to each span — **negation**, **temporality**, **uncertainty** — turning raw mentions into clinically faithful assertions before they reach a problem list or FHIR Condition.

When to use

• Immediately after `extracting-clinical-entities`, before grounding,

problem-list building, or analytics.

• The user asks for assertion status, negation handling, "is this affirmed?",

family-history vs. patient, historical vs. active, or hedged/uncertain findings.

• You are about to map entities to FHIR `verificationStatus` /`clinicalStatus`

and need the upstream signal.

Quick start

import openmed
from openmed.clinical import (
    resolve_span_context, assert_context_axes,
    NEGATED, HISTORICAL, HYPOTHETICAL, UNCERTAIN,
)

note = "Patient denies chest pain. History of MI. Concern for PE; rule out DVT."

# 1) Extract entities (registry key, HF id, or local path).
ents = openmed.analyze_text(note, model_name="disease_detection_superclinical",
                            output_format="dict")

# 2) Assign ConText axes per entity. Pass the span text plus a window of cues.
for e in ents:
    span = e["word"]                      # entity surface text
    window = note                         # full sentence/note as modifier context
    ctx = resolve_span_context(span, window)
    print(span, "->", ctx.negation, ctx.temporality, ctx.certainty)

# "chest pain" -> negated   recent      certain     (do NOT record as present)
# "MI"         -> affirmed  historical  certain     (past, not active)
# "PE"         -> affirmed  recent      uncertain   (hedged; flag, don't drop)

`resolve_span_context` returns a `ClinicalContextResult(negation, temporality, certainty)`. For a downstream-grounding-shaped record use `assert_context_axes`, which returns a `ClinicalAssertion` with a `.to_dict()` that omits unset axes.

Workflow

1. **Get entities and their context window.** From `analyze_text`, take each entity's surface text and the surrounding sentence (or the whole short note) as the modifier window. The ConText helpers accept a string, a span mapping with a `text`-like key, or any object exposing `.text`, plus optional `modifier_hits`. 2. **Resolve negation** with `resolve_negation(span, window)` → `AFFIRMED` or `NEGATED`. It uses a NegEx/ConText cue lexicon ("denies," "no evidence of," "without," "negative for"), masks **pseudo-negation** ("not ruled out," "cannot be excluded") so those don't refute the concept, and counts true cues with even/odd parity so double-negation is deterministic. 3. **Resolve temporality** with `resolve_temporality(span, window)` → `RECENT` (default), `HISTORICAL` ("history of," "h/o," "s/p," "resolved," "PMH"), or `HYPOTHETICAL` ("if," "should," "in case of"). A conditional span is treated as hypothetical even if a historical cue is also present. 4. **Resolve uncertainty** with `resolve_uncertainty(span, window)` → `CERTAIN` or `UNCERTAIN` ("concern for," "suspicious for," "rule out," "probable," "vs," "r/o"). Uncertain spans are **flagged, not dropped**. 5. **Apply the axes downstream.** Drop or refute `NEGATED` spans; route `HISTORICAL` to inactive/resolved status; do not record `HYPOTHETICAL` spans as present; mark `UNCERTAIN` spans provisional. Use the constants, not string literals, so a vocabulary change doesn't silently break comparisons.

Hand-off to / from OpenMed

• **From** `extracting-clinical-entities`: this skill consumes `analyze_text`

Disease/Finding entities. Without context resolution, every mention — including negated and historical ones — would be (wrongly) treated as present.

• **OpenMed calls:** `from openmed.clinical import resolve_negation,

resolve_temporality, resolve_uncertainty, resolve_span_context, assert_context_axes, ClinicalAssertion` and the `NEGATED/AFFIRMED`, `HISTORICAL/RECENT/HYPOTHETICAL`, `CERTAIN/UNCERTAIN` constants.

• **To** `reconciling-problem-lists`: feed each entity plus its

`ClinicalContextResult` so active vs. resolved vs. historical is decided correctly and negated mentions are excluded.

• **To FHIR grounding:** `negation=negated` → `verificationStatus=refuted`;

`temporality=historical` → inactive/resolved `clinicalStatus`; `certainty=uncertain` → `verificationStatus=provisional`. The layer emits the axis; it does not build the FHIR record.

Edge cases & gotchas

• **Window scoping matters.** Pass a sentence-sized window, not the whole

document — a negation cue three sentences away should not flip an affirmed finding. Segment first (`segmenting-clinical-sections`) for long notes.

• **Pseudo-negation is handled, double-check anyway.** "Cannot exclude PE" is

affirmed-but-uncertain, not negated. The negation layer masks these cues; the u