hep-waterfall 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. hepWaterfall(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 (moveBoxHover, panelArm, redrawFlank, init, setData, setSettings, render, selectParticipant, 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
hepWaterfall([element], [settings])
Create a modified ALT waterfall inside a container element. The control shell renders immediately; pass long-format liver-chemistry records to setData (or init) on the returned instance to validate the data and draw the chart.
| Param | Type | Default | Description |
|---|---|---|---|
element (optional) | string | HTMLElement | 'body' | Container node, or a CSS selector for it. |
settings (optional) | HepWaterfallSettings | {} | Setting overrides, merged onto DEFAULT_SETTINGS and normalized. |
Returns: SafetyHepWaterfall — The live hep-waterfall instance.
Methods
moveBoxHover()
The pointer moved over a flank panel: hover whatever box it is on. @private
panelArm()
The arm label a flank panel summarizes. @private
redrawFlank()
Repaint one flank panel, e.g. after its hover changed. @private
init(data)
Load data and render — an alias for setData keeping the two-step create-then-init call shape (HWF-API-002).
| Param | Type | Default | Description |
|---|---|---|---|
data | Array.<Object> | — | Long-format liver-chemistry records matching the hep-waterfall data contract. |
Returns: SafetyHepWaterfall — The instance, for chaining.
setData(data)
Replace the bound data and re-render: validate against the settings mapping (throwing, and rendering the message into the target, when a required column is missing), clean, rebuild the controls, and draw.
| Param | Type | Default | Description |
|---|---|---|---|
data | Array.<Object> | — | Long-format liver-chemistry records matching the hep-waterfall data contract. |
Returns: SafetyHepWaterfall — The instance, for chaining.
setSettings(settings)
Merge setting overrides, re-normalize them (same rules as the factory), re-seed every control from the merged settings, rebuild the controls, and re-render.
| Param | Type | Default | Description |
|---|---|---|---|
settings | HepWaterfallSettings | — | Setting overrides to merge. |
Returns: SafetyHepWaterfall — The instance, for chaining.
render()
Redraw everything from the current data, settings, and control state: the cohort and its notes, the floating bars and baseline trace, the mirrored axes, the arm divider and reference range, and the two flanking summary panels. Called automatically by the controls and the data/settings setters.
Returns: void —
selectParticipant(id)
Select (or, when already selected, deselect) a participant: highlight their bar, open the linked listing of their records, and dispatch the participantsSelected event (HWF-SELECT-002, HWF-SELECT-003).
| Param | Type | Default | Description |
|---|---|---|---|
id | string | number | — | The participant identifier. |
Returns: void —
resize()
Resize every live chart — the waterfall and both flanking panels — 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 waterfall down: destroy every chart and empty the target element. The instance cannot be reused afterwards — create a new one via the factory.
Returns: void —
Settings
| Setting | Type | Default | Description |
|---|---|---|---|
id_col | string | 'USUBJID' | Participant identifier column; one bar per participant (HWF-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. |
value_col | string | 'STRESN' | Column holding the numeric result; required in the data. The bars and the baseline trace are drawn in these units (HWF-AXIS-001). |
unit_col | string | null | 'STRESU' | Unit column; the modal value for the plotted measure titles both axes, falling back to U/L (HWF-DATA-006). |
normal_col_high | string | 'STNRHI' | Upper-limit-of-normal column; required in the data — it drives the reference-range band and the ×ULN bilirubin rules (HWF-AXIS-004). |
normal_col_low | string | null | 'STNRLO' | Optional lower-limit-of-normal column, carried into the participant listing. |
studyday_col | string | null | 'DY' | Study-day column; separates the baseline record from the on-treatment records and dates the maximum (HWF-DATA-002). |
visit_col | string | null | 'VISIT' | Optional categorical visit column, shown in the participant listing. |
visitn_col | string | null | 'VISITNUM' | Optional numeric visit column ordering the visits. |
measure_values | Object | — | Map of the short measure key (ALT/AST/TB/ALP) to the full measure string in the data; controls present the short keys but resolve rows via these strings. |
measure | string | 'ALT' | The plotted analyte. The paper plots ALT; AST, ALP and TB are available (HWF-CFG-002). |
arm_col | string | 'ARM' | Treatment-arm column; REQUIRED in the data — the arm decides which half of the waterfall a participant's bar sits in, so a waterfall without it has no seam and no comparison (HWF-DATA-005). |
placebo_arm | string | null | null | Arm plotted blue on the left half; when null it is auto-detected by matching the arm values against /placebo|control/i (HWF-CFG-003). |
active_arms | Array.<string> | null | null | Arms plotted bronze on the right half; when null every non-placebo arm pools right (HWF-CFG-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. |
baseline_value | string | 'Y' | The value of baseline_col that marks the baseline record. |
jaundice_uln | number | 2 | New-onset-jaundice threshold on the total-bilirubin ×ULN scale: flagged when the baseline is at or below it and the on-treatment maximum exceeds it (HWF-DATA-004). |
baseline_tb_max | number | 1 | Paper Table-1 cohort rule: participants whose baseline total bilirubin exceeds this many ×ULN are excluded (HWF-DATA-003). |
apply_tb_cohort | boolean | true | Whether to apply that Table-1 exclusion; turning it off admits baseline-jaundiced participants and says so in the notes (HWF-DATA-003). |
uln_display | string | 'band' | How the reference range is drawn: 'band', 'per_subject', or 'none' (HWF-CFG-004, HWF-AXIS-004). |
summary | string | 'baseline_peak' | What the flanking panels show: 'baseline_peak' (a baseline box and a peak box per arm) or 'peak' (HWF-CFG-005, HWF-BOX-003). |
filters | Array.<(string|Object)> | [] | Filter controls: column names or { value_col, label } specs (HWF-CTRL-003). |
details | Array.<(string|Object)> | null | null | Columns for the linked participant listing; when null, defaults derive from the measure/day/value mappings (HWF-SELECT-002). |
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 | 480 | Chart-area height in pixels, carried over for the R widget bindings. |
Data contract
safety.viz hep-waterfall data contract
Long-format liver-chemistry data: one record per participant per measure per visit (HWF-DATA-001), the same record contract the hep-explorer reads, plus a required treatment-arm column. The hep-waterfall draws the modified waterfall of Amirzadegan et al., Drug Safety 2025;48(5):443-453, Figure 5, for trials enrolling participants with elevated baseline ALT but NORMAL baseline bilirubin: one floating bar per participant spanning their baseline value to their maximum on-treatment value in the data's absolute units, participants ranked by baseline with placebo ascending left-to-right and active descending right-to-centre so the highest baselines of the two arms meet at the seam, a black line tracing the baselines, blue/bronze arm colours with a green override for new-onset jaundice, and a box-and-whisker summary flanking each arm. Participants whose baseline total bilirubin exceeds baseline_tb_max are excluded by the paper's Table 1 rule, and participants whose arm is designated neither placebo nor active are excluded; both counts are reported separately (HWF-DATA-003, HWF-DATA-005).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | array | yes | — | d3.csv()-style records; every row carries the participant, measure, result, reference-range and treatment-arm columns named in settings, one row per participant per measure per visit. Both ALT (or the configured measure) and total bilirubin must be present for a participant to be plotted: the measure supplies the bar, the bilirubin the cohort rule and the jaundice flag. |
settings | object | yes | — | Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied. The lab-mapping block is identical to the hep-explorer contract so one settings list can drive both. |
settings.id_col | string | yes | USUBJID | Participant identifier column; required in data — one bar per participant, and the tie-break that makes the ordering reproducible (HWF-DATA-001, HWF-ORDER-004). |
settings.measure_col | string | yes | TEST | Column holding the measure name; required in data. Rows are matched to the ALT/AST/TB/ALP keys via measure_values. |
settings.value_col | string | yes | STRESN | Column holding the numeric result; required in data. The bars, the baseline trace and both axes are in these units — absolute, never a multiple of the reference range or of baseline (HWF-AXIS-001). |
settings.unit_col | string,null | no | STRESU | Unit column. The modal unit of the plotted measure titles both axes, falling back to U/L; a cohort carrying more than one unit for that measure is a warning, not a chart (HWF-DATA-006, HWF-DATA-007). |
settings.normal_col_high | string | yes | STNRHI | Upper-limit-of-normal column; required in data. It draws the reference-range band on the absolute axis and standardizes total bilirubin for the cohort rule and the jaundice flag (HWF-AXIS-004, HWF-DATA-003, HWF-DATA-004). |
settings.normal_col_low | string,null | no | STNRLO | Optional lower-limit-of-normal column, carried into the linked participant listing. |
settings.studyday_col | string,null | no | DY | Study-day column; separates the baseline record from the on-treatment records and dates the maximum shown in the tooltip (HWF-DATA-002). |
settings.visit_col | string,null | no | VISIT | Optional categorical visit column, shown in the linked participant listing. |
settings.visitn_col | string,null | no | VISITNUM | Optional numeric visit column ordering the visits. |
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; the controls present the short keys but resolve rows via these strings. |
settings.measure | string | no | ALT | The plotted analyte. The paper plots ALT; AST, ALP and TB are available (HWF-CFG-002). |
settings.arm_col | string | yes | ARM | Treatment-arm column; required in data. The arm decides which half of the waterfall a participant's bar sits in and which colour it takes, so a waterfall without it has no seam and no comparison (HWF-DATA-005, HWF-COLOR-001). |
settings.placebo_arm | string,null | no | — | Arm plotted blue on the left half; when null it is auto-detected by matching the arm values against /placebo|control/i, an exact match beating a substring one (HWF-CFG-003). |
settings.active_arms | array,null | no | — | Arms plotted bronze on the right half; when null every non-placebo arm pools right. Arms named by neither setting are excluded with a counted note (HWF-CFG-003, HWF-DATA-005). |
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. |
settings.baseline_value | string | no | Y | The value of baseline_col that marks the baseline record. |
settings.jaundice_uln | number | no | 2 | New-onset-jaundice threshold on the total-bilirubin xULN scale: flagged when the baseline is at or below it and the maximum on-treatment value exceeds it. Defaults to the composite plot's bilirubin cutpoint so the flag and the Hy's-Law quadrants stay mutually consistent (HWF-DATA-004). |
settings.baseline_tb_max | number | no | 1 | The paper's Table-1 cohort rule: participants whose baseline total bilirubin exceeds this many xULN are excluded, because the waterfall serves the abnormal-ALT / NORMAL-bilirubin population. Separate from jaundice_uln, which is an event threshold (HWF-DATA-003). |
settings.apply_tb_cohort | boolean | no | true | Whether to apply the Table-1 baseline-bilirubin exclusion. Turning it off admits baseline-jaundiced participants for exploratory use and says so in the notes (HWF-DATA-003). |
settings.uln_display | string | no | band | How the reference range is drawn on the absolute axis. Because the upper limit of normal genuinely varies across a real cohort, a single line would be undefined: 'band' shades min-to-max and collapses to a line when the cohort shares one limit, 'per_subject' traces each participant's own limit, 'none' draws nothing (HWF-AXIS-004). |
settings.summary | string | no | baseline_peak | What the flanking box-and-whisker panels show: 'baseline_peak' gives a baseline box and a maximum-on-treatment box per arm, so the panel summarizes the same shift the bars show per participant; 'peak' gives the single-box reading (HWF-BOX-003). |
settings.filters | array | no | — | Optional filter columns rendered as controls; an active filter restricts the plotted cohort and the counts in the notes (HWF-CTRL-003). |
settings.details | array | no | — | Columns for the linked participant listing opened by clicking a bar; when null, defaults derive from the measure/day/value mappings (HWF-SELECT-002). |
settings.page_size | number | no | 10 | Rows per page in the linked participant listing. |