histogram 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. histogram(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
histogram([element], [settings])
Create a safety histogram 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) | HistogramSettings | {} | Setting overrides, merged onto DEFAULT_SETTINGS and normalized. |
Returns: SafetyHistogram — The live histogram 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 (SH-API-001).
| Param | Type | Default | Description |
|---|---|---|---|
data | Array.<Object> | — | Long-format result records matching the histogram data contract. |
Returns: SafetyHistogram — 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 histogram data contract. |
Returns: SafetyHistogram — 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 | HistogramSettings | — | Setting overrides to merge. |
Returns: SafetyHistogram — The instance, for chaining.
render()
Redraw everything from the current data, settings, and control state: destroys the live charts, clears the listing and any bar selection, then draws the main chart, the grouped small multiples, and the participant-count notes. Called automatically by the controls and the data/settings setters; call it directly only after mutating state by hand.
Returns: void —
resize()
Resize every live chart (the main chart and any small multiples) 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 histogram 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
| Setting | Type | Default | Description |
|---|---|---|---|
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. |
id_col | string | 'USUBJID' | Participant identifier column; drives the participant counts shown above the chart and the default listing columns. |
unit_col | string | 'STRESU' | Unit column, appended to the measure name in labels when present. |
normal_col_low | string | 'STNRLO' | Lower-limit-of-normal column; with normal_col_high, feeds the normal-range overlay. The control hides for measures without normal-range data (SH-FUNC-004C). |
normal_col_high | string | 'STNRHI' | Upper-limit-of-normal column; see normal_col_low. |
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 for the small-multiple charts; a "None" option is always offered first. |
details | Array.<(string|Object)> | null | null | Columns for the linked participant listing; when null, defaults to participant ID, the filter columns, result, normal limits, and unit. |
start_value | string | null | null | Measure selected on first render. When null (the default) the histogram opens on the all-measures overview — one small-multiple histogram per measure, click one to drill in. A measure absent from the data falls back to the overview with a console warning. |
bin_algorithm | string | "Scott's normal reference rule" | Binning algorithm applied on first render; one of the ALGORITHMS options. Setting an explicit bin quantity or width in the UI switches it to "Custom". |
normal_range | boolean | true | Offer the Show Normal Range control (visible only for measures with normal-range data). |
display_normal_range | boolean | false | Draw the normal-range overlay on first render. The pilot's camelCase alias displayNormalRange is still honored. |
annotate_bin_boundaries | boolean | false | Label the x-axis with bin boundaries instead of linear ticks on first render. |
test_normality | boolean | false | Annotate the main chart with an approximate Jarque-Bera normality screen. |
group_by | string | 'sh_none' | Column the small multiples are grouped by on first render; 'sh_none' disables grouping. Unknown columns are added to the group options as-is. |
compare_distributions | boolean | false | When grouped, annotate each panel with an approximate one-way ANOVA screen comparing the groups. |
width | string | '100%' | Widget width, carried over from the pilot API for the R widget bindings; the current shell always spans its container. |
height | number | 460 | Chart-area height in pixels, carried over from the pilot API for the R widget bindings; the current shell fixes the chart area at 460px. |
page_size | number | 10 | Rows per page in the linked participant listing. |
Data contract
safety.viz histogram data contract
Long-format results data: one record per measurement (SH-DATA-001). Column names are supplied by the settings mapping; the histogram removes missing/non-numeric results with a reported count (SH-DATA-002) and degrades gracefully when optional columns are absent (SH-DATA-003).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | array | yes | — | d3.csv()-style records; every row carries the measure and result 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.id_col | string | no | USUBJID | Optional participant identifier column. |
settings.unit_col | string | no | STRESU | Optional unit column, appended to measure labels. |
settings.normal_col_low | string | no | STNRLO | Optional lower limit of normal; normal-range UI hides for measures without normal data (SH-FUNC-004C). |
settings.normal_col_high | string | no | STNRHI | Optional upper limit of normal. |
settings.filters | array | no | — | Optional filter columns rendered as controls. |
settings.groups | array | no | — | Optional group-by columns for small-multiple charts. |
settings.details | array | no | — | Optional listing columns; defaults derive from the other mappings. |