nep-explorer API reference Experimental
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. nepExplorer(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, 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
nepExplorer([element], [settings])
Create a KDIGO nephrotoxicity 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 scatter.
| Param | Type | Default | Description |
|---|---|---|---|
element (optional) | string | HTMLElement | 'body' | Container node, or a CSS selector for it. |
settings (optional) | NepExplorerSettings | {} | Setting overrides, merged onto DEFAULT_SETTINGS and normalized. |
Returns: SafetyNepExplorer โ The live nep-explorer 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 | Array.<Object> | โ | Long-format lab records matching the nep-explorer data contract. |
Returns: SafetyNepExplorer โ 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), reduced to one staged point per participant, and the controls are rebuilt from the new data.
| Param | Type | Default | Description |
|---|---|---|---|
data | Array.<Object> | โ | Long-format lab records matching the nep-explorer data contract. |
Returns: SafetyNepExplorer โ The instance, for chaining.
setSettings(settings)
Merge setting overrides onto the current settings, re-normalize, rebuild the controls, and re-render.
| Param | Type | Default | Description |
|---|---|---|---|
settings | NepExplorerSettings | โ | Setting overrides to merge. |
Returns: SafetyNepExplorer โ The instance, for chaining.
render()
Redraw everything from the current data, settings and control state.
Returns: void โ
clearSelection()
Clear the point selection: restore the marks, reset the annotation, and dispatch the empty selection so external listeners follow.
Returns: void โ
resize()
Resize the live chart to its container. For host layouts that change the container size without a window resize โ e.g. the R htmlwidget bindings.
Returns: void โ
destroy()
Tear the explorer down: destroy the Chart.js instance 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; one point per participant and the selection key (NEP-CFG-001). |
measure_col | string | 'TEST' | Column holding the measure name, matched against measure_values.CREAT to find the creatinine records (NEP-CFG-008). |
value_col | string | 'STRESN' | Column holding the numeric result; non-numeric rows drop with a counted note (NEP-DATA-005). |
unit_col | string | null | 'STRESU' | Column holding the result unit, resolved PER RECORD to mg/dL before any comparison (NEP-UNIT-002). |
baseline_col | string | null | null | Optional baseline-flag column. When supplied, the flagged record is the baseline; otherwise the earliest record is used (D7, NEP-DATA-001). |
baseline_value | string | 'Y' | The value of baseline_col that marks the baseline record (NEP-CFG-002). |
visit_col | string | 'VISIT' | Categorical visit column; the tooltip's "maximum at visit" and the baseline fallback's second sort key. |
visitn_col | string | null | 'VISITNUM' | Numeric visit column ordering the records; ignored when absent. |
studyday_col | string | null | 'DY' | Optional numeric study-day column: the baseline fallback's first sort key and the tooltip's "maximum on study day". Degrades silently when the data has no such column (NEP-SCAT-003). |
measure_values | Object | {CREAT: 'Creatinine'} | Map of the short measure key to this data's full measure name; grows to the profile panel in Phase 2. |
arm_col | string | null | 'ARM' | Treatment-arm column, carried on each point for the tooltip and the filters. |
stages | Object | KDIGO_STAGES | The staging cut-points (D4): the three fold-change cut-points, the single absolute-change Stage-1 trigger, and the Stage-3 rule on the value reached. |
units | Object | โ | The mg/dL contract (design ยง4): the target unit and the per-unit multiplier table. Factor keys are normalized (lower-cased, ยต/ฮผ/u folded) on merge, so lookups never guess. |
filters | Array.<(string|Object)> | [] | Filter controls: column names or { value_col, label } specs (NEP-CFG-006). |
details | Array.<(string|Object)> | null | null | Participant-detail columns shown with the selected participant; defaults to the participant ID plus the filter columns. |
zone_labels | string | 'shown' | Whether the scatter draws the stage-zone labels: `shown` or `hidden` (NEP-ZONE-004). |
width | string | '100%' | Widget width, carried for the R widget bindings; the current shell always spans its container. |
height | number | 460 | Chart-area height in pixels, carried for the R widget bindings. |
Data contract
safety.viz nep-explorer data contract
Long-format laboratory data: one record per participant per measure per visit (NEP-DATA-001). Column names are supplied by the settings mapping. The nep-explorer reads the serum-creatinine records only, resolves each participant's baseline (an explicit baseline flag when configured, otherwise the earliest record), converts every record to mg/dL through the per-record unit table, and reduces each participant to one point: their maximum post-baseline fold change against their maximum post-baseline absolute change, staged on the KDIGO acute-kidney-injury criteria. Phase 1 requires only id, measure, value, unit and a way to find baseline โ a deliberately small contract, so the scatter ports to a study carrying nothing but a chemistry panel. Records that cannot be plotted are counted and exported rather than dropped silently (NEP-DATA-005).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | array | yes | โ | d3.csv()-style records; every row carries the participant, measure, result, unit and visit columns named in settings, one row per participant per measure per visit. |
settings | object | yes | โ | Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied. |
settings.id_col | string | yes | USUBJID | Participant identifier column; required in data. One point per participant, and the key the participantsSelected event carries (NEP-CFG-001, NEP-SCAT-004). |
settings.measure_col | string | yes | TEST | Column holding the measure name; required in data. Matched against measure_values.CREAT to select the creatinine records (NEP-CFG-008). |
settings.value_col | string | yes | STRESN | Column holding the numeric result; required in data. Missing or non-numeric results are dropped with a counted, exportable note (NEP-DATA-005). |
settings.unit_col | string,null | no | STRESU | Column holding the result unit, resolved PER RECORD against the units factor table. When any record's unit is absent or unrecognized the module refuses to guess: the fold axis stays (it is a ratio), and the absolute cut-line, the >= 4.0 mg/dL rule and the delta staging are suppressed with a note (NEP-UNIT-002, NEP-UNIT-003). |
settings.baseline_col | string,null | no | โ | Optional baseline-flag column (e.g. ABLFL). When supplied, the participant's first record whose value equals baseline_value is the baseline; otherwise, and for a participant with no flagged record, the earliest record is used โ by study day, then visit number, then input order (NEP-DATA-001, NEP-DATA-002). |
settings.baseline_value | string | no | Y | The value of baseline_col that marks the baseline record (NEP-CFG-002). |
settings.visit_col | string | no | VISIT | Categorical visit column; the tooltip's "maximum at visit" line and the baseline fallback's ordering (NEP-SCAT-003). |
settings.visitn_col | string,null | no | VISITNUM | Optional numeric visit column ordering the records; falls back to input order when absent. |
settings.studyday_col | string,null | no | DY | Optional numeric study-day column: the baseline fallback's first sort key and the tooltip's "maximum on study day" line. Absent from the vendored demo extract, so the line degrades silently rather than rendering blank (NEP-SCAT-003). |
settings.measure_values | object | no | [object Object] | Map of the short measure key to this data's full measure name. Phase 1 reads CREAT only; the map grows to the profile panel in Phase 2 (NEP-CFG-008). |
settings.arm_col | string,null | no | ARM | Treatment-arm column carried on each point for the tooltip; ignored when absent from the data. |
settings.stages | object | no | โ | The staging cut-points, defaulting to the KDIGO acute-kidney-injury criteria (NEP-CFG-003, NEP-STAGE-001..004). Supplied members merge onto the defaults. |
settings.stages.fold | array | no | 1.5,2,3 | The ascending fold-change (value / baseline) cut-points for Stages 1, 2 and 3. Sorted ascending on merge: the R source paints its chart from a descending ladder and stages its table from an ascending one, and the two disagree. |
settings.stages.delta | number | no | 0.3 | The single absolute-change cut-point KDIGO defines (mg/dL). It produces Stage 1 only โ there is no KDIGO Stage 2 or 3 on absolute change (NEP-STAGE-002). |
settings.stages.absolute | number | no | 4 | The Stage-3 rule on the VALUE reached (mg/dL). A property of the participant, not a region of the plane, so it is drawn as a mark property rather than a zone (NEP-STAGE-003). |
settings.units | object | no | โ | The mg/dL contract (NEP-UNIT-002). The fold axis is a ratio and unit-free; the absolute axis and both absolute cut-points are not. |
settings.units.target | string | no | mg/dL | The unit the absolute axis and the cut-points are expressed in. |
settings.units.factors | object | no | [object Object] | Multiplier from each source unit to the target. Keys are normalized on merge โ trimmed, lower-cased, with ยต/ฮผ/u folded โ so one entry covers every spelling and casing. Sponsor-specific factors vary, which nepExplorer warns about itself, so this is a setting rather than a constant (NEP-UNIT-001). |
settings.filters | array | no | โ | Optional filter columns rendered as controls (NEP-CFG-006). |
settings.details | null | no | โ | Participant-detail columns shown with the selected participant; null defaults to the participant ID plus the filter columns. |
settings.zone_labels | string | no | shown | Whether the scatter draws the stage-zone labels (NEP-ZONE-004). |