/building-patient-timelines

name: building-patient-timelines
description: "Assemble a chronological patient timeline from OpenMed-extracted clinical events, normalizing dates and resolving relative time expressions on-device. Use when the user wants to build a patient timeline, order events from clinical notes, reconstruct a longitudinal history, plot a course of illness, or turn analyze_text/deidentify output into a sorted sequence of dated encounters, diagnoses, medications, and procedures. Covers temporal normalization (absolute and relative), event modeling toward FHIR Encounter/Condition.onsetDateTime, anchoring to a document/admission date, and handling undated or ambiguous events. Consumes OpenMed analyze_text entities plus clinical temporality (resolving-clinical-context); produces a sorted event list ready for charting or FHIR export."
license: Apache-2.0
metadata:
  project: OpenMed
  category: analytics-reporting
  pairs: after
  version: "1.0"

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).

Worked example: events → sorted timeline

def to_timeline(events, *, anchor, note_id):
    """events: list of {text,label,start,end,confidence}. anchor: date.
    Returns sorted [(date, granularity, label, text, confidence)]."""
    timeline = []
    for e in events:
        date, gran = resolve_event_date(e, note=note, anchor=anchor)  # your resolver
        if date is None:
            continue  # undated/unresolvable: route to an "undated" bucket, don't drop silently
        timeline.append((date, gran, e["label"], e["text"], e["confidence"]))
    # year-only ('Y') sorts before month ('M') before day ('D') on ties
    order = {"Y": 0, "M": 1, "D": 2}
    return sorted(timeline, key=lambda r: (r[0], order[r[1]]))

# resolve_event_date handles: ISO dates, "March 2019" (gran='M'),
# "yesterday"/"two days after admission" (relative to anchor/admission), POD-n, etc.

Hand-off to / from OpenMed

• **From OpenMed:** `analyze_text` entities (`extracting-clinical-entities`) and

`clinical` context tags (`resolving-clinical-context`) are the inputs. Run `deidentify` upstream when notes carry PHI.

• **To OpenMed / interop:** feed the sorted, dated events into

`exporting-to-fhir` (`openmed.interop`). Map an admission/discharge event to a FHIR `Encounter`, a diagnosis date to `Condition.onsetDateTime`, a med-start to `MedicationStatement.effectiveDateTime`, a procedure to `Procedure.performedDateTime`.

• **Downstream:** the same timeline feeds `etl-to-omop-cdm` (start/end dates on

`condition_occurrence` / `drug_exposure`) and clinical-summary cards.

Edge cases & gotchas

• **No anchor → no relative dates.** "Two days later", "POD 2", "yesterday" are

m