safety.viz

safety.viz is a charting library for monitoring clinical trial safety. Point any of its nine interactive charts at your study data and review it in the browser: filter, group, zoom, and click through from a pattern on the screen to the participant records behind it. It's an agent-assisted update of the safetyGraphics interactive renderers.

▶ Try every chart live: https://jwildfire.github.io/safety.viz/

The charts

Chart	What it shows
Safety Histogram	Distribution of any lab or vital-sign measure, with normal-range overlay, treatment-group small multiples, and a linked participant listing
Safety Outlier Explorer	Every participant's results over time as one line each, against the population — click a line to isolate a participant
Safety Results Over Time	Population distribution of a measure at each visit as box-and-whisker marks, with grouping and outlier flags
Safety Shift Plot	Baseline vs. comparison-visit values on a scatter — who moved, and which direction
Safety Delta-Delta	Paired change-from-baseline for two measures on one scatter (e.g. ALT change vs. AST change)
Adverse Event Timelines	Each participant's AEs as timelines colored by severity, serious events marked, with click-through detail
Adverse Event Explorer	AE prevalence by system organ class and preferred term, with per-arm rates, between-arm differences, and participant drill-down
Hepatic Safety Explorer	eDISH scatter of peak liver measures with Hy's Law quadrants, plus a baseline-referenced composite view for abnormal-baseline populations
QT Safety Explorer	QT/QTc central tendency against the ICH E14 threshold, an outlier scatter, and categorical crossing counts

Every chart has a live demo against real example data, a generated API reference documenting every setting, and its own test-evidence report — all linked from its page on the site.

Using it

Vendor the committed bundle — no build step, no npm install:

<script src="dist/safety.viz-1.11.2/safety.viz.js"></script>
<script>
  SafetyViz.histogram('#container', {
    value_col: 'STRESN',
    measure_col: 'TEST',
    filters: [{ value_col: 'ARM', label: 'Treatment Group' }]
  }).init(rows); // rows: array of records, e.g. parsed from an ADaM BDS extract
</script>

An ESM build is committed alongside:

import { histogram } from './dist/safety.viz-1.11.2/safety.viz.esm.js';
histogram('#container', settings).init(rows);

Data. Charts take an array of plain records, one row per result — a parsed CSV or JSON extract. Each chart declares its expected columns in a JSON-Schema data contract and validates its input on init: malformed rows are removed and counted, not silently plotted. Column defaults follow ADaM-style names (USUBJID, TEST, STRESN, VISIT, …) and every mapping is a setting, so any tidy dataset works.

Settings. Every setting has a default, a type, and a description in the generated API reference — e.g. the histogram API; each chart's site page links its own.

Using R? gsm.safety wraps this same bundle as Widget_* htmlwidgets — one per chart.

Building another chart library beside it? The parts every chart shares — the control sidebar, filters, record listing, participant rail and the bundled Chart.js — are exported as SafetyViz.kit (kit in the ESM build), so a second library on the page builds from them instead of copying them. The kit reference lists every member; a change to one is a breaking change.

Run the demo app on your own machine

The demo app loads a study, checks how its columns map, and draws it in every chart. One script puts the same page on your own computer. You need Node.js 22 or later and git.

curl -fsSLO https://raw.githubusercontent.com/jwildfire/safety.viz/main/scripts/install-demo.mjs
node install-demo.mjs

The script checks for Node and git, clones the latest release into ./safety.viz, installs it, builds the demo and opens it in your browser at an address it prints, http://127.0.0.1:8642/ unless that port is busy. The install takes about 285 MB of disk, most of it the tools that build the demo.

• Stop and start. Ctrl+C stops it. Run the script again, with the same --ref if you named one, or cd safety.viz and npm run demo, to start it again: what is already there is used as it is, with nothing downloaded or installed a second time.
• Options. --ref v1.9.2 installs that release rather than the latest, --dir <path> installs somewhere else, --port <number> names the port and --no-open leaves the browser alone. node install-demo.mjs --help lists them.
• Another release later. An install is never moved to another release: give the new one its own directory, --ref v1.9.3 --dir safety.viz-1.9.3.
• Already have a clone? npm ci, then npm run demo.
• Your data stays with you. The page is served to your own computer, at its own address, and to nothing else, and files you load are read in your browser. The one thing it asks the network for is R, and only when you press Start R: from webr.r-wasm.org for the biomarker charts, and from there and repo.r-wasm.org for the RBQM tab.
• Windows. The script is plain Node and is written to run there, but it has not been tried there yet: it has been run end to end on macOS, and its tests run on Linux. In Windows PowerShell write curl.exe in place of curl.
• Nothing to install? Download the single file and open it: the same app in one HTML file that runs with no network. It carries no demo study and cannot start R, so load your own files.

Example data

The demos and evidence reports run on pharmaverseadam, the pharmaverse consortium's ADaM test data derived from the CDISC SDTM/ADaM Pilot 01 study (Apache-2.0), vendored as CSVs under site/data/ by scripts/build-demo-data.mjs.

One cleaning step is applied, to the ECG data. Like plenty of real trial data, the pilot is internally inconsistent here: it collects RR interval and heart rate as separate measurements, and the two contradict each other — they were generated independently, so only 0.8% of readings agree. Its pre-derived QTc parameters are corrected against that collected RR, which puts them about 80 ms high. The build therefore derives QTcF and QTcB itself, correcting against the RR implied by the recorded heart rate — the more credible of the two inputs — and fails if the RR source ever contradicts heart rate again. To be clear about where the fault lies: the packages that produced the data behave exactly as documented; the inconsistency is in the source, and this is routine cleaning rather than a defect report.

Two additions are also made for coverage: placeholder rows for participants with no adverse events, so AE denominators cover the whole safety population, and a small synthetic chronic-liver-disease cohort, without which the hep-explorer composite plot has no abnormal-baseline population to draw. Everything else ships as sourced. Full provenance, including what the cleaning does and does not fix, is in docs/DATA_SOURCES.md.

Quality and evidence

Each chart re-implements an interactive display built by Rho, Inc. and used in practice under the safetyGraphics project. The port is held to that standard: every chart traces to a reviewed requirement matrix, tests are keyed to requirement IDs, and results are published as audit-style evidence reports with every release.

Documentation site

https://jwildfire.github.io/safety.viz/ — gallery, live demos, API reference, and evidence reports.

Tier	Tracks
root	latest release (main)
/dev/	the dev branch
/pr/{N}/	open pull-request previews

Layout

src/
├── main.js               # public module collection (the nine renderers)
├── {chart}.js            # one entry per renderer, plus a {chart}/ dir of parts
└── data/schema/          # JSON Schema data contracts, one per chart
site/                     # documentation-site sources (gallery, demos, shell)
docs/                     # requirement-coverage docs + evidence data
scripts/                  # build, site, API-reference, and evidence tooling
tests/
├── unit/                 # Vitest specs
└── e2e/                  # Playwright specs + fixtures
dist/                     # committed, versioned esbuild bundles

Stack

Chart.js v4 · esbuild (IIFE + ESM bundles to dist/safety.viz-{version}/) · Vitest · Playwright · Prettier. See CONTRIBUTING.md for commands and the test-naming / traceability conventions.

Distribution

dist/safety.viz-{version}/ is committed (not published to npm). Consumers like gsm.safety vendor a specific version at inst/htmlwidgets/lib/safety.viz-{version}/, the precedent set by gsm.kri vendoring gsm.viz.

Lineage

safety.viz is part of the safetyGraphics → gsm modernization (design doc · roadmap), mirroring the architecture of gsm.viz behind gsm.kri. Full credits are on the about page.

License

Apache License 2.0. See LICENSE.