FDA ST&F static safety displays — phased implementation

1Context and goals

The FDA Standard Safety Tables and Figures: Integrated Guide v2.0 (April 2025, governed by MAPP 6025.9) specifies 60 tables and 22 figures across three delivery tiers. This requirement implements a deliberately scoped subset in R, as static displays that can be reviewed and generated alongside the safety.viz interactive graphics.

The full inventory — every display with its tier, section, chart engine, ADaM domains and the guide's cross-cutting rules — is published as fda_stf_inventory.json alongside the assessment. It is the specification input to this design.

Why the scope is what it is

Open-source coverage of the guide is sharply lopsided. pharmaverse cardinal has templates for 26 of 60 tables but only 4 of 22 figures. Fifteen figures have no static-R implementation in any open-source package, and twelve of those already exist as shipped safety.viz interactive renderers, collapsing into four reusable chart engines. The gap in the ecosystem and the assets already on our shelf are very nearly the same set — so the plan builds figures and borrows tables.

2Architecture — three layers

The framing question was whether to run parallel R and JS libraries or integrate them. Both pure options are rejected:

• One library, JS renders both. Chart.js draws to canvas, so output is raster — submission figures want vector PDF or SVG. Making a headless browser a deliverable-production dependency is also a qualification liability, and it gives no path to RTF or DOCX tables.
• Two fully independent libraries. This duplicates the guide's normative rules — extreme-value exclusion, the under-10% sparse-visit rule, Level 1/2/3 abnormality grading, the 30-day DILI pairing window — in two languages. Two implementations of a regulatory definition will drift.

Instead, three layers, with the sharing in the middle. This mirrors gsm.kri, which pairs Visualize_Scatter (ggplot2) with Widget_ScatterPlot (htmlwidget) over one shared data interface.

3Package layout and API surface

All of it lands in gsm.safety, alongside the seven Widget_* bindings delivered by v1.0.0. This mirrors gsm.kri, which already carries ggplot2, gt, DT, htmlwidgets and rmarkdown in one package, and it is what makes "review the static and interactive versions side by side" possible in a single pkgdown gallery.

gsm.safety/
  R/
    Derive_*.R          # L1 — FDA normative rules (shared)
    Visualize_*.R       # L2a — ggplot2 static figures
    Table_*.R           # L2a — gt / gtsummary tables
    Listing_*.R         # L2a — subject-level listings
    Widget_*.R          # L2b — existing htmlwidget bindings (v1.0.0)
  data/
    FDA_AbnormalityLevels    # Appendix Tables 56–57
    FDA_ExtremeValues        # Appendix Tables 58–60
  inst/workflow/3_reports/
    fda_*.yaml          # workr workflows, one per display

Naming follows the guide's own identifiers so traceability is mechanical: Visualize_HepatocellularDILI() implements Figure 7, Table_DILIQuadrants() implements Tables 21 and 22. Each carries the guide version it was written against.

4Workflow integration, and the cardinal-template question

The question raised was whether we can skip porting table logic entirely and instead add YAML workflows that render the cardinal templates directly. It is the right instinct — cardinal is Apache-2, pharmaverse-hosted, and covers 26 of the guide's tables — so it was investigated against the actual sources rather than assumed.

What the templates actually are

Cardinal's catalog is 27 entries at quarto/catalog/fda-table_NN/index.qmd (26 FDA tables plus one Roche display). Inspecting fda-table_07, the FDA Overview of Adverse Events:

• There is no parameterisation surface. The YAML front matter is title, subtitle and categories only — no params: block. Nothing accepts a dataset.
• The data source is hard-coded. The template loads pharmaverseadam::adsl and ::adae inline.
• Column names are hard-coded to ADaM conventions — TRT01A, USUBJID, SAFFL, AESER, AESDTH, EOSSTT, AESEV — with no mapping layer.
• It fabricates data where the demo set is incomplete. Table 07 generates AEACN with set.seed(1) and sample(), commenting that the dataset "doesn't have treatment action recorded". That is catalog scaffolding, and rendering it against real study data would either error or silently produce invented numbers.
• It carries presentation furniture — Quarto panel-tabsets and knitr::include_graphics("result.png") — that belongs to the catalog website, not to an analysis pipeline.

It also fits the workflow model poorly. gsm.safety's workr steps name R functions and pass R objects:

steps:
  - output: lWidget
    name: gsm.safety::Widget_AeTimelines
    params:
      dfResults: dfResults

A Quarto render is a document build, not a step returning a chainable object, and it would add a Quarto CLI dependency to the runtime.

Three options, and the recommendation

The porting cost is smaller than it first appears. Stripping the demo scaffolding from Table 07 leaves roughly forty lines of genuine logic — a tbl_hierarchical() composition stacked with tbl_stack() and indented with modify_indent(). Cardinal remains extremely valuable as the reference implementation for that logic, and Apache-2 permits reuse with attribution.

5Phased implementation

Phases 0 and 1 begin after gsm.safety v1.0.0 is released — PR #39 merged and tagged. Until then main is the stale v0.1.0 safetyCharts bridge, and static work would be built on a moving foundation.

6Evidence and QC

Static displays use the more traditional testthat path that gsm.safety #27 already anticipates, rather than the Playwright browser evidence the JS renderers need:

• vdiffr snapshots for every Visualize_* figure, reviewed on first commit and regenerated deliberately thereafter.
• ARD equality tests for every Table_* — assert the computed numbers, not the rendered markup, which makes tables testable independently of their formatting.
• Shared-rule tests on Derive_* against the published criteria in the appendix datasets.
• qcthat conventions per #27, including the test-name-carries-its-issue-reference guard already in the v1.0.0 branch.
• Cross-renderer consistency: where a static figure and its safety.viz twin render the same display, assert that both consume the same L1-derived columns and agree on flagged counts.

Displays reach "done" the same way renderers do — visible on the published site with a demo, evidence, and requirement traceability — extended to a static gallery in the gsm.safety pkgdown site so the two renderings sit side by side.

7Decisions

8Out of scope

• The 40-odd guide tables outside the Phase 3 priority set, and the Expanded and Optional tiers generally, except where a table is the direct companion to a Phase 1 figure.
• The Targeted Analysis Guides (Kidney Injury, Liver Injury, Muscle Injury, Dysglycemia, Hypersensitivity) — separate FDA deliverables, not part of the Integrated Guide.
• Open-label-extension displays (T23–T28, and F11 in its OLE framing) beyond F12's basic engine.
• Algorithmic OCMQ tables (T46–T49), which need concomitant-medication and medical-history domains not currently mapped.
• A submission-ready end-to-end package. This produces displays and their source, not a filing.

9Risks

• Scope. Eighty-two numbered displays plus analyte-panel variants is far beyond a solo track. The plan is only credible if the restraint above holds.
• The guide is versioned and moves. v2.0 renumbered displays relative to 2022 — which is exactly why cardinal's figure templates are now stale. Record the guide version against every display ID in the requirement matrix.
• Mock displays are the only specification. No reference implementation and no published reference outputs exist, so "correct" means matching the PDF's mocks and satisfying the stated rules. Record interpretation decisions per display.
• Figures 2, 3 and 12 were characterised from titles and body text, not rendered mocks. Confirm their visual form against the PDF before implementing the dot-plus-forest engine.
• ADaM alignment is assumed. The guide is written against ADaM; gsm.safety v1.0.0 ships pharmaverseadam demo data, which is promising, but the mapping from gsm's Mapped_* domains has not been verified. Phase 0 should settle it.
• The L1 contract change touches shipped code. Moving derivations out of structureData.js risks regressing working renderers; gate it behind the DILI proof and the existing Playwright evidence.
• Cardinal could revive. It is dormant but Roche-backed with several sponsors involved. Re-check before Phase 3; a renewed upstream figure push would change the calculus, and may open a contribution path.

10Acceptance criteria

• Appendix Tables 56–60 ship as tested package datasets.
• The requirement matrix covers every display in scope, keyed so static and interactive renderings of the same display share a requirement ID, each annotated with the guide version.
• All twelve Phase 1 figures render from the four engines, each with vdiffr evidence and a published gallery entry beside its safety.viz twin.
• Normative rules exist once, in Derive_*, with tests against the published criteria — not reimplemented in JS.
• Every Table_* emits both a rendered object and its ARD, with equality tests on the ARD.
• devtools::check() clean, per the ecosystem gate.

11Candidate decomposition

Sub-issues to file in gsm.safety once this design is signed off and the v1.0.0 gate clears — via the requirement-tasks skill, as cross-repo sub-issues of #9.