time-to-event API reference Experimental
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. timeToEvent(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, 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
timeToEvent([element], [settings])
Create a Kaplan–Meier time-to-event explorer inside a container element. The control shell renders immediately; pass `{ events, population }` records to setData (or init) on the returned instance to validate the data and draw the curves.
| Param | Type | Default | Description |
|---|---|---|---|
element (optional) | string | HTMLElement | 'body' | Container node, or a CSS selector for it. |
settings (optional) | TimeToEventSettings | {} | Setting overrides, merged onto DEFAULT_SETTINGS and normalized. |
Returns: SafetyTimeToEvent — The live time-to-event instance.
Methods
init(data)
Load data and render: an alias for setData that keeps the two-step create-then-init call shape working.
| Param | Type | Default | Description |
|---|---|---|---|
data | Object | — | Event-level and population records matching the time-to-event data contract. |
Returns: SafetyTimeToEvent — The instance, for chaining.
setData(data)
Replace the bound data and re-render. Both datasets are validated against the settings mapping (throwing, and rendering the message into the target element, when required columns are missing) and the filter controls are rebuilt from the data.
| Param | Type | Default | Description |
|---|---|---|---|
data | Object | — | Event-level and population records matching the time-to-event data contract. |
Returns: SafetyTimeToEvent — The instance, for chaining.
setSettings(settings)
Merge setting overrides onto the current settings, re-normalize, rebuild the controls, and re-render.
| Param | Type | Default | Description |
|---|---|---|---|
settings | TimeToEventSettings | — | Setting overrides to merge. |
Returns: SafetyTimeToEvent — The instance, for chaining.
render()
Redraw everything from the current data, settings and control state.
Returns: void —
clearSelection()
Clear the event-step selection and dispatch the empty selection so external listeners follow.
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 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
| Setting | Type | Default | Description |
|---|---|---|---|
id_col | string | 'USUBJID' | Participant identifier column, in both datasets: one row per participant in the population data, any number of event rows, and the key the participantsSelected event carries (TTE-CFG-001). |
group_col | string | null | 'ARM' | Population curve-grouping column (treatment arm). When the population has no such column the module draws one pooled curve (TTE-DATA-004). |
fu_day_col | string | 'EOSDY' | Population follow-up-end study day: the censoring time for participants with no qualifying event (TTE-DERIV-002). Event-free participants without a usable value are excluded with a counted reason. |
censor_desc_col | string | null | 'EOSSTT' | Optional population censoring description (e.g. end-of-study status), shown in censor-mark tooltips. |
event_day_col | string | 'ASTDY' | Event onset study day (day 1 = first dose). Event rows with a missing, non-numeric or non-positive day are excluded and counted (TTE-DATA-002). |
event_desc_col | string | null | 'AEDECOD' | Optional event description column, shown in event tooltips for the qualifying event. |
event_filters | Array.<(string|Object)> | ['AEBODSYS','AEDECOD','AESER','AESEV'] | Multiselect filter controls over the event dataset — the endpoint composer (TTE-FILT-001): column names or { value_col, label } specs. A filter whose column is absent from the events is dropped with a console warning. |
endpoint_label | string | 'Time to first qualifying event' | Display name for the composed endpoint, used in the notes. |
filters | Array.<(string|Object)> | [] | Population filter controls (single-select): column names or { value_col, label } specs. |
direction | string | 'incidence' | `incidence` (1 − KM, rising — the safety default, D2) or `survival` (falling). Anything else falls back to incidence. |
ci | boolean | true | Whether to draw the pointwise 95% confidence band (D3). |
time_unit | string | 'day' | Axis label unit; display only, no rescaling. |
width | string | '100%' | Widget width, carried for the R widget bindings. |
height | number | 560 | Chart-area height in pixels, carried for the R widget bindings; includes the in-canvas risk table. |
Data contract
safety.viz time-to-event data contract
Two datasets: event-level records (one row per event, e.g. an ADAE projection) and population records (one row per participant, e.g. an ADSL projection carrying the follow-up-end study day). The module composes the endpoint from the events passing the active multiselect filters (TTE-FILT-001), takes each participant's first qualifying event by onset day (TTE-DERIV-001), censors event-free participants at the population follow-up day (TTE-DERIV-002), and computes the Kaplan-Meier product-limit estimator, Greenwood variance and log-log pointwise 95% bounds from the derived observations. The derivation rule is fixed and stated in the clinical guide; records that cannot be used are counted and exported rather than dropped silently (TTE-DATA-002). Column names are supplied by the settings mapping.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
events | array | yes | — | d3.csv()-style event records; every row carries the participant id and onset-day columns named in settings, plus any descriptor columns the event filters use (body system, preferred term, seriousness, severity, ...). Rows with a missing, non-numeric or non-positive day, or a participant absent from the population data, are excluded with a counted, exportable reason (TTE-DATA-002). |
population | array | yes | — | d3.csv()-style population records, one row per participant: the analysis denominator. Every row carries the participant id and follow-up-end day columns named in settings; the group column is optional (one pooled curve when absent, TTE-DATA-004). Later duplicate rows for a participant are excluded with a counted reason (TTE-DATA-003). |
settings | object | yes | — | Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied. |
settings.id_col | string | no | USUBJID | Participant identifier column, required in both datasets, and the key the participantsSelected event carries (TTE-CFG-001). |
settings.group_col | string,null | no | ARM | Population curve-grouping column (treatment arm). Optional: when the population has no such column, one pooled curve is drawn (TTE-DATA-004). |
settings.fu_day_col | string | no | EOSDY | Population follow-up-end study day (day 1 = first dose): the censoring time for participants with no qualifying event (TTE-DERIV-002); required in population data. Event-free participants without a usable value are excluded with a counted reason. |
settings.censor_desc_col | string,null | no | EOSSTT | Optional population censoring description (e.g. end-of-study status), shown in censor-mark tooltips. |
settings.event_day_col | string | no | ASTDY | Event onset study day (day 1 = first dose); required in event data. Missing, non-numeric or non-positive days exclude the row with a counted, exportable reason (TTE-DATA-002). |
settings.event_desc_col | string,null | no | AEDECOD | Optional event description (e.g. the preferred term), shown in event tooltips for the qualifying event. |
settings.event_filters | array | no | AEBODSYS,AEDECOD,AESER,AESEV | Multiselect filter controls over the event dataset — the endpoint composer (TTE-FILT-001): column names or { value_col, label } specs. Which columns get a filter is configurable; which values qualify is the reviewer's live choice, never hard-coded. A filter whose column is absent from the events is dropped with a console warning. |
settings.endpoint_label | string | no | Time to first qualifying event | Display name for the composed endpoint, used in the notes (TTE-FILT-003). |
settings.filters | array | no | | Single-select filter controls over the population rows: column names or { value_col, label } specs. A filter whose column is absent from the population is dropped with a console warning. |
settings.direction | string | no | incidence | Display orientation: cumulative incidence (1 - KM, rising - the safety convention and the FDA ST&F figures' orientation, D2) or survival (falling). The y-axis names the estimator either way (TTE-CURV-004). |
settings.ci | boolean | no | true | Whether to draw the pointwise 95% confidence band (Greenwood variance, log-log transform, matching survival::survfit conf.type='log-log'; D3). The band is pointwise, not simultaneous, and is labelled as such (TTE-CURV-003). |
settings.time_unit | string | no | day | Axis label unit; display only - the module never rescales times. |
settings.width | string | no | 100% | Widget width, carried for the R widget bindings; the shell always spans its container. |
settings.height | number | no | 560 | Chart-area height in pixels, including the in-canvas at-risk / cumulative-events table. |