shift-plot API reference

Overview

Every safety.viz renderer is one factory call. shiftPlot(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, selectInPixelRect, brushValues, 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

shiftPlot([element], [settings])

Create a safety shift 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.

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

Returns: SafetyShiftPlot — The live shift-plot instance.

Methods

init(data)

Load data and render: an alias for setData that keeps the pilot's two-step create-then-init call shape working (SSP-DATA-003).

Param	Type	Default	Description
data	Array.<Object>	—	Long-format result records matching the shift-plot data contract.

Returns: SafetyShiftPlot — 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.

Param	Type	Default	Description
data	Array.<Object>	—	Long-format result records matching the shift-plot data contract.

Returns: SafetyShiftPlot — The instance, for chaining.

setSettings(settings)

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

Param	Type	Default	Description
settings	ShiftPlotSettings	—	Setting overrides to merge.

Returns: SafetyShiftPlot — The instance, for chaining.

render()

Redraw everything from the current data, settings, and control state: destroys the live chart, clears the listing and any brush selection, then draws the scatter, the identity line, and the participant-count notes. Called automatically by the controls and the data/settings setters; call it directly only after mutating state by hand.

Returns: void —

selectInPixelRect(rect)

Select every point whose pixel position falls inside a rectangle, opening the listing (or clearing when the rectangle catches nothing).

Param	Type	Default	Description
rect	Object	—	Pixel rectangle.

Returns: void —

brushValues(x0, x1, y0, y1)

Select points inside a data-space rectangle. The programmatic entry point the R widget bindings and tests use in place of a mouse drag.

Param	Type	Default	Description
x0	number	—	One baseline-axis bound of the rectangle.
x1	number	—	The other baseline-axis bound.
y0	number	—	One comparison-axis bound of the rectangle.
y1	number	—	The other comparison-axis bound.

Returns: void —

clearSelection()

Clear the brush selection: restore uniform point colors, hide the gray box and the listing, and dispatch an empty participantsSelected event (SSP-REG-011).

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 shift 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

Data contract

safety.viz shift-plot data contract

Long-format results data: one record per participant per visit per measure (SSP-DATA-001). Column names are supplied by the settings mapping; the shift plot pairs each participant's baseline-visit value against their comparison-visit value for the selected measure, removes missing/non-numeric results with a reported count (SSP-REG-020), and degrades gracefully when optional columns are absent (SSP-DATA-003).