outlier-explorer API reference

Overview

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

Factory

outlierExplorer([element], [settings])

Create a safety outlier explorer 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 chart.

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

Returns: SafetyOutlierExplorer — The live outlier-explorer 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 (SOE-API-001).

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

Returns: SafetyOutlierExplorer — 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 filter values.

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

Returns: SafetyOutlierExplorer — 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	OutlierExplorerSettings	—	Setting overrides to merge.

Returns: SafetyOutlierExplorer — The instance, for chaining.

render()

Redraw everything from the current data, settings, and control state: destroys the live chart, clears the listing and any selection, then draws the population lines, the normal-range band, the legend, and the counts. Called automatically by the controls and the data/settings setters.

Returns: void —

selectParticipant(id)

Highlight one participant: draw the bold selection overlay, open the linked listing, and dispatch the participantsSelected event (SOE-FUNC-010, SOE-REG-013/014/016, SOE-API-003).

Param	Type	Default	Description
id	string	—	Participant identifier.

Returns: void —

clearSelection()

Clear any participant selection and the linked listing (SOE-FUNC-010 click-outside behavior).

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

Data contract

safety.viz outlier-explorer data contract

Long-format results data: one record per participant per time point per measure (SOE-DATA-001). Column names are supplied by the settings mapping; the outlier-explorer removes missing/non-numeric results with a reported count (SOE-REG-037) and derives a per-participant measurement sequence when the data carries no visit/study-day column.