| 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."
)
result = openmed.analyze_text(note, output_format="dict")
events = result["entities"]
anchor = dt.date(2024, 3, 12)
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
- 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.
- Extract events.
openmed.analyze_text(note) for conditions, drugs,
procedures; pick the model that matches your target entities
(choosing-openmed-models).
- 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.
- 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.
- Build event records. One record per event:
(date, granularity, label, surface_text, char_span, temporality, confidence, source_note_id).
- Sort and de-duplicate. Sort by
(date, granularity); merge repeated
mentions of the same event across notes (same label + overlapping date).
- 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)
if date is None:
continue
timeline.append((date, gran, e["label"], e["text"], e["confidence"]))
order = {"Y": 0, "M": 1, "D": 2}
return sorted(timeline, key=lambda r: (r[0], order[r[1]]))
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
