resolving-clinical-context

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.