qt-explorer API reference QT Safety Explorer is experimentalExperimental: its settings and its table may still change.QualifiedValidated for regulated use. Nothing in safety.viz is, yet.ExploratoryTested and documented. Confirm every result.ExperimentalThis chartTested and documented, but what it shows or how it behaves may still change.PrototypeAn early look, on the docs site only. Not in the demo app.What each rung means
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, 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. The shared parts it is built from are public surface of their own, listed in the kit reference.
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 and visits. @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
selectParticipant(id)
Select one participant from the outlier scatter (#99, PPRF-QT-001): set the minimal host selection state, emphasize the participant's point, and dispatch the house participantsSelected event on the shell root β which feeds the railed profile. Single-select only (PPRF-QT-004).
| Param | Type | Default | Description |
|---|---|---|---|
id | string | β | Participant identifier. |
Returns: void β
clearSelection()
Clear the point selection (#99, PPRF-QT-003): restore the uniform point emphasis and dispatch the empty selection so the dock empties.
Returns: void β
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). The central-tendency view also uses it to average replicate readings to one value per participant and visit, so its n counts participants (#166). |
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; the chart's own views fall back to first-seen order. It is also the order of the participant drill-down's Visit view, which needs it: without it the drill-down offers no Visit view (#384). |
studyday_col | string | null | 'DY' | Optional numeric study-day column: the participant drill-down's Study day view, where ECGs taken on one day stack at that day (#372). null leaves the drill-down Visit only. |
x_axis | Object | null | null | The participant drill-down's X-axis toggle, the setting every chart that shows change over time takes (#372): `{ options: [{ key, col, label_col, type: 'ordinal'|'linear', title }], default }`. null builds it from `visitn_col` / `visit_col` (Visit, which spaces the visits evenly in visit-number order, so Screening sorts before Baseline) and `studyday_col` (Study day), opening on Visit; `{ default: 'day' }` keeps those options and opens on Study day. The chart's own views are unchanged. |
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), and marks the record the drill-down's ΓBaseline divides by (#372). |
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). 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 whether or not a start is given β pass `all: false` to remove it, and the filter then always holds one value, the first unless `start` names another; a start value the data lacks is dropped with a console warning; `multiple: true` renders a checkbox multiselect whose state is null (everything) or an array of values (#136). |
profile | boolean | true | Dock the shared participant-profile module in the shell's profile slot, fed by the outlier-scatter point click via the participantsSelected event; the ECG parameters render as key measures in observed milliseconds with the first absolute threshold as the QTc cut (#99, PPRF-QT-001/002). |
profile_details | Array.<(string|Object)> | null | null | Demographic columns for the docked profile's header, as names or { value_col, label } specs; null shows none (#99, PPRF-QT-001). |
participantProfileURL | string | null | null | Optional link-out URL for the docked profile's header, templated by every literal `{id}` token (#99, PPRF-QT-001). |
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. Also the order of the participant drill-down's Visit view. |
settings.studyday_col | string,null | no | DY | Optional numeric study-day column: the participant drill-down's Study day view (QT-XAX-001). null leaves the drill-down Visit only. |
settings.x_axis | object,null | no | β | The participant drill-down's X-axis toggle, the setting every chart that shows change over time takes: { options: [{ key, col, label_col, type, title }], default }. Visit view spaces the visits evenly in visit-number order, so Screening sorts before Baseline; Study day view plots each ECG at its day, so ECGs taken on one day stack. When null it is built from visitn_col and visit_col (Visit) and studyday_col (Study day), opening on Visit; { default: 'day' } keeps those options and opens on Study day. The chart's own views are unchanged (QT-XAX-001..003). |
settings.x_axis.options | array | no | β | |
settings.x_axis.default | string | no | visit | The key of the view the drill-down opens on. |
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), and it marks the ECG the drill-down's ΓBaseline divides by (QT-XAX-003). |
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). Each entry is a column name or a { value_col, label, start, all, multiple } spec: `start` is the value the filter opens on, `all` (default true) is whether an "All" option is offered, and `multiple` (default false) makes it a checkbox multiselect. |