`patient-journey-explorer` API reference Prototype

Generated from the module's JSDoc and JSON-Schema data contract — npm run docs:api fails on undocumented surface.

Overview

Every safety.viz renderer is one factory call. patientJourneyExplorer(element, settings) empties the container, renders the shared control shell, and returns a chart instance; pass data to setData (or init) and the module validates it against its data contract, structures it, and draws. Settings are merged onto the module's defaults, so callers supply only overrides — column mappings follow ADaM naming out of the box. The same lifecycle (init, setData, setSettings, render, selectSubject, anchor, setLaneEnabled, setTimeMode, setContextWindowDays, setFilter, getContext, getTimeMode, on, off, resize, destroy) is shared by every module and consumed unchanged by the gsm.safety R bindings. See Architecture for how the pieces fit together. The shared parts it is built from are public surface of their own, listed in the kit reference.

Factory

`patientJourneyExplorer([element], [settings])`

Create a patient journey explorer inside a container element. The control shell renders immediately; pass the per-domain records (or one merged array with a domain column) to setData (or init) on the returned instance to validate the data and draw the lanes.

Param	Type	Default	Description
`element` (optional)	`string \| HTMLElement`	`'body'`	Container node, or a CSS selector for it.
`settings` (optional)	`PatientJourneyExplorerSettings`	`{}`	Setting overrides, merged onto DEFAULT_SETTINGS and normalized.

Returns: SafetyPatientJourneyExplorer — The live patient-journey instance.

Methods

`init(data)`

Load data and render: an alias for setData that keeps the two-step create-then-init call shape working.

Param	Type	Default	Description
`data`	`Object \| Array.<Object>`	—	Per-domain arrays under `{ ex, ae, lb, cm, mh, ds }` keys (any case), or one merged array whose rows carry the domain column.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`setData(data)`

Replace the bound data and re-render. The input is split into the six domains (either form), validated against the data contract (throwing, and rendering the message into the target element, when a present domain is missing a required column or no domain has rows), then the controls are rebuilt from the data and the journey drawn for the opening subject.

Param	Type	Default	Description
`data`	`Object \| Array.<Object>`	—	Per-domain arrays under `{ ex, ae, lb, cm, mh, ds }` keys (any case), or one merged array whose rows carry the domain column.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`setSettings(settings)`

Merge setting overrides onto the current settings, re-normalize, re-adopt the state keys that mirror settings (the window width, lane enablement, time mode, filter start values, the configured subject), rebuild the controls, and re-render.

Param	Type	Default	Description
`settings`	`PatientJourneyExplorerSettings`	—	Setting overrides to merge.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`render()`

Redraw everything from the current data, settings and control state: destroy the lane charts, restructure for the subject and filters, resolve the anchor and its context bundle, and rebuild the notes, the lane stack, the axis strip, the keyboard overlay, the panel and the source drawer.

Returns: void —

`selectSubject(subjectId)`

Select a subject by id (string-compared). An unknown id changes nothing and warns. Any anchor is cleared first (with the null anchor and context events), then the journey is redrawn and pjeSubjectSelected plus the library's shared participantsSelected event are dispatched.

Param	Type	Default	Description
`subjectId`	`string \| number`	—	The participant id to select.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`anchor(eventId)`

Anchor time on an event by its normalized id (`'AE-7'`): rebuild the context bundle, redraw the highlight, the axis labels and the panel, and emit pjeEventAnchored and pjeContextChanged. `anchor(null)` clears the anchor and emits both with null. An id that is not a placeable event of the current subject warns and changes nothing.

Param	Type	Default	Description
`eventId`	`string`	—	The event id to anchor on, or null to clear.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`setLaneEnabled(laneKey, enabled)`

Toggle one lane. An unknown key warns and is a no-op. Emits pjeLaneToggled, and pjeContextChanged when anchored (the window's contents depend on the enabled lanes).

Param	Type	Default	Description
`laneKey`	`string`	—	The lane key (`exposure`, `doseChanges`, `adverseEvents`, `labs`, `conMeds`, `medicalHistory`, `disposition`).
`enabled`	`boolean`	—	Whether the lane is shown.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`setTimeMode(mode)`

Switch the time axis between study days and calendar dates. `'date'` is refused (with a warning) when no reference date resolves for the subject or date mode is not allowed. Emits pjeTimeModeChanged.

Param	Type	Default	Description
`mode`	`string`	—	`'day'` or `'date'`.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`setContextWindowDays(days)`

Set the context-window half-width in elapsed days (coerced as in syncSettings; 0 means the anchor day only) and re-derive the bundle when anchored.

Param	Type	Default	Description
`days`	`number \| string`	—	The half-width in days.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`setFilter(valueCol, selection)`

Set one filter programmatically, using the same grammar filterMatches accepts (null = no restriction, an array = membership, a scalar = equality; for a flag filter, its `flag_value` or null). An unknown column warns and is a no-op. Re-renders, re-derives the bundle when anchored and emits pjeFilterChanged.

Param	Type	Default	Description
`valueCol`	`string`	—	The filter's `value_col`.
`selection`	`*`	—	The next selection.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`getContext()`

The current context bundle, or null when nothing is anchored. A read model: consumers must not mutate it.

Returns: ContextBundle — The bundle (the ContextBundle typedef in patient-journey-explorer/anchor.js), or null.

`getTimeMode()`

The active time-axis mode.

Returns: string — `'day'` or `'date'`.

`on(name, handler)`

Register a listener for one of the module events (pjeSubjectSelected, pjeEventAnchored, pjeContextChanged, pjeLaneToggled, pjeFilterChanged, pjeTimeModeChanged, participantsSelected); the handler receives the event's detail.

Param	Type	Default	Description
`name`	`string`	—	The event name.
`handler`	`function`	—	The listener.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`off(name, [handler])`

Remove a listener, or every listener for the event when no handler is given.

Param	Type	Default	Description
`name`	`string`	—	The event name.
`handler` (optional)	`function`	—	The listener to remove.

Returns: SafetyPatientJourneyExplorer — The instance, for chaining.

`resize()`

Resize every live lane chart and re-sync the keyboard overlay geometry. For host layouts that change the container size without a window resize — e.g. the R htmlwidget binding.

Returns: void —

`destroy()`

Tear the explorer down: destroy the lane charts, remove the window-resize, theme and key listeners, drop every registered event listener, and empty the target element. The instance cannot be reused afterwards — create a new one via the factory instead.

Returns: void —

Settings

Setting	Type	Default	Description
`id_col`	`string`	`'USUBJID'`	Participant identifier column, present in every domain; the subject picker lists its distinct values across all domains and the participantsSelected event carries it (PJE-SUBJ-001, PJE-EVT-002).
`domain_col`	`string`	`'DOMAIN'`	For the merged-array input form, the column whose value names each row's domain (`AE`, `LB`, `EX`, `CM`, `MH`, `DS`, or the ADaM spellings `ADAE` …); rows with any other value are dropped with a named reason (PJE-DATA-001, PJE-DATA-002).
`subject`	`string \| null`	`null`	The subject to open on; null opens on the first subject in sorted order (PJE-SUBJ-001).
`time`	`Object`	—	Time-axis configuration: `mode` (`'day'` or `'date'`, the opening display), `ref_date_col` (`'TRTSDT'`; the column holding the date of study day 1, read from any row of any domain and preferred over deriving it from a recorded date), and `allow_date_mode` (true; when false the calendar-date control is not offered and `mode` is forced to `'day'`). The plan's `day_col` / `date_col` keys are accepted as generic `--DY` / `--DTC` patterns expanded per domain and prepended to each domain's fallback chain (PJE-TIME-001, PJE-TIME-002).
`context_window_days`	`number`	`30`	Half-width of the anchor context window in elapsed days, inclusive on both sides; coerced to a non-negative integer, and 0 means the anchor day only (PJE-CFG-004, PJE-ANCH-002).
`ex_trt_col`	`string`	`'EXTRT'`	Exposure treatment name column; the exposure lane draws one row per distinct value and each record's label and category come from it.
`ex_dose_col`	`string`	`'EXDOSE'`	Exposure dose column; consecutive records with different numeric doses derive the dose-change events (PJE-DERIV-001). A record with both treatment and dose blank is dropped with a named reason.
`ex_dosu_col`	`string`	`'EXDOSU'`	Exposure dose unit column, appended to the dose in tooltips and dose-change labels.
`ex_stdy_col`	`string \| Array.<string>`	`['ASTDY','EXSTDY']`	Exposure start study day, as a column name or a fallback chain resolved per row; required in exposure data. A record with no usable start day is kept but not drawn (PJE-LANE-008).
`ex_endy_col`	`string \| Array.<string>`	`['AENDY','EXENDY']`	Exposure end study day, as a column name or a fallback chain; a blank end is `end not recorded` (exposure has no outcome column).
`ex_stdtc_col`	`string`	`'EXSTDTC'`	Exposure start date column (`--DTC`), shown as recorded; a full date labels the record in date mode and a partial one never positions it (PJE-TIME-003).
`ae_term_col`	`string`	`'AETERM'`	Adverse-event verbatim term column; the tooltip's secondary line when it differs from the decoded term, and the label when the decode is blank. A record with both blank is dropped with a named reason.
`ae_decod_col`	`string`	`'AEDECOD'`	Adverse-event preferred term column: the mark label, and the key the "prior events with the same preferred term" context list matches on (PJE-CTX-004).
`ae_soc_col`	`string`	`'AEBODSYS'`	Adverse-event body-system column, shown as the record's category.
`ae_stdy_col`	`string \| Array.<string>`	`['ASTDY','AESTDY']`	Adverse-event onset study day, as a column name or a fallback chain; required in adverse-event data.
`ae_endy_col`	`string \| Array.<string>`	`['AENDY','AEENDY']`	Adverse-event resolution study day, as a column name or a fallback chain. A blank end is `ongoing` only when `ae_out_col` says so, otherwise `end not recorded`; an end before the start is kept as a single-day mark and counted (PJE-DATA-008).
`ae_sev_col`	`string`	`'AESEV'`	Adverse-event severity column, ranked by `ae_severity_values`; severity is drawn as bar height and border weight at one opaque fill, and a blank value draws a hatched mark named "severity not recorded" (PJE-ACC-002). The plan's lane-level `severityCol` is an alias.
`ae_ser_col`	`string`	`'AESER'`	Adverse-event seriousness column, compared with `ae_serious_value`; serious events get a filled start dot, an escalation ring and an `SAE` tag. The plan's lane-level `seriousCol` is an alias.
`ae_rel_col`	`string`	`'AEREL'`	Adverse-event relatedness column, shown in the tooltip as recorded.
`ae_stdtc_col`	`string`	`'AESTDTC'`	Adverse-event onset date column (`--DTC`), shown as recorded (PJE-TIME-003, PJE-TIME-004).
`ae_severity_values`	`Array.<string>`	`['MILD','MODERATE','SEVERE']`	Severity levels in ascending rank; a value outside the list keeps rank 0 and draws at the moderate height. An empty list falls back to the default.
`ae_serious_value`	`string`	`'Y'`	The `ae_ser_col` value (case-insensitive) that marks a serious event (PJE-FILT-001).
`ae_out_col`	`string \| null`	`'AEOUT'`	Adverse-event outcome column, read only when the end day is blank: an event is `ongoing` when this cell is one of `ae_ongoing_values`, and `end not recorded` otherwise (D16).
`ae_ongoing_values`	`Array.<string>`	`['NOT RECOVERED/NOT RESOLVED','RECOVERING/RESOLVING','ONGOING','N']`	Outcome values (upper-cased, trimmed) that assert an event is still running when its end day is blank.
`lb_test_col`	`string`	`'LBTEST'`	Lab test name column; required in lab data. A record with a blank name is dropped with a named reason; `lb_tests` matches this column or `lb_testcd_col`, case-insensitively.
`lb_testcd_col`	`string`	`'LBTESTCD'`	Lab test code column; `lb_tests` entries match either the name or the code, so both `'Alanine Aminotransferase'` and `'ALT'` select the same series.
`lb_value_col`	`string`	`'LBSTRESN'`	Lab numeric result column; required in lab data. A non-numeric result is dropped with a named reason.
`lb_lo_col`	`string`	`'LBSTNRLO'`	Lab lower limit of normal column; with `lb_hi_col` draws the reference band and the `× LLN` ratio (PJE-LANE-005).
`lb_hi_col`	`string`	`'LBSTNRHI'`	Lab upper limit of normal column; with `lb_lo_col` draws the reference band and the `× ULN` ratio.
`lb_day_col`	`string \| Array.<string>`	`['LBDY','ADY']`	Lab study day, as a column name or a fallback chain; required in lab data.
`lb_nrind_col`	`string`	`'LBNRIND'`	Lab normal-range indicator column: a present value other than `lb_normal_value` marks the point abnormal by flag (PJE-CTX-002); `HIGH`/`LOW` pick the glyph and `HH`/`LL` add the escalation ring.
`lb_unit_col`	`string`	`'LBSTRESU'`	Lab result unit column, appended to values in labels and the panel.
`lb_dtc_col`	`string`	`'LBDTC'`	Lab collection date column (`--DTC`), shown as recorded.
`lb_tests`	`Array.<string>`	`['Alanine Aminotransferase','Aspartate Aminotransferase','Bilirubin','Alkaline Phosphatase']`	The lab tests drawn as small multiples, in this order, matched case-insensitively against the test name or code; an empty list means every test present. The plan's `labTests` and lane-level `tests` are aliases.
`lb_normal_value`	`string`	`'NORMAL'`	The `lb_nrind_col` value meaning within range; any other non-blank value is abnormal by flag, and a blank value is not abnormal.
`lb_baseline_flag_col`	`string \| null`	`'ABLFL'`	Analysis-baseline flag column, consulted first when resolving a test's baseline (D17); null skips the flag rule.
`lb_baseline_flag_value`	`string`	`'Y'`	The `lb_baseline_flag_col` value marking the baseline record.
`lb_baseline_day`	`number`	`1`	Fallback baseline rule: the last value on or before this study day, used only when no flagged record exists (PJE-DERIV-002).
`lb_change_factor`	`number`	`2`	Symmetric change rule: a value at least this many times, or at most 1/this of, the baseline is abnormal by change (D28). Must exceed 1.
`cm_trt_col`	`string`	`'CMTRT'`	Con-med name column; required in con-med data. A record with a blank name is dropped with a named reason.
`cm_class_col`	`string`	`'CMCLAS'`	Con-med class column (ATC class), the record's category and the multiselect filter's values; `cm_uncoded_value` is kept as its own bucket (PJE-FILT-003).
`cm_dose_col`	`string`	`'CMDOSE'`	Con-med dose column, shown with the route as the tooltip's secondary line when present.
`cm_route_col`	`string`	`'CMROUTE'`	Con-med route column, shown with the dose as the tooltip's secondary line when present.
`cm_stdy_col`	`string \| Array.<string>`	`['ASTDY','CMSTDY']`	Con-med start study day, as a column name or a fallback chain. A con-med with no usable start is kept, not drawn, and never asserted active at an anchor (PJE-CTX-001).
`cm_endy_col`	`string \| Array.<string>`	`['AENDY','CMENDY']`	Con-med end study day, as a column name or a fallback chain; a blank end is `end not recorded` unless `cm_out_col` says ongoing.
`cm_stdtc_col`	`string`	`'CMSTDTC'`	Con-med start date column (`--DTC`), shown as recorded.
`cm_uncoded_value`	`string`	`'UNCODED'`	The `cm_class_col` value meaning "not coded", kept as an ordinary selectable class.
`cm_out_col`	`string \| null`	`null`	Con-med ongoing-indicator column (`CMENRTPT`, `CMONGO`, …), read only when the end day is blank; null (the default — the pilot data has none) makes every blank end `end not recorded` (D16).
`cm_ongoing_values`	`Array.<string>`	`['ONGOING','Y','CONTINUING']`	Values of `cm_out_col` (upper-cased, trimmed) that assert a con-med is still running when its end day is blank.
`mh_term_col`	`string`	`'MHTERM'`	Medical-history verbatim term column; the label when the decode is blank. A record with both blank is dropped with a named reason.
`mh_decod_col`	`string`	`'MHDECOD'`	Medical-history decoded term column, the mark label when present.
`mh_cat_col`	`string`	`'MHCAT'`	Medical-history category column, shown as the record's category.
`mh_day_col`	`string \| Array.<string>`	`'MHDY'`	Medical-history collection study day (the screening visit), the mark's position under the default `mh_day_source` (D18).
`mh_day_source`	`string`	`'collection'`	Which day places a medical-history mark: `'collection'` (`mh_day_col`, the day it was recorded) or `'onset'` (`mh_onset_stdy_col`); anything else falls back to `'collection'` with a warning.
`mh_onset_stdy_col`	`string \| Array.<string>`	`['ASTDY', 'MHSTDY']`	Medical-history onset study day, as a column name or a fallback chain resolved per row (the ADaM `ASTDY`, then the SDTM `MHSTDY`, so the plan's vocabulary places too — D15); the tooltip's onset text by default, and the mark position under `mh_day_source: 'onset'`.
`mh_strtpt_col`	`string`	`'MHSTRTPT'`	Medical-history onset relative-timing column (`BEFORE`, …), the tooltip's onset text when no onset day or date resolves.
`mh_enrtpt_col`	`string`	`'MHENRTPT'`	Medical-history end relative-timing column; `ONGOING` adds "still present" to the tooltip.
`mh_onset_dtc_col`	`string`	`'MHSTDTC'`	Medical-history onset date column (`--DTC`), shown as recorded in the onset text.
`ds_decod_col`	`string`	`'DSDECOD'`	Disposition decoded term column, the mark label; required in disposition data. A record with a blank decode is dropped with a named reason.
`ds_term_col`	`string`	`'DSTERM'`	Disposition verbatim term column, the tooltip's secondary line when it differs from the decode.
`ds_cat_col`	`string`	`'DSCAT'`	Disposition category column (`DISPOSITION EVENT`, `PROTOCOL MILESTONE`, …), the record's category and the key `ds_reference_cats` matches (D19).
`ds_stdy_col`	`string \| Array.<string>`	`'DSSTDY'`	Disposition study day, as a column name or a fallback chain.
`ds_dtc_col`	`string`	`'DSSTDTC'`	Disposition date column (`--DTC`), shown as recorded.
`ds_reference_cats`	`Array.<string>`	`['DISPOSITION EVENT']`	Disposition categories (upper-cased, trimmed) whose rows draw a full-height dashed rule across every lane; every disposition row still draws its own mark. An empty list draws a rule for every row, which is legal but noisy and warned once.
`lanes`	`Object`	—	Per-lane display configuration keyed by lane (`exposure`, `doseChanges`, `adverseEvents`, `labs`, `conMeds`, `medicalHistory`, `disposition`), each `{ enabled, label, group }` merged key by key onto the default; null disables a lane, an unknown lane key is dropped with a warning (PJE-CFG-003). Lane-level `severityCol`, `seriousCol` and `tests` are lifted to `ae_sev_col`, `ae_ser_col` and `lb_tests`; `domain`, `derivedFrom` and `smallMultiple` are accepted and ignored.
`lane_groups`	`Array.<Object>`	—	Collapsible lane groups in stack order, each `{ key, label, collapsed }` (`treatment`, `events`, `context` by default); a group with no enabled lane is dropped at render time (PJE-LANE-003). The plan's `laneGroups` is an alias.
`filters`	`Array.<Object>`	—	Sidebar filter specs, each with a `domain` (the only domain the filter applies to) and the shared filter contract keys: `type: 'flag'` with a `flag_value` renders a checkbox (the special `flag_value: '__abnormal__'` keeps only labs failing the abnormality rule), `multiple: true` renders the shell multiselect, and the rest follow `{ value_col, label, start, all }`. Specs without a `value_col` (or the plan's `col` alias) or without a recognized `domain` are dropped with a warning; a filter whose column is absent from its domain's data is dropped at render time with the library's standard warning (PJE-FILT-001 … PJE-FILT-004).
`source_url_template`	`string \| null`	`null`	Optional external link template for every source row, e.g. `'https://edc.example/{domain}/{USUBJID}/{AESEQ}'`: `{domain}` is the domain code and `{COLUMN}` the row's URI-encoded value; a row lacking a named column gets no link. null renders no link (PJE-SRC-002). The plan's `sourceUrlTemplate` is an alias.
`source_url_label`	`string`	`'Open source record'`	Link text for the external source link.
`on_select_subject`	`function \| null`	`null`	Callback `(subjectId, detail)` when the subject changes; kept only when a function. The plan's `onSelectSubject` is an alias (PJE-EVT-001).
`on_anchor_event`	`function \| null`	`null`	Callback `(event, context)` when a mark is anchored or the anchor is cleared (both null on clear). The plan's `onAnchorEvent` is an alias.
`on_context_change`	`function \| null`	`null`	Callback `(context)` whenever the context bundle changes while anchored, and with null when cleared. The plan's `onContextChange` is an alias.
`row_height`	`number`	`26`	Pixels per row inside a categorical lane; a positive integer. The plan's `rowHeight` is an alias.
`row_height_min`	`number`	`18`	Floor for `row_height` when `fit_to_height` scales the stack down.
`max_rows_per_lane`	`number`	`12`	Rows drawn per categorical lane before the remainder is counted in prose, in the lane's documented sort order (PJE-LANE-010). The plan's `maxRowsPerLane` is an alias.
`lab_height`	`number`	`96`	Pixels per lab small multiple. The plan's `labHeight` is an alias.
`lab_height_min`	`number`	`64`	Floor for `lab_height` when `fit_to_height` scales the stack down.
`height`	`number`	`760`	Pixel height of the lane column; taller stacks scroll and say so (PJE-LANE-009, D21). 760 is the height at which the Definition-of-Done participant (four lab tests, nine con-meds, a screening-history lane) fits at the row and lab floors; 720 left it 16px short.
`fit_to_height`	`boolean`	`true`	Scale row and lab heights (down to their floors) so the opening stack fits `height` before the column scrolls (D21).
`width`	`string`	`'100%'`	Widget width, applied as the container element's style width; carried for the R widget binding.
`page_size`	`number`	`10`	Rows per page in the source-row drawer's tables.

Data contract

safety.viz patient-journey-explorer data contract

One subject's safety record across six CDISC domains — exposure (EX), adverse events (AE), labs (LB), concomitant medications (CM), medical history (MH) and disposition (DS) — drawn as stacked lanes on one shared study-day axis. Data arrives either as an object of per-domain arrays (keys matched case-insensitively: { ae, lb, ex, cm, mh, ds }) or as one merged array whose rows carry a domain column named by settings.domain_col (PJE-DATA-001). No domain is individually required: any one is enough to draw a partial journey, and absent domains render an explanatory empty lane (PJE-DATA-005). Column names are supplied by the settings mapping; day columns accept an ordered fallback chain resolved per row (PJE-DATA-007). Rows that cannot be used are dropped with a named, counted, exportable reason (PJE-DATA-003); rows with no usable study day are kept and named in prose rather than dropped (PJE-LANE-008). This schema documents the contract and names, per domain, the settings keys whose columns must be present (requiredSettings); it validates no rows — row-level rules are the module's own drop table.

Field	Type	Required	Default	Description
`ex`	`array`	no	—	Exposure records (an ADEX or EX projection), one row per dosing record: the participant id, the treatment name (ex_trt_col), the dose and unit (ex_dose_col, ex_dosu_col), the start and end study days (ex_stdy_col, ex_endy_col — fallback chains, ASTDY/EXSTDY and AENDY/EXENDY by default) and optionally the start date (ex_stdtc_col). The exposure lane draws one bar segment per record; consecutive records with different doses derive the dose-change events (PJE-DERIV-001, PJE-LANE-006). A row with both treatment and dose blank is dropped with a named reason; a row with no usable start day is kept but not drawn.
`ae`	`array`	no	—	Adverse-event records (an ADAE or AE projection), one row per event: the participant id, the verbatim and preferred terms (ae_term_col, ae_decod_col), the body system (ae_soc_col), onset and resolution study days (ae_stdy_col, ae_endy_col — ASTDY/AESTDY and AENDY/AEENDY by default), severity, seriousness and relatedness (ae_sev_col, ae_ser_col, ae_rel_col), the outcome (ae_out_col, which decides whether a blank end day means ongoing or simply not recorded, D16) and optionally the onset date (ae_stdtc_col). Anchoring an event opens the ±N-day context window (PJE-ANCH-001). A row with both terms blank is dropped with a named reason; an end day before the start day is kept as a single-day mark and counted (PJE-DATA-008).
`lb`	`array`	no	—	Lab records (an ADLB or LB projection), one row per result: the participant id, the test name and code (lb_test_col, lb_testcd_col — lb_tests matches either), the numeric result and unit (lb_value_col, lb_unit_col), the reference range (lb_lo_col, lb_hi_col), the normal-range indicator (lb_nrind_col), the study day (lb_day_col — LBDY/ADY by default), the analysis-baseline flag (lb_baseline_flag_col, consulted first when resolving a test's baseline, D17) and optionally the collection date (lb_dtc_col). Each configured test draws as a small multiple with its reference band (PJE-LANE-005); a point is abnormal by flag when the indicator is present and not normal, or by change when it is at least lb_change_factor times, or at most 1/lb_change_factor of, the baseline (PJE-CTX-002). A row with a blank test name or a non-numeric result is dropped with a named reason.
`cm`	`array`	no	—	Concomitant-medication records (an ADCM or CM projection), one row per medication course: the participant id, the medication name (cm_trt_col), its class (cm_class_col; the uncoded value is kept as its own selectable bucket, PJE-FILT-003), optional dose and route (cm_dose_col, cm_route_col), start and end study days (cm_stdy_col, cm_endy_col — ASTDY/CMSTDY and AENDY/CMENDY by default), optionally an ongoing indicator (cm_out_col; none by default, so a blank end day is 'end not recorded' rather than asserted ongoing) and the start date (cm_stdtc_col). Con-meds active at an anchor are those started on or before it and not ended before it; one with no usable start day is never asserted active and is counted as not evaluated (PJE-CTX-001). A row with a blank name is dropped with a named reason.
`mh`	`array`	no	—	Medical-history records (an ADMH or MH projection), one row per condition: the participant id, the verbatim and decoded terms (mh_term_col, mh_decod_col — the decode is preferred as the label because verbatim terms are often scrubbed), the category (mh_cat_col), the collection study day (mh_day_col, the screening visit, where the mark is drawn by default, D18), the onset study day, date and relative-timing text (mh_onset_stdy_col, mh_onset_dtc_col, mh_strtpt_col — named in the tooltip) and the end relative-timing text (mh_enrtpt_col; ONGOING adds 'still present'). Set mh_day_source to 'onset' to place marks at onset instead. A row with both terms blank is dropped with a named reason.
`ds`	`array`	no	—	Disposition records (a DS projection), one row per disposition event or milestone: the participant id, the decoded and verbatim terms (ds_decod_col, ds_term_col), the category (ds_cat_col), the study day (ds_stdy_col) and optionally the date (ds_dtc_col). Every row draws a mark in the disposition lane; only rows whose category is in ds_reference_cats (DISPOSITION EVENT by default) draw the full-height dashed rule across every lane (D19). A row with a blank decode is dropped with a named reason.
`settings`	`object`	yes	—	Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied. Column settings are flat, snake_case and domain-prefixed; the plan's camelCase spellings (contextWindowDays, onAnchorEvent, sourceUrlTemplate, lane-level severityCol/seriousCol/tests, filters[].col, time.day_col/date_col) are accepted as aliases and normalized with a console warning each (PJE-CFG-002).
`settings.id_col`	`string`	no	`USUBJID`	Participant identifier column, present in every domain; the subject picker lists its distinct values across all domains and the participantsSelected event carries it (PJE-SUBJ-001, PJE-EVT-002).
`settings.domain_col`	`string`	no	`DOMAIN`	For the merged-array input form, the column whose value names each row's domain (AE, LB, EX, CM, MH, DS, or the ADaM spellings ADAE …, case-insensitively); rows with any other value are dropped with a named reason (PJE-DATA-002).
`settings.subject`	`string,null`	no	—	The subject to open on; null opens on the first subject in sorted order (PJE-SUBJ-001).
`settings.time`	`object`	no	—	Time-axis configuration: mode ('day' or 'date', the opening display), ref_date_col ('TRTSDT', the column holding the date of study day 1, read from any row of any domain) and allow_date_mode (true; when false the calendar-date control is not offered). The plan's day_col / date_col keys are accepted as generic --DY / --DTC patterns expanded per domain (PJE-TIME-001, PJE-TIME-002).
`settings.time.mode`	`string`	no	`day`	The opening display mode: study day, or calendar date (only when allow_date_mode is true and a reference date resolves for the subject). The scale stays linear in days in both modes; date mode relabels ticks, tooltips and panel text (D7).
`settings.time.ref_date_col`	`string`	no	`TRTSDT`	Column holding the date of study day 1 (first dose), read from any row of any domain and preferred over deriving the reference from a recorded --DTC date plus its study day (D30).
`settings.time.allow_date_mode`	`boolean`	no	`true`	Whether the calendar-date display is offered at all; false forces mode to 'day'.
`settings.context_window_days`	`number`	no	`30`	Half-width of the anchor context window in elapsed days, inclusive on both sides; coerced to a non-negative integer, and 0 means the anchor day only (PJE-CFG-004, PJE-ANCH-002).
`settings.ex_trt_col`	`string`	no	`EXTRT`	Exposure treatment name column; the exposure lane draws one row per distinct value and each record's label and category come from it.
`settings.ex_dose_col`	`string`	no	`EXDOSE`	Exposure dose column; consecutive records with different numeric doses derive the dose-change events (PJE-DERIV-001). A record with both treatment and dose blank is dropped.
`settings.ex_dosu_col`	`string`	no	`EXDOSU`	Exposure dose unit column, appended to the dose in tooltips and dose-change labels.
`settings.ex_stdy_col`	`string,array`	no	`ASTDY,EXSTDY`	Exposure start study day, as a column name or a fallback chain resolved per row; required in exposure data. A record with no usable start day is kept but not drawn (PJE-LANE-008).
`settings.ex_endy_col`	`string,array`	no	`AENDY,EXENDY`	Exposure end study day, as a column name or a fallback chain; a blank end is 'end not recorded' (exposure has no outcome column).
`settings.ex_stdtc_col`	`string`	no	`EXSTDTC`	Exposure start date column (--DTC), shown as recorded; a full date labels the record in date mode and a partial one never positions it (PJE-TIME-003).
`settings.ae_term_col`	`string`	no	`AETERM`	Adverse-event verbatim term column; the tooltip's secondary line when it differs from the decoded term, and the label when the decode is blank. A record with both blank is dropped.
`settings.ae_decod_col`	`string`	no	`AEDECOD`	Adverse-event preferred term column: the mark label, and the key the 'prior events with the same preferred term' context list matches on (PJE-CTX-004).
`settings.ae_soc_col`	`string`	no	`AEBODSYS`	Adverse-event body-system column, shown as the record's category.
`settings.ae_stdy_col`	`string,array`	no	`ASTDY,AESTDY`	Adverse-event onset study day, as a column name or a fallback chain; required in adverse-event data.
`settings.ae_endy_col`	`string,array`	no	`AENDY,AEENDY`	Adverse-event resolution study day, as a column name or a fallback chain. A blank end is 'ongoing' only when ae_out_col says so, otherwise 'end not recorded'; an end before the start is kept as a single-day mark and counted (PJE-DATA-008).
`settings.ae_sev_col`	`string`	no	`AESEV`	Adverse-event severity column, ranked by ae_severity_values; drawn as bar height and border weight at one opaque fill, and a blank value draws a hatched mark named 'severity not recorded' (PJE-ACC-002).
`settings.ae_ser_col`	`string`	no	`AESER`	Adverse-event seriousness column, compared with ae_serious_value; serious events get a filled start dot, an escalation ring and an SAE tag.
`settings.ae_rel_col`	`string`	no	`AEREL`	Adverse-event relatedness column, shown in the tooltip as recorded.
`settings.ae_stdtc_col`	`string`	no	`AESTDTC`	Adverse-event onset date column (--DTC), shown as recorded (PJE-TIME-003, PJE-TIME-004).
`settings.ae_severity_values`	`array`	no	`MILD,MODERATE,SEVERE`	Severity levels in ascending rank; a value outside the list keeps rank 0 and draws at the moderate height. An empty list falls back to the default.
`settings.ae_serious_value`	`string`	no	`Y`	The ae_ser_col value (case-insensitive) that marks a serious event (PJE-FILT-001).
`settings.ae_out_col`	`string,null`	no	`AEOUT`	Adverse-event outcome column, read only when the end day is blank: the event is 'ongoing' when this cell is one of ae_ongoing_values, and 'end not recorded' otherwise (D16).
`settings.ae_ongoing_values`	`array`	no	`NOT RECOVERED/NOT RESOLVED,RECOVERING/RESOLVING,ONGOING,N`	Outcome values (upper-cased, trimmed) that assert an event is still running when its end day is blank.
`settings.lb_test_col`	`string`	no	`LBTEST`	Lab test name column; required in lab data. A record with a blank name is dropped; lb_tests matches this column or lb_testcd_col, case-insensitively.
`settings.lb_testcd_col`	`string`	no	`LBTESTCD`	Lab test code column; lb_tests entries match either the name or the code, so 'Alanine Aminotransferase' and 'ALT' select the same series.
`settings.lb_value_col`	`string`	no	`LBSTRESN`	Lab numeric result column; required in lab data. A non-numeric result is dropped with a named reason.
`settings.lb_lo_col`	`string`	no	`LBSTNRLO`	Lab lower limit of normal column; with lb_hi_col draws the reference band and the × LLN ratio (PJE-LANE-005).
`settings.lb_hi_col`	`string`	no	`LBSTNRHI`	Lab upper limit of normal column; with lb_lo_col draws the reference band and the × ULN ratio.
`settings.lb_day_col`	`string,array`	no	`LBDY,ADY`	Lab study day, as a column name or a fallback chain; required in lab data.
`settings.lb_nrind_col`	`string`	no	`LBNRIND`	Lab normal-range indicator column: a present value other than lb_normal_value marks the point abnormal by flag (PJE-CTX-002); HIGH/LOW pick the glyph and HH/LL add the escalation ring.
`settings.lb_unit_col`	`string`	no	`LBSTRESU`	Lab result unit column, appended to values in labels and the panel.
`settings.lb_dtc_col`	`string`	no	`LBDTC`	Lab collection date column (--DTC), shown as recorded.
`settings.lb_tests`	`array`	no	`Alanine Aminotransferase,Aspartate Aminotransferase,Bilirubin,Alkaline Phosphatase`	The lab tests drawn as small multiples, in this order, matched case-insensitively against the test name or code; an empty list means every test present. The plan's labTests and lane-level tests are aliases.
`settings.lb_normal_value`	`string`	no	`NORMAL`	The lb_nrind_col value meaning within range; any other non-blank value is abnormal by flag, and a blank value is not abnormal.
`settings.lb_baseline_flag_col`	`string,null`	no	`ABLFL`	Analysis-baseline flag column, consulted first when resolving a test's baseline (D17); null skips the flag rule.
`settings.lb_baseline_flag_value`	`string`	no	`Y`	The lb_baseline_flag_col value marking the baseline record.
`settings.lb_baseline_day`	`number`	no	`1`	Fallback baseline rule: the last value on or before this study day, used only when no flagged record exists (PJE-DERIV-002).
`settings.lb_change_factor`	`number`	no	`2`	Symmetric change rule: a value at least this many times, or at most 1/this of, the baseline is abnormal by change (D28). Must exceed 1.
`settings.cm_trt_col`	`string`	no	`CMTRT`	Con-med name column; required in con-med data. A record with a blank name is dropped with a named reason.
`settings.cm_class_col`	`string`	no	`CMCLAS`	Con-med class column (ATC class), the record's category and the multiselect filter's values; cm_uncoded_value is kept as its own bucket (PJE-FILT-003).
`settings.cm_dose_col`	`string`	no	`CMDOSE`	Con-med dose column, shown with the route as the tooltip's secondary line when present.
`settings.cm_route_col`	`string`	no	`CMROUTE`	Con-med route column, shown with the dose as the tooltip's secondary line when present.
`settings.cm_stdy_col`	`string,array`	no	`ASTDY,CMSTDY`	Con-med start study day, as a column name or a fallback chain. A con-med with no usable start is kept, not drawn, and never asserted active at an anchor (PJE-CTX-001).
`settings.cm_endy_col`	`string,array`	no	`AENDY,CMENDY`	Con-med end study day, as a column name or a fallback chain; a blank end is 'end not recorded' unless cm_out_col says ongoing.
`settings.cm_stdtc_col`	`string`	no	`CMSTDTC`	Con-med start date column (--DTC), shown as recorded.
`settings.cm_uncoded_value`	`string`	no	`UNCODED`	The cm_class_col value meaning 'not coded', kept as an ordinary selectable class.
`settings.cm_out_col`	`string,null`	no	—	Con-med ongoing-indicator column (CMENRTPT, CMONGO, …), read only when the end day is blank; null (the default — the pilot data has none) makes every blank end 'end not recorded' (D16).
`settings.cm_ongoing_values`	`array`	no	`ONGOING,Y,CONTINUING`	Values of cm_out_col (upper-cased, trimmed) that assert a con-med is still running when its end day is blank.
`settings.mh_term_col`	`string`	no	`MHTERM`	Medical-history verbatim term column; the label when the decode is blank. A record with both blank is dropped with a named reason.
`settings.mh_decod_col`	`string`	no	`MHDECOD`	Medical-history decoded term column, the mark label when present.
`settings.mh_cat_col`	`string`	no	`MHCAT`	Medical-history category column, shown as the record's category.
`settings.mh_day_col`	`string,array`	no	`MHDY`	Medical-history collection study day (the screening visit), the mark's position under the default mh_day_source (D18).
`settings.mh_day_source`	`string`	no	`collection`	Which day places a medical-history mark: 'collection' (mh_day_col, the day it was recorded) or 'onset' (mh_onset_stdy_col); anything else falls back to 'collection' with a warning.
`settings.mh_onset_stdy_col`	`string,array`	no	`ASTDY,MHSTDY`	Medical-history onset study day, as a column name or a fallback chain resolved per row (the ADaM ASTDY, then the SDTM MHSTDY, so the plan's vocabulary places too — D15); the tooltip's onset text by default, and the mark position under mh_day_source 'onset'.
`settings.mh_strtpt_col`	`string`	no	`MHSTRTPT`	Medical-history onset relative-timing column (BEFORE, …), the tooltip's onset text when no onset day or date resolves.
`settings.mh_enrtpt_col`	`string`	no	`MHENRTPT`	Medical-history end relative-timing column; ONGOING adds 'still present' to the tooltip.
`settings.mh_onset_dtc_col`	`string`	no	`MHSTDTC`	Medical-history onset date column (--DTC), shown as recorded in the onset text.
`settings.ds_decod_col`	`string`	no	`DSDECOD`	Disposition decoded term column, the mark label; required in disposition data. A record with a blank decode is dropped with a named reason.
`settings.ds_term_col`	`string`	no	`DSTERM`	Disposition verbatim term column, the tooltip's secondary line when it differs from the decode.
`settings.ds_cat_col`	`string`	no	`DSCAT`	Disposition category column (DISPOSITION EVENT, PROTOCOL MILESTONE, …), the record's category and the key ds_reference_cats matches (D19).
`settings.ds_stdy_col`	`string,array`	no	`DSSTDY`	Disposition study day, as a column name or a fallback chain.
`settings.ds_dtc_col`	`string`	no	`DSSTDTC`	Disposition date column (--DTC), shown as recorded.
`settings.ds_reference_cats`	`array`	no	`DISPOSITION EVENT`	Disposition categories (upper-cased, trimmed) whose rows draw a full-height dashed rule across every lane; every disposition row still draws its own mark. An empty list draws a rule for every row, which is legal but noisy and warned once.
`settings.lanes`	`object`	no	—	Per-lane display configuration keyed by lane (exposure, doseChanges, adverseEvents, labs, conMeds, medicalHistory, disposition), each { enabled, label, group } merged key by key onto the default; null disables a lane, an unknown lane key is dropped with a warning (PJE-CFG-003). Lane-level severityCol, seriousCol and tests are lifted to ae_sev_col, ae_ser_col and lb_tests; domain, derivedFrom and smallMultiple are accepted and ignored.
`settings.lane_groups`	`array`	no	`[object Object],[object Object],[object Object]`	Collapsible lane groups in stack order, each { key, label, collapsed }; a group with no enabled lane is dropped at render time (PJE-LANE-003). The plan's laneGroups is an alias.
`settings.filters`	`array`	no	`[object Object],[object Object],[object Object]`	Sidebar filter specs, each with a domain (the only domain the filter applies to) and the shared filter contract keys: type 'flag' with a flag_value renders a checkbox (the special flag_value '__abnormal__' keeps only labs failing the abnormality rule), multiple true renders the shell multiselect, and the rest follow { value_col, label, start, all }. Specs without a value_col (or the plan's col alias) or without a recognized domain are dropped with a warning; a filter whose column is absent from its domain's data is dropped at render time with the library's standard warning (PJE-FILT-001 … PJE-FILT-004).
`settings.source_url_template`	`string,null`	no	—	Optional external link template for every source row, e.g. 'https://edc.example/{domain}/{USUBJID}/{AESEQ}': {domain} is the domain code and {COLUMN} the row's URI-encoded value; a row lacking a named column gets no link. null renders no link (PJE-SRC-002). The plan's sourceUrlTemplate is an alias.
`settings.source_url_label`	`string`	no	`Open source record`	Link text for the external source link.
`settings.on_select_subject`	`null`	no	—	Callback (subjectId, detail) when the subject changes; kept only when a function. The plan's onSelectSubject is an alias (PJE-EVT-001).
`settings.on_anchor_event`	`null`	no	—	Callback (event, context) when a mark is anchored or the anchor is cleared (both null on clear). The plan's onAnchorEvent is an alias.
`settings.on_context_change`	`null`	no	—	Callback (context) whenever the context bundle changes while anchored, and with null when cleared. The plan's onContextChange is an alias.
`settings.row_height`	`number`	no	`26`	Pixels per row inside a categorical lane; a positive integer. The plan's rowHeight is an alias.
`settings.row_height_min`	`number`	no	`18`	Floor for row_height when fit_to_height scales the stack down.
`settings.max_rows_per_lane`	`number`	no	`12`	Rows drawn per categorical lane before the remainder is counted in prose, in the lane's documented sort order (PJE-LANE-010). The plan's maxRowsPerLane is an alias.
`settings.lab_height`	`number`	no	`96`	Pixels per lab small multiple. The plan's labHeight is an alias.
`settings.lab_height_min`	`number`	no	`64`	Floor for lab_height when fit_to_height scales the stack down.
`settings.height`	`number`	no	`760`	Pixel height of the lane column; taller stacks scroll and say so (PJE-LANE-009, D21). 760 is the height at which the Definition-of-Done participant fits at the row and lab floors.
`settings.fit_to_height`	`boolean`	no	`true`	Scale row and lab heights (down to their floors) so the opening stack fits height before the column scrolls (D21).
`settings.width`	`string`	no	`100%`	Widget width, applied as the container element's style width; carried for the R widget binding.
`settings.page_size`	`number`	no	`10`	Rows per page in the source-row drawer's tables.

patient-journey-explorer API reference Prototype

Overview

Factory

patientJourneyExplorer([element], [settings])

Methods

init(data)

setData(data)

setSettings(settings)

render()

selectSubject(subjectId)

anchor(eventId)

setLaneEnabled(laneKey, enabled)

setTimeMode(mode)

setContextWindowDays(days)

setFilter(valueCol, selection)

getContext()

getTimeMode()

on(name, handler)

off(name, [handler])

resize()

destroy()

Settings

Data contract

safety.viz patient-journey-explorer data contract

`patient-journey-explorer` API reference Prototype

`patientJourneyExplorer([element], [settings])`

`init(data)`

`setData(data)`

`setSettings(settings)`

`render()`

`selectSubject(subjectId)`

`anchor(eventId)`

`setLaneEnabled(laneKey, enabled)`

`setTimeMode(mode)`

`setContextWindowDays(days)`

`setFilter(valueCol, selection)`

`getContext()`

`getTimeMode()`

`on(name, handler)`

`off(name, [handler])`

`resize()`

`destroy()`