Skip to contents

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, and 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