Patient Timelines

The Patient Timelines feature provides an interactive, event-level view of an individual patient's complete clinical history drawn from the OMOP CDM. It displays all clinical events -- conditions, drugs, procedures, measurements, visits, observations, and device exposures -- on a chronological timeline, enabling clinical review, phenotype validation, cohort quality assessment, and case study work.

Access Requirements

Patient Timelines displays Protected Health Information (PHI) at the individual patient level. Access requires:

• The Researcher role (minimum) or a custom role with the view:patients permission
• A data source with a properly configured CDM daimon
• Explicit administrator enablement of patient-level access for your account
• An active data use agreement covering individual-level data access

If you do not see the Patients menu item in the navigation, contact your administrator to request access.

PHI compliance

All patient timeline access is logged in the audit trail with your user ID, the person ID viewed, and a UTC timestamp. Sharing patient-identifiable information outside your authorized data use agreement may violate HIPAA, GDPR, or institutional policies. See Chapter 26 -- Audit Log for details on access monitoring.

Finding a Patient

Navigate to Patients > Patient Timelines. You can locate patients through two methods:

Direct Lookup

Enter an OMOP person_id (integer) in the search field and press Enter. The timeline loads immediately if the person exists in the selected data source.

Cohort Browse

1. Select a generated cohort from the Cohort dropdown.
2. The cohort member list shows person IDs sorted by cohort start date, along with:
   • Cohort start and end dates
   • Age at cohort entry
   • Gender
   • Observation period span
3. Click any row to open that patient's timeline.

This workflow is particularly useful for validating cohort definitions -- review several patients' clinical histories to confirm the cohort phenotype is capturing the intended population.

Phenotype validation

When validating a new cohort definition, review at least 20-30 patient timelines from the generated cohort. Look for:

• True positives -- patients who clearly match the intended phenotype
• False positives -- patients captured by the logic but who do not truly have the condition/exposure
• Edge cases -- patients where the classification is ambiguous

Document your findings to refine the cohort definition iteratively.

Timeline View

The timeline displays events on a horizontal time axis with the following visual elements:

Event Bands

Each clinical domain is rendered as a horizontal band with a distinct color:

Domain	Color	Event Shape
Conditions	Purple	Duration bar (start to end date)
Drugs	Orange	Duration bar (exposure period)
Measurements	Teal	Point marker (measurement date)
Visits	Blue	Duration bar (visit start to end)
Procedures	Green	Point marker (procedure date)
Observations	Gray	Point marker
Device Exposures	Amber	Duration bar

Observation Periods

Gray background bars span each continuous observation period, indicating when the patient was actively enrolled and generating data. Events outside observation periods may indicate data quality issues.

Navigation Controls

• Click-drag -- zoom into a specific time window
• Double-click -- zoom out to the full timeline
• Scroll wheel -- zoom in/out at the cursor position
• Arrow keys -- pan left/right along the time axis
• Minimap -- a compressed overview bar at the bottom shows the full timeline with a viewport indicator

Event Tooltips

Hover over any event to see a tooltip with:

• Standard concept name and concept ID
• Source value and source concept ID
• Start and end dates
• Domain-specific fields (e.g., value and unit for measurements, days supply for drugs)
• Visit context (which visit this event belongs to)

Event Detail Panel

Click any event to open the detail panel on the right side of the screen. The panel displays all available CDM fields for the selected record:

Common Fields

• Concept IDs -- standard concept ID/name and source concept ID/name
• Dates -- start date, end date, and visit date
• Type concept -- provenance of the record (EHR, claim, self-report, etc.)
• Visit link -- click to highlight all events from the same visit encounter

Domain-Specific Fields

Domain	Additional Fields
Conditions	Condition status (active, resolved, history of), stop reason
Drugs	Quantity, days supply, refills, dose, route, sig
Measurements	Value (numeric or concept), unit, range (low/high), operator
Procedures	Modifier, quantity
Observations	Value (numeric, string, or concept), qualifier, unit

Filtering the Timeline

The Filter panel (right sidebar, toggle with the filter icon) provides multiple ways to focus the timeline:

Domain Filters

Toggle visibility of each clinical domain independently. For example, hide conditions and procedures to focus exclusively on the drug-lab relationship.

Date Range

Set a custom date range to zoom into a specific period (e.g., "6 months before and after cohort entry date").

Concept Set Filter

1. Click Filter by Concept Set.
2. Select a saved concept set (e.g., "Type 2 Diabetes Conditions").
3. The timeline highlights matching events with full opacity and fades unrelated events to 20% opacity.
4. Matching event count is shown in the filter badge.

This is invaluable for answering questions like "When did this patient's diabetes-related events begin, and what medications followed?"

Search

Free-text search across concept names and source values to find specific events (e.g., search "metformin" to highlight all metformin-related drug exposures).

Event Chronology Table

Below the visual timeline, a sortable table lists all events in chronological order with columns for date, domain, concept name, source value, and key attributes. This table view is useful for:

• Exporting a patient's event list
• Sorting events by a specific column
• Quickly counting events by domain

Export

Click Export Timeline to download the patient's event data:

• CSV -- full event list with all CDM columns, suitable for case narrative writing or external analysis
• PDF -- formatted timeline report with visual chart and event table, suitable for clinical review or tumor board presentation

Export audit

All timeline exports are logged in the audit trail. The exported file contains PHI and must be handled according to your institutional data governance policies. Do not email exports or store them on unsecured devices.