`participant-profile` 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. participantProfile(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 (setAeData, setExpanded, init, setData, applySettings, setSettings, setSelected, show, clear, 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

`participantProfile([element], [data], [settings])`

Create a standalone participant profile inside a container element (PPRF-1). The control shell renders immediately and the module starts listening for `participantsSelected` on the configured target; pass long-format lab records here (or to setData/init on the returned instance) to bind the data.

Param	Type	Default	Description
`element` (optional)	`string \| HTMLElement`	`'body'`	Container node, or a CSS selector for it.
`data` (optional)	`Array.<Object>`	`null`	Optional long-format lab records; when omitted, call setData/init later.
`settings` (optional)	`Object`	`{}`	Setting overrides, merged onto DEFAULT_SETTINGS and normalized.

Returns: SafetyParticipantProfile — The live profile instance.

Methods

`setAeData(records)`

Ingest adverse-event records once (PPRF-AE-002). Hosts that already hold cleaned AE rows may pass them here instead of through settings.ae.data; either way the cleaning runs once per call, never per gesture.

Param	Type	Default	Description
`records`	`Array.<Object>`	—	Raw adverse-event records.

Returns: SafetyParticipantProfile — The instance, for chaining.

`setExpanded(expanded)`

Expand the rail to fill the host renderer's own container, or collapse it back (decision D3). Deliberately NOT a viewport overlay or the native Fullscreen API: the same module has to behave identically inside a gsm.safety htmlwidget and an open.gismo panel, where escaping the container is either impossible or rude.

Param	Type	Default	Description
`expanded`	`boolean`	—	The target state.

Returns: SafetyParticipantProfile — The instance, for chaining.

`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 lab records matching the profile data contract.

Returns: SafetyParticipantProfile — The instance, for chaining.

`setData(data)`

Replace the bound data and re-render (standalone ingest path). The data is validated against the settings mapping (throwing, and rendering the message into the target element, when required columns are missing), then cleaned and baseline-derived through the shared hep-core reducers.

Param	Type	Default	Description
`data`	`Array.<Object>`	—	Long-format lab records matching the profile data contract.

Returns: SafetyParticipantProfile — The instance, for chaining.

`applySettings(settings)`

Merge setting overrides onto the current settings without re-rendering: the merge half of setSettings, also used by a docked host to refresh live pass-through settings (cuts, axis type, display) before its own selection re-dispatch re-renders the block (PPRF-7).

Param	Type	Default	Description
`settings`	`Object`	—	Setting overrides to merge.

Returns: SafetyParticipantProfile — The instance, for chaining.

`setSettings(settings)`

Merge setting overrides onto the current settings, adopt a provided display mode into the live state, re-clean any bound data, and re-render.

Param	Type	Default	Description
`settings`	`Object`	—	Setting overrides to merge.

Returns: SafetyParticipantProfile — The instance, for chaining.

`setSelected(ids)`

Programmatic selection: the same path the participantsSelected listener takes (PPRF-6). A non-empty list ranks and shows the cohort; an empty list clears.

Param	Type	Default	Description
`ids`	`Array.<(string\|number)>`	—	The selected participant ids.

Returns: SafetyParticipantProfile — The instance, for chaining.

`show(ids, [cleanRows])`

Show a selection: rank the ids worst-first (PPRF-5) and render the profile for the first. The docked mount passes the host's pre-cleaned rows, which are consumed verbatim — no checkInputs, no cleanData (PPRF-1).

Param	Type	Default	Description
`ids`	`Array.<(string\|number)>`	—	The selected participant ids.
`cleanRows` (optional)	`Array.<Object>`	—	Pre-cleaned rows carrying the __hep_* columns (dock contract).

Returns: SafetyParticipantProfile — The instance, for chaining.

`clear()`

Clear the profile block: destroy the live charts, empty the slot (the shell's `.sv-profile:empty` rule hides it), and return the standalone mount to its idle note.

Returns: SafetyParticipantProfile — The instance, for chaining.

`render()`

Re-render from the current state: the profile when a selection is live, the idle/empty state otherwise.

Returns: SafetyParticipantProfile — The instance, for chaining.

`resize()`

Resize the live charts to their containers — the spaghetti card and any open measure-table insets. For host layouts that change the container size without a window resize (e.g. the R htmlwidget bindings).

Returns: void —

`destroy()`

Tear the profile down: destroy the charts, remove the standalone event listener, and empty the mount 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 (PPRF-1).
`measure_col`	`string`	`'TEST'`	Column holding the measure name; rows are matched to the ALT/AST/TB/ALP keys via measure_values (PPRF-3).
`value_col`	`string`	`'STRESN'`	Column holding the numeric result; rows with missing/non-numeric values are removed (PPRF-1).
`unit_col`	`string`	`'STRESU'`	Optional unit column.
`normal_col_high`	`string`	`'STNRHI'`	Upper-limit-of-normal column; the ×ULN denominator and the outlier-high flag (PPRF-4).
`normal_col_low`	`string \| null`	`'STNRLO'`	Lower-limit-of-normal column; the sparkline band floor and the outlier-low flag (PPRF-4).
`studyday_col`	`string \| null`	`'DY'`	Study-day column; the spaghetti / inset x-axis (PPRF-3/4).
`visit_col`	`string \| null`	`'VISIT'`	Visit column, carried onto spark points.
`visitn_col`	`string \| null`	`'VISITNUM'`	Numeric visit column.
`baseline_col`	`string \| null`	`null`	Optional baseline-flag column, feeding deriveBaseline and the hep-core reduction (PPRF-5).
`baseline_value`	`string`	`'Y'`	The value of baseline_col that marks the baseline record.
`details`	`Array.<(string\|Object)>`	`[]`	Header demographics: column names or { value_col, label } specs (PPRF-2).
`measure_values`	`Object`	—	Map of the short measure key (ALT/AST/TB/ALP) to the full TEST string in the data (PPRF-3).
`cuts`	`Object`	—	Per-measure reference cutpoints keyed by measure then display mode; a `defaults` entry back-fills any measure without its own cuts (PPRF-3).
`display`	`string`	`'relative_uln'`	Initial display mode: `relative_uln` (×ULN) or `relative_baseline` (×Baseline) (PPRF-3).
`display_options`	`Array.<{value: string, label: string}>`	—	Display-toggle labels (PPRF-3).
`axis_type`	`string`	`'linear'`	Spaghetti y-axis scale: `linear` or `log`; a host passes its live axis-type state through so the drill-down follows the chart (PPRF-3/7).
`measureBounds`	`Array.<number>`	`[0.01, 0.99]`	Population-extent quantiles for the sparkline / inset guides (PPRF-4).
`participantProfileURL`	`string \| null`	`null`	Optional link-out URL, templated by every literal `{id}` token (PPRF-2, closes #53).
`p_alt_col`	`string \| null`	`null`	Optional column carrying a pre-computed P_ALT; passed through where present, and always preferred over a computed one (PPRF-2).
`calculate_palt`	`boolean`	`false`	Opt in to computing P_ALT from the participant's ALT trajectory when `p_alt_col` supplies none (HEP-PALT-001). Off by default: the estimate assumes ALT in IU/L and a study-day axis dense enough for a trapezoidal AUC, which only the data owner can confirm.
`listing`	`boolean`	`false`	Optional participant record listing under the measure table, via the shared listing renderer (PPRF-4).
`listing_cols`	`Array.<(string\|Object)> \| null`	`null`	Listing columns as names or { value_col, label } specs; null derives them from the lab mapping columns.
`listing_page_size`	`number`	`10`	Listing page size.
`listen_to`	`Element \| string \| null`	`null`	Standalone event target (Element or selector); null → document (PPRF-6).
`on_clear`	`function \| null`	`null`	Callback the Clear affordance invokes so the host clears its own selection (PPRF-2/6).
`on_step`	`function \| null`	`null`	Callback (id) fired on stepper navigation so the host keeps its highlight in sync (PPRF-5).
`filters`	`Array.<(string\|Object)>`	`[]`	Normalized to spec arrays — required by the hep-core reducers' settings shape.
`groups`	`Array.<(string\|Object)>`	`[]`	Normalized to spec arrays — required by the hep-core reducers' settings shape.
`width`	`string`	`'100%'`	Widget width, carried over for the R widget bindings.
`height`	`number`	`300`	Spaghetti chart-area height in pixels.

Data contract

safety.viz participant-profile data contract

Long-format lab data: one record per participant per measure per visit/day — the same contract the hep-explorer consumes, so the docked mount can read a host chart's already-cleaned rows verbatim (PPRF-1). Column names are supplied by the settings mapping; the standalone mount standardizes each value to ×ULN and ×Baseline, matches the key liver measures from the measure column via measure_values, and removes missing/non-numeric results with a reported count. The docked mount skips ingest entirely and is fed pre-cleaned rows imperatively.

Field	Type	Required	Default	Description
`data`	`array`	yes	—	d3.csv()-style records; every row carries the participant, measure, result, and ULN columns named in settings, one row per participant per measure per visit/day.
`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`	yes	`USUBJID`	Participant identifier column; the profile renders one participant at a time and steps through a multi-participant selection (PPRF-1, PPRF-5).
`settings.measure_col`	`string`	yes	`TEST`	Column holding the measure name; required in data. Matched to the ALT/AST/TB/ALP keys via measure_values (PPRF-3).
`settings.value_col`	`string`	yes	`STRESN`	Column holding the numeric result; required in data. Non-numeric results are removed with a reported count (PPRF-1).
`settings.unit_col`	`string`	no	`STRESU`	Optional unit column, carried onto measure labels and spark points.
`settings.normal_col_high`	`string`	yes	`STNRHI`	Upper limit of normal (ULN); required in data — the ×ULN standardization divides each value by it, and it feeds the outlier-high flag (PPRF-4).
`settings.normal_col_low`	`string,null`	no	`STNRLO`	Optional lower limit of normal; the sparkline band floor and the outlier-low flag (PPRF-4).
`settings.studyday_col`	`string,null`	no	`DY`	Study-day column; the x-axis of the labs-over-time spaghetti and the expanded inset (PPRF-3, PPRF-4).
`settings.visit_col`	`string,null`	no	`VISIT`	Visit-name column, carried onto spark points and tooltips.
`settings.visitn_col`	`string,null`	no	`VISITNUM`	Numeric visit column, the fallback ordering when no study day exists.
`settings.baseline_col`	`string,null`	no	—	Optional baseline-flag column; when null, the earliest record per measure is the baseline for the ×Baseline display (PPRF-3).
`settings.baseline_value`	`string`	no	`Y`	The value of baseline_col that marks the baseline record.
`settings.details`	`array`	no	—	Header demographics: column names or { value_col, label } specs rendered as label/value pairs in the participant header (PPRF-2).
`settings.measure_values`	`object`	no	`[object Object]`	Map of the short measure key (ALT/AST/TB/ALP) to the full measure string in the data (PPRF-3).
`settings.cuts`	`object`	no	`[object Object]`	Per-measure reference cutpoints keyed by measure then display mode; a `defaults` entry back-fills any measure without its own cuts — the spaghetti's dashed reference lines (PPRF-3).
`settings.display`	`string`	no	`relative_uln`	Initial display mode: `relative_uln` (×ULN) or `relative_baseline` (×Baseline) (PPRF-3).
`settings.measureBounds`	`array`	no	`0.01,0.99`	Population-extent quantiles drawn as band guides behind each sparkline and the expanded inset (PPRF-4).
`settings.participantProfileURL`	`string,null`	no	—	Optional link-out URL for the header; every literal `{id}` token is replaced with the URL-encoded participant id (PPRF-2, closes #53).
`settings.calculate_palt`	`boolean`	no	`false`	Opt in to computing P_ALT from the participant's ALT trajectory when p_alt_col supplies no value; a supplied value always wins (HEP-PALT-001).
`settings.p_alt_col`	`string,null`	no	—	Optional column carrying a pre-computed P_ALT; passed through where present, never computed client-side (PPRF-2).
`settings.listing`	`boolean`	no	`false`	Whether to render the participant's raw records in the shared listing under the measure table (PPRF-4).
`settings.listen_to`	`string,null`	no	—	Standalone event target (Element or selector) the module listens to for participantsSelected; null listens on document. The profile never dispatches selection events of its own (PPRF-6).
`settings.filters`	`array`	no	—	Filter specs normalized for the shared reducers' settings shape; the profile renders no filter controls of its own.
`settings.groups`	`array`	no	—	Group specs normalized for the shared reducers' settings shape.