`qt-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. qtExplorer(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 (renderShellDom, init, setData, setSettings, validateAndCleanData, buildControls, postBaselineVisits, destroyCharts, render, showQtcOnlyNote, drawLegend, renderCentral, drawIchCallout, setCentralFootnote, renderOutlier, renderCategorical, 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

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

Create a QT Safety Explorer bound to a target element.

Param	Type	Default	Description
`element` (optional)	`string \| HTMLElement`	`'body'`	Target selector or element.
`settings` (optional)	`QtExplorerSettings`	`{}`	Setting overrides.

Returns: SafetyQtExplorer — The instance.

Methods

`renderShellDom()`

Build the shell + module-owned slots (legend, note, table, ICH callout). @private

`init(data)`

Load data and render — an alias for setData keeping the two-step create-then-init call shape (QT-API-001).

Param	Type	Default	Description
`data`	`Array.<Object>`	—	Long-format ECG records matching the qt-explorer data contract.

Returns: SafetyQtExplorer — The instance, for chaining.

`setData(data)`

Replace the bound data and re-render: validate (throwing and rendering the message into the target when required columns are missing), clean, rebuild controls, and render the active view.

Param	Type	Default	Description
`data`	`Array.<Object>`	—	Long-format ECG records matching the qt-explorer data contract.

Returns: SafetyQtExplorer — The instance, for chaining.

`setSettings(settings)`

Merge setting overrides, re-normalize (same rules as the factory), rebuild controls, and re-render.

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

Returns: SafetyQtExplorer — The instance, for chaining.

`validateAndCleanData()`

Validate + clean; resolve measures, arms, placebo, visits, and prune stale state. @private

`buildControls()`

Build the sidebar controls for the active view. @private

`postBaselineVisits()`

Post-baseline visit labels for the current measure. @private

`destroyCharts()`

Destroy live charts before re-rendering into the shared canvas. @private

`render()`

Render the active view into the shared canvas: destroy prior charts, apply the filters, and dispatch to the central-tendency, outlier, or categorical renderer.

Returns: void —

`showQtcOnlyNote()`

Show a "select a QTc correction" note and hide chart/table (HR, QTc-only views). @private

`drawLegend()`

Draw the "Treatments" arm legend (color swatch per arm). @private

`renderCentral()`

Render the central-tendency view. @private

`drawIchCallout()`

ICH-E14 metric callout (mean + ΔΔ + QTc only). @private

`setCentralFootnote()`

Central-tendency footnote: method + mode caveats. @private

`renderOutlier()`

Render the outlier-scatter view. @private

`renderCategorical()`

Render the categorical-exceedance view. @private

`resize()`

Resize the live charts (e.g. after the sidebar collapses).

Returns: void —

`destroy()`

Destroy the charts and empty the target element.

Returns: void —

Settings

Setting	Type	Default	Description
`id_col`	`string`	`'USUBJID'`	Participant identifier column; one scatter point per participant and the exceedance denominators (QT-DATA-001).
`measure_col`	`string`	`'TEST'`	Column holding the ECG parameter name; required in the data. Matched to the correction options (QT-DATA-002).
`value_col`	`string`	`'STRESN'`	Column holding the numeric analysis value; required in the data. Missing / non-numeric rows are removed with a console warning (QT-DATA-003).
`baseline_col`	`string`	`'BASE'`	Baseline-value column; required in the data — the scatter x-axis and the absolute-threshold diagonals anchor to it (QT-OUT-001).
`change_col`	`string \| null`	`'CHG'`	Optional source change-from-baseline column; when blank for a row, change is derived as value − baseline (QT-DATA-004).
`unit_col`	`string \| null`	`'STRESU'`	Optional unit column, appended to the parameter label.
`arm_col`	`string`	`'ARM'`	Treatment-arm column; required in the data. Drives per-arm lines, point colors, ΔΔ correction, and the exceedance columns (QT-CT-001, QT-OUT-004, QT-CAT-001).
`placebo_arm`	`string \| null`	`null`	Arm treated as placebo for ΔΔ and the ICH-E14 metric; when null, /placebo/i is auto-detected (QT-CT-004).
`visit_col`	`string`	`'VISIT'`	Categorical visit column; the central-tendency x-axis and the scatter timepoint selector (QT-CT-001, QT-OUT-002).
`visitn_col`	`string \| null`	`'VISITNUM'`	Optional numeric visit column ordering the visits; falls back to first-seen order.
`baseline_flag_col`	`string \| null`	`'ABLFL'`	Optional 'Y'-flagged baseline-record column; excludes the baseline visit from post-baseline extremes and the change series (QT-DATA-005).
`measures`	`Array.<string>`	`['QTcF','QTcB','Heart Rate']`	Correction / parameter options offered by the Correction control (QT-CTRL-002).
`qtc_measures`	`Array.<string>`	`['QTcF','QTcB']`	Which measures are QTc corrections; absolute cut-lines/rows apply only to these (QT-OUT-003).
`start_measure`	`string \| null`	`'QTcF'`	Correction selected on first render; falls back to the first available measure (QT-CTRL-002).
`absolute_thresholds`	`Array.<number>`	`[450,480,500]`	Absolute QTc cut-lines (msec) — scatter diagonals + categorical absolute rows (QT-OUT-003, QT-CAT-002).
`change_thresholds`	`Array.<number>`	`[30,60]`	Change-from-baseline cut-lines (msec) — scatter horizontals + categorical change rows (QT-OUT-003, QT-CAT-003).
`reference_threshold`	`number`	`10`	Central-tendency reference line (msec): the ICH-E14 threshold of concern (QT-CT-003).
`ci_level`	`number`	`0.9`	Confidence level for the CI on the mean change and the mean difference; the ICH-E14 metric reads its upper bound (QT-CT-005).
`filters`	`Array.<(string\|Object)>`	`[]`	Filter controls: column names or { value_col, label } specs (QT-CTRL-003).
`width`	`string`	`'100%'`	Widget width, carried over for the R widget bindings.
`height`	`number`	`460`	Chart-area height in pixels, carried over for the R widget bindings.

Data contract

safety.viz qt-explorer data contract

Long-format ECG-interval data: one record per participant per ECG parameter (QTcF / QTcB / Heart Rate) per visit (QT-DATA-001). Column names are supplied by the settings mapping. The qt-explorer reads a heart-rate-corrected QTc value, its baseline, and its change-from-baseline (taken from the change column, or derived value − baseline) to drive three views: central-tendency change over time by arm (Δ / placebo-corrected ΔΔ) with a 90% CI and the ICH-E14 metric, an outlier scatter of change vs baseline with absolute (450/480/500 ms) and change (30/60 ms) cut-lines, and a categorical by-arm exceedance table. Missing / non-numeric results are removed with a reported count (QT-DATA-003).

Field	Type	Required	Default	Description
`data`	`array`	yes	—	d3.csv()-style records; every row carries the parameter, result, baseline, participant, arm, and visit columns named in settings, one row per participant per parameter per visit.
`settings`	`object`	yes	—	Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied (QT-DATA-003).
`settings.id_col`	`string`	no	`USUBJID`	Participant identifier column; one point per participant in the scatter and the exceedance denominators (QT-DATA-001).
`settings.measure_col`	`string`	yes	`TEST`	Column holding the ECG parameter name; required in data. Matched to the correction options (QTcF/QTcB/Heart Rate) (QT-DATA-002).
`settings.value_col`	`string`	yes	`STRESN`	Column holding the numeric analysis value; required in data. Non-numeric results are removed with a logged count (QT-DATA-003).
`settings.baseline_col`	`string`	yes	`BASE`	Column holding the participant's baseline value; required in data — the scatter's x-axis and the absolute-threshold diagonals are anchored to it (QT-OUT-001).
`settings.change_col`	`string,null`	no	`CHG`	Optional column holding the source change-from-baseline. When absent or blank for a row, change is derived as value − baseline (QT-DATA-004).
`settings.unit_col`	`string,null`	no	`STRESU`	Optional unit column, appended to the parameter label.
`settings.arm_col`	`string`	yes	`ARM`	Treatment-arm column; required in data. Drives the per-arm central-tendency lines, point colors, ΔΔ placebo correction, and the exceedance table columns (QT-CT-001, QT-OUT-004, QT-CAT-001).
`settings.placebo_arm`	`string,null`	no	—	The arm treated as placebo for the ΔΔ (placebo-corrected) central-tendency mode and the ICH-E14 metric. When null, the arm whose name matches /placebo/i is auto-detected (QT-CT-004).
`settings.visit_col`	`string`	no	`VISIT`	Categorical visit column; the central-tendency x-axis and the outlier-scatter timepoint selector (QT-CT-001, QT-OUT-002).
`settings.visitn_col`	`string,null`	no	`VISITNUM`	Optional numeric visit column ordering the visits; falls back to first-seen order when absent.
`settings.baseline_flag_col`	`string,null`	no	`ABLFL`	Optional 'Y'-flagged baseline-record column; when present the baseline visit is excluded from the post-baseline extremes and the central-tendency change series (QT-DATA-005).
`settings.measures`	`array`	no	`QTcF,QTcB,Heart Rate`	The correction / parameter options offered by the Correction control, in order (QT-CTRL-002).
`settings.qtc_measures`	`array`	no	`QTcF,QTcB`	Which measures are QTc corrections; the outlier scatter's absolute-threshold diagonals and the categorical absolute rows apply only to these (Heart Rate has no QTc cut-lines) (QT-OUT-003).
`settings.start_measure`	`string,null`	no	`QTcF`	Correction selected on first render; falls back to the first available measure (QT-CTRL-002).
`settings.absolute_thresholds`	`array`	no	`450,480,500`	Absolute QTc cut-lines (msec) for the outlier-scatter diagonals and the categorical absolute rows (QT-OUT-003, QT-CAT-002; workflow step 3a).
`settings.change_thresholds`	`array`	no	`30,60`	Change-from-baseline cut-lines (msec) for the outlier-scatter horizontals and the categorical change rows (QT-OUT-003, QT-CAT-003; workflow step 3b).
`settings.reference_threshold`	`number`	no	`10`	Central-tendency reference line (msec): the ICH-E14 threshold of regulatory concern for the mean/ΔΔ change (QT-CT-003; workflow step 1a).
`settings.ci_level`	`number`	no	`0.9`	Confidence level for the two-sided CI on the mean change and the mean difference; the ICH-E14 metric reads the upper bound of this interval (QT-CT-005).
`settings.filters`	`array`	no	—	Optional filter columns rendered as controls (QT-CTRL-003).

qt-explorer API reference Experimental

Overview

Factory

qtExplorer([element], [settings])

Methods

renderShellDom()

init(data)

setData(data)

setSettings(settings)

validateAndCleanData()

buildControls()

postBaselineVisits()

destroyCharts()

render()

showQtcOnlyNote()

drawLegend()

renderCentral()

drawIchCallout()

setCentralFootnote()

renderOutlier()

renderCategorical()

resize()

destroy()

Settings

Data contract

safety.viz qt-explorer data contract

`qt-explorer` API reference Experimental

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

`renderShellDom()`

`init(data)`

`setData(data)`

`setSettings(settings)`

`validateAndCleanData()`

`buildControls()`

`postBaselineVisits()`

`destroyCharts()`

`render()`

`showQtcOnlyNote()`

`drawLegend()`

`renderCentral()`

`drawIchCallout()`

`setCentralFootnote()`

`renderOutlier()`

`renderCategorical()`

`resize()`

`destroy()`