ae-explorer API reference

Overview

Every safety.viz renderer is one factory call. aeExplorer(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, showDetails, backToSummary, buildValidationCsv, 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

aeExplorer([element], [settings])

Create an adverse-event explorer inside a container element. The control shell renders immediately; pass one-record-per-adverse-event data (plus placeholder rows for participants with no adverse events) to setData (or init) on the returned instance to validate the data and draw the summary table (AE-API-001).

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

Returns: AEExplorer — The live explorer instance.

Methods

init(data)

Load data and render: an alias for setData that keeps the original renderer's create-then-init call shape working (AE-DATA-003, AE-API-001).

Param	Type	Default	Description
data	Array.<Object>	—	Adverse-event records matching the ae-explorer data contract.

Returns: AEExplorer — 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); placeholder rows for participants with no adverse events are flagged so they count toward the population denominators (AE-DATA-001); and the filter controls are rebuilt from the new data's values.

Param	Type	Default	Description
data	Array.<Object>	—	Adverse-event records matching the ae-explorer data contract.

Returns: AEExplorer — The instance, for chaining.

setSettings(settings)

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

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

Returns: AEExplorer — The instance, for chaining.

render()

Redraw the summary table from the current data, settings, and control state: closes any open details view, recomputes the roll-up, and rebuilds the table with the prevalence and search visibility applied. Called automatically by the controls and the data/settings setters; call it directly only after mutating state by hand.

Returns: void —

showDetails(target)

Open the details view for a category (AE-USER-016): the record-level listing of the events under the clicked System Organ Class or Preferred Term as currently filtered, with the active filters reported and a Return to the Summary View button.

Param	Type	Default	Description
target	Object	—	The clicked category.

Returns: void —

backToSummary()

Return from the details view to the summary table (AE-USER-017).

Returns: void —

buildValidationCsv()

The validation download's payload: the summarized data as currently filtered and summarized, and its major-minor-basis file name (AE-USER-020, AE-REG-027).

Returns: Object — The file name and CSV text.

resize()

Table layout reflows with the page, so resizing is a no-op kept for the shared lifecycle shape (the R htmlwidget bindings call it).

Returns: void —

destroy()

Tear the explorer down: 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 ae-explorer data contract

Adverse-event data: one record per adverse event, plus one placeholder row per participant with no adverse events so the population denominator is right (AE-DATA-001). Placeholder rows are identified by the placeholder_flag setting — blank or 'NA' in the System Organ Class column by default — and count toward participant denominators while never appearing as events. Column names default to the ADaM ADAE standard and are remappable through the settings (AE-CFG-003); a chart initializes with no settings at all when the data carries the default columns (AE-DATA-003).