Skip to content

Readable R programs

In this chapter

  • Make one readable R program per table, and read it top to bottom.
  • Run the readable programs, and compare every number with the engine’s.
  • Say why two implementations that agree are a check.
Time
20 minutes
At the end you have
12 readable R programs in out/r/programs, run, and every one of the 18,392 numbers equal to the engine's.

16.1 The idea: a program that reads like its table

Section titled “16.1 The idea: a program that reads like its table”

The engine’s programs are made for the machine: they read the analysis contract and compute every analysis of a table. A reviewer asks a simpler question: how was this number made? For that reader, Sapling also writes one readable program per table: the population, the records, one call per block of the table, then the layout. The functions come from the R package sapling, one for each SAS macro of Sapling, so a SAS programmer finds the same names.

Terminal
$ sapling r programs --no-companions
r programs R PROGRAMS PASS: 12 program(s) in out/r/programs: 12 table(s), 0 listing(s), 0 figure(s)
out/r/programs/t14_3_1.R
# PROGRAM t14_3_1.R
# study PILOT
# purpose Table 14.3.1 ADAS-Cog (11): Change from Baseline to Week 24 - LOCF
# plan sap.qmd: output T14_3_1 of its analysis contract (out/tlf/spec/pilot_sap.json)
# twin of out/sas/programs/t14_3_1.sas: the same blocks, in the same order, with the same labels
# results each out= data set below is the analysis of the same name in the plan; the N of the columns is T14_3_1_N
# trace sapling find T14_3_1: its blocks of the SAP, its analyses, their variables and where those come from
# inputs ADaM: ADSL ADQSADAS
# outputs tlf/t14_3_1.rtf and .lst, ard/t14_3_1.csv
# Made by sapling from the plan. Do not edit: change sap.qmd or tlf-spec.qmd and make it again.
# The functions (describe, freq, ..., tlf_stack, columns, ard, tlf_layout, tlf_print, kmplot, meanplot ...) are in
# sapling/R/ (the R package sapling: with the package installed, library(sapling) in place of source()),
# each with a header that says what it does.
spl_root <- Sys.getenv("SPL_ROOT", "~/sapling/pilot") # the one line to change on another computer
source(Sys.getenv("SPL_LIB", file.path(spl_root, "sapling", "sapling.R")))
study("PILOT", program = "t14_3_1")
# Efficacy population: one row per subject
adsl <- subset(adam("adsl"), efffl == "Y")
adsl <- adsl[order(adsl$usubjid), ]
# ADQSADAS of the Efficacy population (adsl): its records, with the variables of ADSL
adqsadas <- adam("adqsadas")
adqsadas <- adqsadas[order(adqsadas$usubjid), ]
adqsadas <- adqsadas[adqsadas$usubjid %in% adsl$usubjid, ]
adqsadas <- cbind(adqsadas, adsl[match(adqsadas$usubjid, adsl$usubjid), setdiff(names(adsl), names(adqsadas)), drop = FALSE])
t14_3_1_bl_summ <- describe(
data = adqsadas,
where = paramcd == "ACTOT" & avisit == "Week 24" & anl01fl == "Y",
var = base,
by = trt01p,
label = "Baseline"
)
t14_3_1_v_summ <- describe(
data = adqsadas,
where = paramcd == "ACTOT" & avisit == "Week 24" & anl01fl == "Y",
var = aval,
by = trt01p,
label = "Week 24"
)
t14_3_1_chg_summ <- describe(
...

Read it as the table:

  • The header says what the program makes, from which plan, which data it reads and what it writes. It also says: do not edit; change sap.qmd or tlf-spec.qmd and make it again.
  • The population: subset(adam("adsl"), efffl == "Y"), the efficacy population of the SAP.
  • The records: ADQSADAS of those patients, with the variables of ADSL.
  • One call per block: describe() for the baseline, the value at week 24 and the change, each with its where (the parameter ACTOT, the visit, the analysis flag) and by = trt01p, the planned treatment.
Terminal
$ sapling r run
r run R RUN PASS: 12 program(s) in 15 s: 12 table(s), 0 listing(s), 0 figure(s), 12 ard file(s) in out/r
$ sapling r check
r check R CHECK PASS: 18392 of 18392 numbers of the engine are the same in the readable programs (out/r/check.md)

sapling r run runs the readable programs in R. sapling r check compares every number of the engine with the number of the readable programs: 18,392 of 18,392 are the same. Two programs, written in two styles from the same plan, agree to the last digit. That is the logic of double programming, and it costs no second team.

Your turn 16.1 Find the population

In the readable program of section 16.2, which line makes the population of the table, and which SAP population is it?

Show the answer
out/r/programs/t14_3_1.R
...
# Efficacy population: one row per subject
adsl <- subset(adam("adsl"), efffl == "Y")
adsl <- adsl[order(adsl$usubjid), ]
...

adsl <- subset(adam("adsl"), efffl == "Y"): the patients of ADSL with the efficacy flag, the population EFF of the SAP (chapter 11 shows the rule of EFFFL).

What you learned

  • A readable program shows a table as the population, the records, one call per block and the layout.
  • sapling r run and sapling r check prove that every number of the engine is the same in the readable programs.
  • Agreement of two implementations finds slips in a program, not errors in the plan.

Next: 17 · When a run fails →

Found an error or have a question? Write to datastep.studio@gmail.com· The plan is written in Sapling; every R program runs in DataStep Studio for R.

Data: the CDISC pilot study (cdiscpilot01). The protocol as CDISC USDM from the CDISC 360i project (MIT licence); the SDTM data from the PhUSE scripts repository (MIT licence). Public example data: no real patient.

R is a project of the R Foundation. SAS is a registered trademark of SAS Institute Inc. CDISC, SDTM, ADaM and USDM are trademarks of the Clinical Data Interchange Standards Consortium. Claude is a trademark of Anthropic. This book is not affiliated with or endorsed by any of them.

© 2026 DataStep Labs. All rights reserved.