safety.viz v1.1.0

delta-delta 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. deltaDelta(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, 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

deltaDelta([element], [settings])

Create a safety delta-delta plot inside a container element. The control shell renders immediately; pass long-format result records to setData (or init) on the returned instance to validate the data and draw the scatter.

ParamTypeDefaultDescription
element (optional)string | HTMLElement'body'Container node, or a CSS selector for it.
settings (optional)DeltaDeltaSettings{}Setting overrides, merged onto DEFAULT_SETTINGS and normalized.

Returns: SafetyDeltaDelta — The live delta-delta instance.

Methods

init(data)

Load data and render: an alias for setData that keeps the two-step create-then-init call shape working.

ParamTypeDefaultDescription
dataArray.<Object>—Long-format result records matching the delta-delta data contract.

Returns: SafetyDeltaDelta — 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 results are removed with a console warning, and the controls are rebuilt from the new data's measures and visits.

ParamTypeDefaultDescription
dataArray.<Object>—Long-format result records matching the delta-delta data contract.

Returns: SafetyDeltaDelta — The instance, for chaining.

setSettings(settings)

Merge setting overrides onto the current settings, adopt any provided measure/visit/regression selections into the control state, re-normalize the settings, rebuild the controls, and re-render.

ParamTypeDefaultDescription
settingsDeltaDeltaSettings—Setting overrides to merge.

Returns: SafetyDeltaDelta — The instance, for chaining.

render()

Redraw everything from the current data, settings, and control state: destroys the live chart, clears the measure table and any point selection, recomputes the per-participant points, and draws the scatter plus the participant-count and regression notes. Called automatically by the controls and the data/settings setters.

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 delta-delta plot 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

SettingTypeDefaultDescription
measure_colstring'TEST'Column holding the measure name; required in the data. Each distinct measure becomes an option in the X and Y Measure controls (SDD-CFG-004).
value_colstring'STRESN'Column holding the numeric result; required in the data. Rows with missing or non-numeric values are removed with a console warning (SDD-CFG-005, SDD-REG-008).
id_colstring'USUBJID'Participant identifier column; drives the participant counts and the one-point-per-participant scatter (SDD-CFG-006).
visit_colstring'VISIT'Categorical visit column; drives the baseline/comparison visit multi-selects (SDD-CFG-007).
visitn_colstring'VISITNUM'Numeric visit column used to order the visit selectors and the linked-table sparklines; ignored when absent (SDD-CFG-008).
measure_xstring | nullnullMeasure plotted on the x-axis; falls back to the first measure in the data when absent (SDD-CFG-009, SDD-CFG-010).
measure_ystring | nullnullMeasure plotted on the y-axis; falls back to the second measure in the data when absent (SDD-CFG-011).
baseline_visitsArray.<string>[]Baseline visit(s); multiple selected visits are averaged. Falls back to the first visit in the data (SDD-CFG-012, SDD-FUNC-001).
comparison_visitsArray.<string>[]Comparison visit(s); multiple selected visits are averaged. Falls back to the last visit in the data (SDD-CFG-013, SDD-FUNC-001).
add_regression_linebooleantrueDraw a simple linear regression line with an equation and R² note on first render (SDD-REG-026).
filtersArray.<(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 (SDD-CFG-014, SDD-REG-007).
detailsArray.<(string|Object)> | nullnullParticipant-detail columns shown above the linked measure table; when null, defaults to the participant ID and the filter columns (SDD-CFG-015).
widthstring'100%'Widget width, carried over for the R widget bindings; the current shell always spans its container.
heightnumber460Chart-area height in pixels, carried over for the R widget bindings; the current shell fixes the chart area at 460px.

Data contract

safety.viz delta-delta data contract

Long-format results data: one record per measurement at a visit (SDD-DATA-001). Column names are supplied by the settings mapping; each participant needs at least a baseline and a comparison visit for the two selected measures so change-from-baseline can be computed. The renderer removes missing/non-numeric results with a reported count (SDD-REG-008) and plots one point per participant (change in measure X vs change in measure Y).

FieldTypeRequiredDefaultDescription
dataarrayyes—d3.csv()-style records; every row carries the measure, result, participant, and visit columns named in settings.
settingsobjectyes—Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied.
settings.measure_colstringyesTESTColumn holding the measure name; required in data (SDD-CFG-004).
settings.value_colstringyesSTRESNColumn holding the numeric result; required in data. Non-numeric results are removed with a logged count (SDD-CFG-005, SDD-REG-008).
settings.id_colstringyesUSUBJIDParticipant identifier column; one plotted point per participant (SDD-CFG-006).
settings.visit_colstringyesVISITCategorical visit column; drives the baseline/comparison visit selectors (SDD-CFG-007).
settings.visitn_colstringnoVISITNUMOptional numeric visit column; orders the visit selectors and the sparkline (SDD-CFG-008).
settings.measure_xstring,nullno—Measure plotted on the x-axis; defaults to the first measure in the data (SDD-CFG-009, SDD-CFG-010).
settings.measure_ystring,nullno—Measure plotted on the y-axis; defaults to the second measure in the data (SDD-CFG-011).
settings.baseline_visitsarraynoBaseline visit(s); multiple visits are averaged. Defaults to the first visit (SDD-CFG-012).
settings.comparison_visitsarraynoComparison visit(s); multiple visits are averaged. Defaults to the last visit (SDD-CFG-013).
settings.add_regression_linebooleannotrueDraw a simple linear regression line with an equation and R² note (SDD-REG-026).
settings.filtersarrayno—Optional filter columns rendered as controls (SDD-CFG-014).
settings.detailsarrayno—Optional participant-detail columns shown above the linked measure table; defaults derive from id_col and the filters (SDD-CFG-015).