hep-explorer API reference
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. hepExplorer(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, selectParticipant, clearSelection, resize, destroy) is shared by every module and consumed unchanged by the gsm.safety R bindings. See Architecture for how the pieces fit together.
Factory
hepExplorer([element], [settings])
Create a safety hep explorer inside a container element. The control shell renders immediately; pass long-format lab records to setData (or init) on the returned instance to validate the data and draw the eDISH scatter.
| Param | Type | Default | Description |
|---|---|---|---|
element (optional) | string | HTMLElement | 'body' | Container node, or a CSS selector for it. |
settings (optional) | HepExplorerSettings | {} | Setting overrides, merged onto DEFAULT_SETTINGS and normalized. |
Returns: SafetyHepExplorer — The live hep-explorer instance.
Methods
init(data)
Load data and render: an alias for setData that keeps the two-step create-then-init call shape working (HEP-API-001).
| Param | Type | Default | Description |
|---|---|---|---|
data | Array.<Object> | — | Long-format lab records matching the hep-explorer data contract. |
Returns: SafetyHepExplorer — The instance, for chaining.
setData(data)
Replace the bound data and re-render. The data is validated against the settings mapping (throwing, and rendering the message into the target element, when required columns are missing), rows with missing or non-numeric values/ULN are removed with a console warning, baselines are derived for the mDISH view, and the controls are rebuilt from the new data.
| Param | Type | Default | Description |
|---|---|---|---|
data | Array.<Object> | — | Long-format lab records matching the hep-explorer data contract. |
Returns: SafetyHepExplorer — The instance, for chaining.
setSettings(settings)
Merge setting overrides onto the current settings, re-normalize them (same rules as the factory), re-seed the affected control state, rebuild the controls, and re-render.
| Param | Type | Default | Description |
|---|---|---|---|
settings | HepExplorerSettings | — | Setting overrides to merge. |
Returns: SafetyHepExplorer — The instance, for chaining.
render()
Redraw everything from the current data, settings, and control state: destroys the live charts, clears the listing, legend, quadrant summary, and any selection, then hands off to the active view, which recomputes its own data and draws (the scatter, its legend and quadrant summary table, or the composite panels — or an empty-data message). A live participant selection survives the redraw: when the participant is still shown, every coordinated panel — scatter highlight, visit path, lab-over-time chart, summary table, and listing — is re-rendered from the same selection in the active display units (HEP-SELECT-006); otherwise the selection is cleared and listeners are notified. Called automatically by the controls and the data/settings setters.
Returns: void —
selectParticipant(id)
Select a participant and drive every coordinated view (HEP-SELECT-001..006): highlight the point, trace the visit path on the scatter, open the linked listing of the participant's raw records, annotate the chart, and dispatch the participantsSelected event — which feeds the railed participant profile (#98, PPRF-7) — all in the active display units.
| Param | Type | Default | Description |
|---|---|---|---|
id | string | number | — | The participant identifier. |
Returns: void —
clearSelection()
Clear any participant selection — the clicked drill-down and the Participants-control multi-highlight: erase the visit-path overlay, close the detail panels and listing, restore the base annotation/footnote and idle header, and notify listeners (HEP-SELECT-007).
Returns: void —
resize()
Resize the live charts to their containers. For host layouts that change the container size without a window resize — e.g. the R htmlwidget bindings.
Returns: void —
destroy()
Tear the hep explorer down: destroy the Chart.js instances 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; drives the one-point-per-participant scatter, the participant counts, and the linked listing (HEP-DATA-001). |
measure_col | string | 'TEST' | Column holding the measure name; required in the data. Rows are matched to the ALT/AST/TB/ALP keys via measure_values (HEP-DATA-002). |
value_col | string | 'STRESN' | Column holding the numeric result; required in the data. Rows with missing or non-numeric values are removed with a console warning (HEP-DATA-003). |
unit_col | string | 'STRESU' | Optional unit column, appended to measure labels and shown in the linked listing. |
normal_col_high | string | 'STNRHI' | Upper-limit-of-normal (ULN) column; required in the data — the ×ULN standardization divides each value by it (HEP-DISPLAY-002). |
normal_col_low | string | null | 'STNRLO' | Optional lower-limit-of-normal column, carried into the linked listing. |
studyday_col | string | null | 'DY' | Optional study-day column; drives the day_diff timing test and the visit-path ordering. When absent, a per-participant per-measure input-order sequence is derived (HEP-SELECT-004, HEP-DATA-004). |
visit_col | string | null | 'VISIT' | Optional categorical visit column; labels the visit-path overlay and pairs the X/Y trajectory points (HEP-SELECT-003). |
visitn_col | string | null | 'VISITNUM' | Optional numeric visit column; orders visit-keyed series when present. |
arm_col | string | null | 'ARM' | Treatment-arm column, structural for the migration view — it decides which side of the centre column a participant's flow leaves from. Auto-detected across ARM, ACTARM, TRT01A, TREATMENT and TRTA when the named column is absent; deliberately not a globally required column, so arm-less data still renders the scatter and composite views (HEP-ARM-001). |
placebo_arm | string | null | null | Arm value plotted on the left (placebo) side of the migration Sankey; when null it is auto-detected by matching the arm values against /placebo|control/i (HEP-ARM-002). |
active_arms | Array.<string> | null | null | Arm values plotted on the right (active) side; when null every non-placebo arm pools right and the pooled arms are named in the notes (HEP-ARM-003). |
baseline_col | string | null | null | Optional baseline-flag column (e.g. ABLFL). When supplied, the flagged record is the baseline, outranking the day-0-else-earliest heuristic (HEP-CORE-003). |
baseline_value | string | 'Y' | The value of baseline_col that marks the baseline record (HEP-CORE-003). |
jaundice_uln | number | 2 | New-onset-jaundice threshold on the total-bilirubin ×ULN scale: flagged when baseline is at or below it and the on-treatment maximum exceeds it. Defaults to the composite plot's bilirubin cutpoint so the flag and the quadrants stay mutually consistent (HEP-CORE-006). |
hide_unchanged | boolean | false | Migration view: suppress the diagonal (no-migration) ribbons; the hidden participant count stays in the notes and the cross tables (HEP-MIG-013). |
unscheduled_visits | boolean | true | Include records taken at an unscheduled visit — matched by unscheduled_visit_values, else by unscheduled_visit_pattern, against visit_col — in the baseline and peak reduction. Defaults to TRUE, diverging deliberately from results-over-time's `false`: an unscheduled draw in a hepatic study is often the draw a suspected injury prompted, so excluding it by default would hide the very peak that caused the visit. Turning it off re-derives every baseline and peak from the scheduled records alone, and a participant left with no retained record leaves the chart (HEP-CTRL-018, HEP-DATA-013). |
unscheduled_visit_pattern | string | '/unscheduled|early termination/i' | Regular expression, in /source/flags string form, identifying an unscheduled visit; parity with results-over-time's setting of the same name (HEP-DATA-013). |
unscheduled_visit_values | Array.<string> | null | null | Explicit list of unscheduled visit names; takes precedence over unscheduled_visit_pattern when set (HEP-DATA-013). |
measure_values | Object | — | Map of the short measure key (ALT/AST/TB/ALP) to the full TEST string in the data; controls present the short keys but resolve rows via these strings (HEP-DATA-002). |
x_default | string | 'ALT' | Measure plotted on the x-axis on first render (HEP-CTRL-001). |
y_default | string | 'TB' | Measure plotted on the y-axis on first render (HEP-CTRL-002). |
x_options | Array.<string> | ['ALT','AST','TB','ALP'] | Measures offered by the X-axis Measure control (HEP-CTRL-001). |
y_options | Array.<string> | ['TB'] | Measures offered by the Y-axis Measure control; when only one option the control is dropped (HEP-CTRL-002). |
cuts | Object | — | Per-measure Hy's-Law cutpoints keyed by measure then display mode; a `defaults` entry back-fills any measure without its own cuts (HEP-QUAD-001). |
view | string | 'scatter' | Initial view mode: `scatter` (eDISH/mDISH scatter), `migration` (the bidirectional baseline → on-treatment Sankey with per-arm cross tables), or `composite` (baseline-referenced composite plot for abnormal-baseline subjects) (HEP-COMP-006, HEP-MIG-001). |
group_order_col | string | null | null | Numeric companion column (e.g. `TRTN` beside `TRT`) that orders the colour-by legend; null leaves the groups alphabetical (HEP-CTRL-015). |
imputation_methods | Object | — | Below-LLOQ handling per measure key: `data-driven` (limit = the smallest positive recorded value), `user-defined` (limit from imputation_values), or `drop` (remove non-positive records). Defaults to `data-driven` for ALT, AST, TB and ALP, matching the original renderer (HEP-IMPUTE-001). |
imputation_values | Object | null | null | Per-measure lower limits of quantitation, used by the `user-defined` method (HEP-IMPUTE-001). |
quadrant_labels | string | 'shown' | Whether the scatter draws the four quadrant corner labels: `shown` or `hidden` (HEP-QUAD-007). |
log_base | number | 10 | Gridline base for a logarithmic axis: 10 (decades) or 2 (doublings). Only in force while the Axis Type is `log`; the axis POSITIONS are unchanged by it, the gridlines and their labels are not (HEP-CTRL-017). |
marginals | string | 'box_rug' | Marginal distributions drawn beside the eDISH scatter: `box_rug` (marginal box plots and axis rugs), `box`, `rug`, or `none` (HEP-MARG-001, HEP-MARG-002, HEP-MARG-003). |
visit_window | number | 30 | Timing window (days): points whose peak-X and peak-Y days are within this many days render filled, else hollow (HEP-CTRL-008, HEP-DISPLAY-005). |
profile | boolean | true | Mount the shared participant-profile module (header, labs-over-time spaghetti, measure table) in the shell's rail slot beside the chart, driven by every selection path via the participantsSelected event; false restores the pre-#98 behaviour of no drill-down block (#98, PPRF-7; obot.roadmap#75 moved the mount from the dock to the rail). |
profile_details | Array.<(string|Object)> | null | null | Demographic columns for the railed profile's header, as names or { value_col, label } specs; null falls back to the caller's own `details` value. Use this when `details` is configured for the linked listing rather than demographics (#98, PPRF-2). |
participantProfileURL | string | null | null | Optional link-out URL for the railed profile's header, templated by every literal `{id}` token (#98, PPRF-2, closes #53). |
calculate_palt | boolean | false | Opt in to computing the P_ALT hepatocyte-loss estimate (Chung et al., PMID 30303523) from each participant's ALT trajectory when `p_alt_col` supplies none; shown in the railed profile's header with the arithmetic behind it (HEP-PALT-001). Off by default because the estimate assumes ALT in IU/L and a study-day axis dense enough for a trapezoidal AUC. |
p_alt_col | string | null | null | Optional column carrying a pre-computed P_ALT shown in the railed profile's header; passed through where present, never computed client-side (#98, PPRF-2). |
measureBounds | Array.<number> | [0.01, 0.99] | Population-extent quantiles for the railed profile's sparkline / inset guides (#98, PPRF-4; parity with the original renderer's measureBounds). |
r_ratio_filter | boolean | true | Whether to render the R-Ratio range filter control (HEP-CTRL-010). |
r_ratio | Array.<number> | [0,null] | Initial R-Ratio [min, max] range; a null max is resolved from the data on first render (HEP-CTRL-010). |
filters | Array.<(string|Object)> | [] | Filter controls: column names or { value_col, label } specs. Filters whose column is absent from the data are dropped with a console warning (HEP-CTRL-011). Filter specs take `{ value_col, label, start, all, multiple }`: `start` is the opening selection (an array for a `multiple` filter, and a start of `0` or `false` is a real value, not an absent one); `all` controls the "All" option and defaults to true, or to false when a start is given — pass `all: true` to keep All alongside a start, `all: false` to require a selection; `multiple: true` renders a checkbox multiselect whose state is null (everything) or an array of values (#136). |
groups | Array.<(string|Object)> | [] | Color-by options; a "None" option is always offered first (HEP-CTRL-009). |
group_by | string | 'hep_none' | Column the points are colored by on first render; 'hep_none' disables grouping. |
details | Array.<(string|Object)> | null | null | Columns for the linked participant listing; when null, defaults derive from the measure/day/value mappings (HEP-SELECT-006). |
page_size | number | 10 | Rows per page in the linked participant listing. |
width | string | '100%' | Widget width, carried over for the R widget bindings; the shell always spans its container. |
height | number | 460 | Chart-area height in pixels, carried over for the R widget bindings; the shell fixes the chart-area height. |
Data contract
safety.viz hep-explorer data contract
Long-format liver-lab data: one record per participant per measure per visit/day (HEP-DATA-001). Column names are supplied by the settings mapping; the hep-explorer standardizes each value to ×ULN and ×Baseline, reduces to one point per participant (peak X measure vs peak Y measure), and removes missing/non-numeric results with a reported count (HEP-DATA-003). The four liver measures (ALT/AST/TB/ALP) are matched from the measure column via measure_values.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | array | yes | — | d3.csv()-style records; every row carries the measure, result, participant, and ULN columns named in settings, one row per participant per measure per visit/day. |
settings | object | yes | — | Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied (HEP-DATA-003). |
settings.id_col | string | yes | USUBJID | Participant identifier column; one plotted point per participant (HEP-DATA-001). |
settings.measure_col | string | yes | TEST | Column holding the measure name; required in data. Matched to the ALT/AST/TB/ALP keys via measure_values (HEP-DATA-002). |
settings.value_col | string | yes | STRESN | Column holding the numeric result; required in data. Non-numeric results are removed with a logged count (HEP-DATA-003). |
settings.unit_col | string | no | STRESU | Optional unit column, appended to measure labels and shown in the linked listing. |
settings.normal_col_high | string | yes | STNRHI | Upper limit of normal (ULN); required in data — the ×ULN standardization divides each value by it (HEP-DISPLAY-002). |
settings.normal_col_low | string,null | no | STNRLO | Optional lower limit of normal, carried into the linked listing. |
settings.studyday_col | string,null | no | DY | Optional study-day column; drives the timing test and visit-path ordering. When absent, a per-participant per-measure input-order sequence is derived (HEP-DATA-004, HEP-SELECT-004). |
settings.visit_col | string,null | no | VISIT | Optional categorical visit column; labels the visit-path overlay and pairs the X/Y trajectory points (HEP-SELECT-003). |
settings.visitn_col | string,null | no | VISITNUM | Optional numeric visit column; orders visit-keyed series when present. |
settings.arm_col | string,null | no | ARM | Treatment-arm column, structural for the migration view — it decides which side of the centre column a participant's flow leaves from. Auto-detected across ARM, ACTARM, TRT01A, TREATMENT and TRTA when the named column is absent, and deliberately NOT in this contract's required list, so arm-less data still renders the scatter and composite views (HEP-ARM-001). |
settings.placebo_arm | string,null | no | — | Arm value plotted on the left (placebo) side of the migration Sankey; when null it is auto-detected by matching the arm values against /placebo|control/i (HEP-ARM-002). |
settings.active_arms | array,string,null | no | — | Arm values plotted on the right (active) side; when null every non-placebo arm pools right and the pooled arms are named in the notes (HEP-ARM-003). |
settings.baseline_col | string,null | no | — | Optional baseline-flag column (e.g. ABLFL). When supplied, the flagged record is the baseline, outranking the day-0-else-earliest heuristic (HEP-CORE-003). |
settings.baseline_value | string | no | Y | The value of baseline_col that marks the baseline record (HEP-CORE-003). |
settings.jaundice_uln | number | no | 2 | New-onset-jaundice threshold on the total-bilirubin ×ULN scale: flagged when baseline is at or below it and the on-treatment maximum exceeds it. Defaults to the composite plot's bilirubin cutpoint so the flag and the quadrants stay mutually consistent (HEP-CORE-006). |
settings.hide_unchanged | boolean | no | false | Migration view: suppress the diagonal (no-migration) ribbons; the hidden participant count stays in the notes and the cross tables (HEP-MIG-013). |
settings.measure_values | object | no | [object Object] | Map of the short measure key (ALT/AST/TB/ALP) to the full measure string in the data (HEP-DATA-002). |
settings.view | string | no | scatter | Initial view mode: `scatter` (eDISH/mDISH one-point-per-participant scatter), `migration` (the bidirectional baseline → peak on-treatment Sankey mirrored about the baseline categorization, with one cross table per treatment arm — Amirzadegan et al., Drug Safety 2025, Fig 3; needs arm_col mapped), or `composite` (baseline-referenced composite plot for subjects with abnormal baseline liver tests — pretreatment and on-treatment eDISH panels, a four-panel ×Baseline shift plot, and a migration table) (HEP-COMP-006, HEP-MIG-001). |
settings.x_default | string | no | ALT | Measure plotted on the x-axis on first render (HEP-CTRL-001). |
settings.y_default | string | no | TB | Measure plotted on the y-axis on first render (HEP-CTRL-002). |
settings.x_options | array | no | ALT,AST,TB,ALP | Measures offered by the X-axis Measure control (HEP-CTRL-001). |
settings.y_options | array | no | TB | Measures offered by the Y-axis Measure control; a single option drops the control (HEP-CTRL-002). |
settings.cuts | object | no | [object Object] | Per-measure Hy's-Law cutpoints keyed by measure then display mode; a `defaults` entry back-fills any measure without its own cuts (HEP-QUAD-001). |
settings.calculate_palt | boolean | no | false | Opt in to computing the P_ALT hepatocyte-loss estimate (ALT AUC x peak ALT^0.18 / 10^5; Chung et al., PMID 30303523) from each participant's ALT trajectory when no pre-computed value is mapped. Off by default: the estimate assumes ALT in IU/L and a study-day axis dense enough for a trapezoidal AUC (HEP-PALT-001, HEP-PALT-002). |
settings.visit_window | number | no | 30 | Timing window (days): points whose peak-X and peak-Y days are within this many days render filled, else hollow (HEP-CTRL-008, HEP-DISPLAY-005). |
settings.r_ratio_filter | boolean | no | true | Whether to render the R-Ratio range filter control (HEP-CTRL-010). |
settings.r_ratio | array | no | 0, | Initial R-Ratio [min, max]; a null max is resolved from the data on first render (HEP-CTRL-010). |
settings.filters | array | no | — | Optional filter columns rendered as controls (HEP-CTRL-011). |
settings.groups | array | no | — | Optional color-by columns for grouping the points (HEP-CTRL-009). |
settings.details | array | no | — | Optional listing columns; defaults derive from the measure/day/value mappings (HEP-SELECT-006). |