building-patient-timelines

Building patient timelines

A patient timeline is a chronologically ordered list of clinical events — diagnoses, medications, procedures, encounters — each carrying a normalized date. OpenMed gives you the events (via analyze_text) and the clinical temporality of each mention (current vs. historical, see resolving-clinical-context); this skill turns those into a sorted timeline. Everything runs on-device — de-identify first if the source notes contain PHI, and keep raw identifiers out of logs.

When to use this skill

After you have extracted entities from one or more notes and want them ordered in time: a longitudinal history, a "course of illness" view, a feed for a summary card, or a pre-step before FHIR export. If you only need to extract entities, use extracting-clinical-entities. If you need negation/temporality on a single mention, use resolving-clinical-context.

Quick start

import datetime as dt
import openmed

note = (
    "Discharge summary, 2024-03-12. Patient admitted 2024-03-08 with chest pain. "
    "History of type 2 diabetes diagnosed in 2019. Started on metformin two days "
    "after admission. Cardiac catheterization performed yesterday."
)

# 1) Extract clinical events (entities carry char offsets: start/end)
result = openmed.analyze_text(note, output_format="dict")
events = result["entities"]   # each: {text, label, confidence, start, end}

# 2) Normalize the temporal frame: an explicit document/anchor date drives
#    resolution of relative expressions ("two days after", "yesterday").
anchor = dt.date(2024, 3, 12)  # parsed from the note header or document metadata

analyze_text returns {text, entities, model_name, timestamp, ...}; each entity is {text, label, confidence, start, end}. Use start/end to locate each event in the source and to find the nearest date expression.

Workflow

1. De-identify if needed. If notes carry PHI, run openmed.deidentify(...) first, or keep the timeline keyed by stable internal IDs — never log raw names/MRNs.
2. Extract events. openmed.analyze_text(note) for conditions, drugs, procedures; pick the model that matches your target entities (choosing-openmed-models).
3. Resolve temporality. For each event, use resolving-clinical-context to tag it current / historical / hypothetical and to drop negated or family-history mentions that should not appear on the patient's own line.
4. Normalize dates. Map each event to a date:
   • Absolute (2024-03-08, March 2019) → parse directly. Record the granularity (day / month / year) — a year-only event sorts to a coarse bucket, not a fake Jan 1.
   • Relative (two days after admission, yesterday, on POD 2) → resolve against an anchor: the document date, admission date, or a prior event's date. Without an anchor, relative expressions are unresolvable — flag them, don't guess.
5. Build event records. One record per event: (date, granularity, label, surface_text, char_span, temporality, confidence, source_note_id).
6. Sort and de-duplicate. Sort by (date, granularity); merge repeated mentions of the same event across notes (same label + overlapping date).
7. Emit. A sorted list for a UI, or FHIR resources (see hand-off).