sdtm-oak
Derives CDISC SDTM domains from raw clinical (EDC/eCRF) data using the {sdtm.oak} R package. Use when a user needs to map raw study data to SDTM Events (AE, CM, MH), Findings (VS, LB, EG), or Interventions (EX) domains following the sdtm.oak algorithm framework. Produces executable, submission- ready R code with controlled terminology recoding, ISO 8601 date derivation, sequence numbering, and study day calculation.
RConsortium · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add RConsortium/pharma-skills --skill sdtm-oak技能说明
name: sdtm-oak description: > Derives CDISC SDTM domains from raw clinical (EDC/eCRF) data using the {sdtm.oak} R package. Use when a user needs to map raw study data to SDTM Events (AE, CM, MH), Findings (VS, LB, EG), or Interventions (EX) domains following the sdtm.oak algorithm framework. Produces executable, submission- ready R code with controlled terminology recoding, ISO 8601 date derivation, sequence numbering, and study day calculation. license: MIT metadata: author: pharma-skills contributors version: "0.1" pharmaverse: "true" compatibility: > Requires R with sdtm.oak (>= 0.2.0), dplyr, and tibble installed. Requires raw EDC/eCRF data and a controlled terminology (CT) specification CSV. Designed for use in a GxP-compliant environment.
sdtm-oak
Derives CDISC SDTM domains from raw clinical data using the {sdtm.oak} algorithm framework. Outputs executable R code with full derivation traceability.
See references/oak-functions.md for the full
function reference.
Inputs
Before generating code, confirm:
| Input | Required | Notes |
|---|---|---|
| Raw EDC dataset | Yes | e.g. ae_raw, vs_raw — raw CRF form data |
| CT specification | Yes | CSV in CDISC codelist format; load via read_ct_spec() |
| Domain specification | Yes | Variable list, CT codelists per variable, date formats |
| DM domain | For study day / BLFL | Provides RFSTDTC for derive_study_day() and derive_blfl() |
Always inspect the raw dataset first — raw column names vary by EDC system
and study. Print names(raw_dat) and head(raw_dat) before writing any
derivations.
Core algorithms
sdtm.oak provides six mapping algorithms. Choose based on whether the target variable has controlled terminology (CT) and whether the value is derived from raw data or hardcoded.
| Algorithm | CT? | Source | Use for |
|---|---|---|---|
assign_no_ct() | No | Raw column | Free-text variables: AETERM, CMTRT, VSORRES |
assign_ct() | Yes | Raw column | CT-mapped from raw: AESEV, AESER, SEX, RACE |
hardcode_no_ct() | No | Fixed value | Study-constant free-text: STUDYID, custom flags |
hardcode_ct() | Yes | Fixed value | Domain constants validated against CT: DOMAIN |
assign_datetime() | — | Raw date col(s) | Any --DTC variable: AESTDTC, VSDTC, EXSTDTC |
condition_add() | — | Condition expr | Gate any of the above to a row subset |
All six functions share the same id_vars join key (default: oak_id_vars())
and the same tgt_dat pipe pattern — pass the growing SDTM dataset as
tgt_dat to accumulate variables.
Workflow
Follow these steps in order. Write code section by section, not as a single block.
Step 1 — Setup and data inspection
library(sdtm.oak)
library(dplyr)
# Load raw data — replace with actual source
ae_raw <- <load raw AE data> # e.g. sdtm.oak::ae_raw for the package example
# ALWAYS inspect before writing derivations
cat("Columns:\n"); print(names(ae_raw))
cat("Rows:", nrow(ae_raw), "\n")
print(head(ae_raw, 3))
Step 2 — Generate oak ID variables
generate_oak_id_vars() adds three key columns used as join keys throughout
all subsequent derivations. Call this once on the raw dataset.
# REVIEW: Set pat_var to the column holding the subject/patient identifier
# in this raw dataset. Set raw_src to the raw dataset object name (e.g. "ae_raw",
# "vs_raw") — pharmaverse convention uses the dataset name, not a CRF form label.
ae_oak <- generate_oak_id_vars(
raw_dat = ae_raw,
pat_var = "patient_number", # confirm column name from Step 1 inspection
raw_src = "ae_raw" # pharmaverse convention: use the raw dataset name
)
# Adds: oak_id (row key), raw_source (form label), patient_number (subj ID)
Step 3 — Load controlled terminology
# REVIEW: Replace path with the study CT spec CSV.
# For the sdtm.oak package example data, use read_ct_spec_example().
ct_spec <- read_ct_spec_example() # or: read_ct_spec("path/to/ct_spec.csv")
# Validate before use
assert_ct_spec(ct_spec)
Step 4 — Hardcode domain constants
Fixed values that apply to every record in the domain. Use hardcode_ct() for
values validated against CT (DOMAIN); use hardcode_no_ct() for free-text constants.
ae_domain <- ae_oak |>
# DOMAIN is a CT-controlled variable — use hardcode_ct
hardcode_ct(
tgt_var = "DOMAIN",
tgt_val = "AE",
raw_dat = ae_raw,
raw_var = "AETERM", # presence filter: only rows with a non-NA AE term
ct_spec = ct_spec,
ct_clst = "DOMAIN"
)
Step 5 — Assign free-text variables (assign_no_ct)
Use for variables with no CT restriction — raw text carried directly.
ae_domain <- ae_domain |>
assign_no_ct(
tgt_var = "AETERM",
raw_dat = ae_raw,
raw_var = "ae_term" # REVIEW: confirm raw column name
) |>
assign_no_ct(
tgt_var = "AELOC",
raw_dat = ae_raw,
raw_var = "ae_location"
)
Step 6 — Assign CT-mapped variables (assign_ct)
Use for variables whose values must be recoded to CDISC controlled terminology.
Supply ct_clst matching the codelist name in your CT spec.
# REVIEW: Confirm ct_clst names match the codelist_code column in ct_spec.
# Wrong ct_clst silently returns the uppercased raw value — verify outputs.
ae_domain <- ae_domain |>
assign_ct(
tgt_var = "AESEV",
raw_dat = ae_raw,
raw_var = "severity",
ct_spec = ct_spec,
ct_clst = "AESEV"
) |>
assign_ct(
tgt_var = "AESER",
raw_dat = ae_raw,
raw_var = "serious_ae",
ct_spec = ct_spec,
ct_clst = "NY"
) |>
assign_ct(
tgt_var = "AEREL",
raw_dat = ae_raw,
raw_var = "causality",
ct_spec = ct_spec,
ct_clst = "AEREL"
) |>
assign_ct(
tgt_var = "AEOUT",
raw_dat = ae_raw,
raw_var = "outcome",
ct_spec = ct_spec,
ct_clst = "AEOUT"
)
Step 7 — Assign datetime variables (assign_datetime)
U
阅读完整来源 ↗