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 ```python 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 ```python 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 meaningless without a reference date. Parse the document date / admission date first; if absent, keep the event in an *undated* bucket rather than inventing a date. - **Preserve granularity.** Don't coerce "2019" to `2019-01-01` and then sort it as if it were a precise day — it'll outrank real January events. Carry a granularity flag and sort coarse dates conservatively. - **Drop the wrong people and tenses.** Negated ("no prior MI"), hypothetical ("would consider surgery if…"), and family-history mentions must not land on the patient's timeline. That's what the temporality pass is for. - **Time zones and 2-digit years** are ambiguous — normalize to dates (not datetimes) for clinical timelines unless you genuinely have timestamps, and resolve `dd/mm` vs `mm/dd` from the document locale, not a guess. - **Future/scheduled events** (follow-up appointments) are real but belong on a separate "planned" lane, not interleaved with what already happened. - **No raw PHI in logs.** Log timeline events by label + offset + note id, never the patient's name or the raw note text. ## Standards & references - FHIR R4 Encounter: https://www.hl7.org/fhir/encounter.html - FHIR R4 Condition (`onsetDateTime`, `recordedDate`): https://www.hl7.org/fhir/condition.html - ISO 8601 date/time representation: https://www.iso.org/iso-8601-date-and-time-format.html - Background on clinical temporal expression normalization (TimeML / i2b2 2012 temporal relations task): https://www.i2b2.org/NLP/TemporalRelations/ - OpenMed source: `openmed/processing/` (`analyze_text` output), `openmed.clinical` (temporality), `openmed.interop` (FHIR export).