r4subtrace

r4subtrace is the traceability engine in the R4SUB ecosystem. It quantifies end-to-end traceability between clinical submission artifacts — ADaM outputs ↔︎ derivations ↔︎ SDTM sources ↔︎ specs ↔︎ code — and converts trace evidence into standardized R4SUB evidence rows.

Can we prove where each analysis variable came from, and can a reviewer follow it?

Installation

install.packages("r4subtrace")

Development version:

pak::pak(c("R4SUB/r4subcore", "R4SUB/r4subtrace"))

Traceability Levels

Level	Name	Description
L0	None	No linkage available
L1	Spec-only	ADaM spec defines derivation, no code mapping
L2	Spec + source	ADaM variable mapped to SDTM variables/domains
L3	Spec + code	Mapping with high confidence or derivation text

Quick Start

library(r4subcore)
library(r4subtrace)

ctx <- r4sub_run_context(study_id = "ABC123", environment = "DEV")

# Build a trace model from metadata and mapping tables
tm <- build_trace_model(
  adam_meta = adam_metadata,
  sdtm_meta = sdtm_metadata,
  mapping   = trace_mapping
)

# Emit evidence rows
ev <- trace_model_to_evidence(tm, ctx = ctx,
                              source_name = "r4subtrace",
                              source_version = "0.1.0")

validate_evidence(ev)

# Indicator scores
ind <- trace_indicator_scores(ev)

Trace Indicators

Indicator	Description
TRACE_VAR_COVERAGE_L2PLUS	Proportion of ADaM variables with L2+ trace
TRACE_VAR_COVERAGE_L3PLUS	Proportion with L3+ trace
TRACE_ORPHAN_VAR_COUNT	ADaM variables with no SDTM mapping
TRACE_AMBIGUOUS_MAPPING_COUNT	Variables mapped to multiple SDTM sources
TRACE_MEAN_TRACE_LEVEL	Mean trace level across all ADaM variables

Key Functions

Function	Purpose
trace_config_default()	Default traceability configuration
build_trace_model()	Build a trace graph from metadata and mappings
compute_trace_levels()	Assign L0–L3 trace levels per ADaM variable
trace_model_to_evidence()	Emit r4subcore-compatible evidence rows
trace_indicator_scores()	Compute trace indicator scores
validate_mapping()	Validate a mapping table for required columns
validate_metadata()	Validate ADaM/SDTM metadata tables

Design Principles

• Graph-first: traceability is a graph problem
• Evidence-first: all conclusions are backed by explicit evidence rows
• Tool-agnostic: ingest mappings from any source format
• Reviewer-centric: emphasize explainability, not just metrics

License

MIT