results-over-time API reference
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. resultsOverTime(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, 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
resultsOverTime([element], [settings])
Create a safety results-over-time chart 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) | ResultsOverTimeSettings | {} | Setting overrides, merged onto DEFAULT_SETTINGS and normalized. |
Returns: SafetyResultsOverTime — The live results-over-time 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 | Array.<Object> | — | Long-format result records matching the results-over-time data contract. |
Returns: SafetyResultsOverTime — 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 results-over-time data contract. |
Returns: SafetyResultsOverTime — 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 | ResultsOverTimeSettings | — | Setting overrides to merge. |
Returns: SafetyResultsOverTime — The instance, for chaining.
render()
Redraw everything from the current data, settings, and control state: destroys the live chart, recomputes the per-visit-group statistics and box specs, and draws the box-and-whisker plot with its outlier overlay.
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 chart 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; drives the participant counts shown above the chart. |
measure_col | string | 'TEST' | Column holding the measure name; required in the data. Each distinct measure (with its unit) becomes an option in the Measure control. |
value_col | string | 'STRESN' | Column holding the numeric result; required in the data. Rows with missing or non-numeric values are removed with a console warning. |
unit_col | string | 'STRESU' | Unit column, appended to the measure name in labels and the y-axis title when present. |
time_col | string | 'VISIT' | Column holding the visit name; required in the data. Distinct visits become the x-axis categories. |
time_order_col | string | 'VISITNUM' | Optional numeric column ordering the visits along the x-axis; falls back to alphanumeric visit order when absent. |
time_label | string | 'Visit' | Axis label for the time (visit) dimension. |
filters | Array.<(string|Object)> | [] | Filter controls: column names or { value_col, label } specs. Filters whose column is absent from the data are dropped with a console warning. |
groups | Array.<(string|Object)> | [] | Group-by options; a "None" option is always offered first. The selected group splits each visit into side-by-side box plots. |
start_value | string | null | null | Measure selected on first render; falls back to the first measure (with a console warning) when absent from the data. |
group_by | string | 'srot_none' | Column the box plots are grouped by on first render; 'srot_none' disables grouping. Unknown columns are added to the group options as-is. |
boxplots | boolean | true | Draw the box-and-whisker marks on first render. |
outliers | boolean | true | Overlay the results outside the 5th/95th percentiles as outlier points on first render. |
visits_without_data | boolean | false | Show x-axis timepoints for visits with no data for the current measure/filters. |
unscheduled_visits | boolean | false | Show unscheduled visits (matched by unscheduled_visit_values or unscheduled_visit_pattern). |
unscheduled_visit_pattern | string | '/unscheduled|early termination/i' | Regular expression (in /source/flags string form) identifying unscheduled visits. |
unscheduled_visit_values | Array.<string> | null | null | Explicit list of unscheduled visit names; takes precedence over unscheduled_visit_pattern when set. |
y_scale | string | 'linear' | Initial y-axis scale, one of the Y_SCALES options ('linear' or 'log'). |
width | string | '100%' | Widget width, carried over for the R widget bindings; the current shell always spans its container. |
height | number | 460 | Chart-area height in pixels, carried over for the R widget bindings; the current shell fixes the chart area at 460px. |
Data contract
safety.viz results-over-time data contract
Long-format results data with a visit dimension: one record per participant per visit per measure (SROT-DATA-001/002). Column names are supplied by the settings mapping; the renderer removes missing/non-numeric results with a reported count and degrades gracefully when optional columns are absent.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | array | yes | — | d3.csv()-style records; every row carries the measure, result, and visit columns named in settings. |
settings | object | yes | — | Column mappings and rendering options; merged onto the module's DEFAULT_SETTINGS, so only overrides need to be supplied. |
settings.measure_col | string | yes | TEST | Column holding the measure name; required in data. |
settings.value_col | string | yes | STRESN | Column holding the numeric result; required in data. |
settings.time_col | string | yes | VISIT | Column holding the visit name; required in data. Distinct visits become the x-axis categories. |
settings.time_order_col | string | no | VISITNUM | Optional numeric column ordering the visits; falls back to alphanumeric order when absent. |
settings.id_col | string | no | USUBJID | Optional participant identifier column driving the participant counts. |
settings.unit_col | string | no | STRESU | Optional unit column, appended to measure labels and the y-axis title. |
settings.filters | array | no | — | Optional filter columns rendered as controls. |
settings.groups | array | no | — | Optional group-by columns that split each visit into side-by-side box plots. |