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, recomputes the per-participant points and quadrants, then draws the scatter, legend, and quadrant summary table (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, draw the lab-over-time companion chart and the measure summary table, open the linked listing of the participant's raw records, annotate the chart, and dispatch the participantsSelected event — all in the active display units.
| Param | Type | Default | Description |
|---|---|---|---|
id | string | number | — | The participant identifier. |
Returns: void —
clearSelection()
Clear any participant selection: erase the visit-path overlay, close the detail panels and listing, and restore the base annotation/footnote (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. |
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). |
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). |
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). |
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.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.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.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). |