ae-timelines API reference

Overview

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

aeTimelines([element], [settings])

Create an adverse-event timelines chart inside a container element. The control shell renders immediately; pass one-record-per-adverse-event data to setData (or init) on the returned instance to validate the data and draw the timelines.

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

Returns: AETimelines — The live timelines instance.

Methods

init(data)

Load data and render: an alias for setData that keeps the original renderer's create-then-init call shape working (AET-DATA-004).

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

Returns: AETimelines — 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); records with blank terms or non-integer start days are removed with console warnings while AE-free placeholder rows still count toward the population; 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-timelines data contract.

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

Returns: AETimelines — The instance, for chaining.

render()

Redraw everything from the current data, settings, and control state: closes any open participant detail view, destroys the live charts, and draws the timeline chart and the participant-count note. Called automatically by the controls and the data/settings setters; call it directly only after mutating state by hand.

Returns: void —

showParticipantDetail(participant)

Open the detail view for one participant: their per-event timeline on the main chart's study-day domain (one row per sequence number), the raw-record listing with search/sort/CSV export, and the Back button — hiding the timelines and controls, and dispatching the participantsSelected event with the selected ID.

Param	Type	Default	Description
participant	string	—	Participant ID to detail.

Returns: void —

backToTimelines()

Return from the participant detail view to the timelines (AET-FUNC-010): clears the selection, dispatches participantsSelected with an empty array, and re-renders the timeline chart.

Returns: void —

resize()

Resize every live chart (the timeline and any open detail 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 timelines down: destroy every 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 ae-timelines data contract

Adverse-event data: one record per adverse event, with placeholder rows (blank term and start day) keeping AE-free participants in the population denominator (AET-DATA-001). Column names default to the ADaM ADAE standard and are supplied by the settings mapping; records with blank reported terms or non-integer start days are removed with reported counts, and a coloring variable — severity by default — is required but remappable (AET-DATA-003).