Skip to content

From the SAP to the programs

In this chapter

  • Say what the SAP decides and what the specifications decide.
  • Make all products of the plan with sapling build, in three parts.
  • Read the population flags in the ADaM specification.
Time
20 minutes
At the end you have
the SAP as a PDF, the ADaM and TLF specifications, 12 shells, 7 ADaM programs and 12 table programs; nothing has run yet.

11.1 The idea: the SAP says what, the specifications say how

Section titled “11.1 The idea: the SAP says what, the specifications say how”

The SAP says what is analysed: in which population, which variable, with which method. The specifications say how the data are made: how each ADaM variable is derived from SDTM, how each table is laid out. The programs are made from both. Nobody edits a program by hand: a change goes into the SAP or into a specification, and the program is made again.

The work has three parts, each with its owner:

Part Products Owner
1 The SAP the structured SAP, its JSON, its PDF the statistician
2 The specifications the ADaM specification (adam-spec.qmd), the TLF specification with the analysis contract, the shells, the QC specification the statistician and the programmer
3 The programs the ADaM programs, the table programs the programmer
Terminal
$ sapling build
1 The SAP (the statistician)
sap.qmd: 1 study, 27 grouping, 22 decision, 1 design, 1 sample_size, 4 population, 12 output, 33 analysis, 15 method, 1 estimand, 19 subset, 1 missing_data, 3 waiver, 1 multiplicity, 1 sensitivity, 1 software, 90 adam, 1 change; 0 error(s), 1 warning(s).
sap structured PASS: out/sap/sap.md, sap.html (234 blocks) (0.1 s)
sap json PASS: out/sap/sap.json (0.0 s)
sap pdf PASS: out/sap/sap.pdf (Quarto, Typst; the extension _extensions/sapling) (3.7 s)
2 The specifications (the statistician and the programmer)
adam-spec.qmd: made from the SAP (yours to edit)
adam spec PASS: adam-spec.qmd, out/adam/spec (7 data sets, define.md) (0.1 s)
tlf-spec.qmd: made from the SAP (yours to edit)
the chain's checker (sap_build.py): SAP BUILD PASS
...
tlf spec PASS: tlf-spec.qmd, out/tlf/spec (the contract; ARS JSON Schema: PASS (0 error(s))) (1.7 s)
tlf shells PASS: out/tlf/shells: 12 shell(s) from the structured SAP (T14_1_1, T14_1_2, T14_2_1, T14_3_1, T14_3_2, T14_4_1, T14_5_1, T14_5_2, T14_5_3, T14_6_1, T14_6_2, T14_7_1) (0.0 s)
tlf qc-spec PASS: out/tlf/qc-spec: 12 QC specification(s) from the structured SAP (0.0 s)
3 The programs (the programmer)
adam programs PASS: out/adam/programs (7 programs: ADSL -> ADAE -> ADQSADAS -> ADQSCIBI -> ADVS -> ADLBC -> ADLBH) (0.0 s)
tlf programs PASS: out/tlf/programs (12 programs, RESULT: CLEAN) (0.2 s)
6 s
SAPLING BUILD PASS
The whole output (23 lines)
Terminal
$ sapling build
1 The SAP (the statistician)
sap.qmd: 1 study, 27 grouping, 22 decision, 1 design, 1 sample_size, 4 population, 12 output, 33 analysis, 15 method, 1 estimand, 19 subset, 1 missing_data, 3 waiver, 1 multiplicity, 1 sensitivity, 1 software, 90 adam, 1 change; 0 error(s), 1 warning(s).
sap structured PASS: out/sap/sap.md, sap.html (234 blocks) (0.1 s)
sap json PASS: out/sap/sap.json (0.0 s)
sap pdf PASS: out/sap/sap.pdf (Quarto, Typst; the extension _extensions/sapling) (3.7 s)
2 The specifications (the statistician and the programmer)
adam-spec.qmd: made from the SAP (yours to edit)
adam spec PASS: adam-spec.qmd, out/adam/spec (7 data sets, define.md) (0.1 s)
tlf-spec.qmd: made from the SAP (yours to edit)
the chain's checker (sap_build.py): SAP BUILD PASS
note: method ANCOVA_4_2 is named in the prose and used by no analysis: nothing is made of it (the ANCOVA has no model yet (dose, covariates, factors): the statistician completes it)
note: method ANCOVA_4_3_3 is named in the prose and used by no analysis: nothing is made of it (the ANCOVA has no model yet (dose, covariates, factors): the statistician completes it)
note: method CMH_4_3_3 is named in the prose and used by no analysis: nothing is made of it (no engine computes cmh)
note: method ANCOVA_4_5 is named in the prose and used by no analysis: nothing is made of it (the ANCOVA has no model yet (dose, covariates, factors): the statistician completes it)
tlf spec PASS: tlf-spec.qmd, out/tlf/spec (the contract; ARS JSON Schema: PASS (0 error(s))) (1.7 s)
tlf shells PASS: out/tlf/shells: 12 shell(s) from the structured SAP (T14_1_1, T14_1_2, T14_2_1, T14_3_1, T14_3_2, T14_4_1, T14_5_1, T14_5_2, T14_5_3, T14_6_1, T14_6_2, T14_7_1) (0.0 s)
tlf qc-spec PASS: out/tlf/qc-spec: 12 QC specification(s) from the structured SAP (0.0 s)
3 The programs (the programmer)
adam programs PASS: out/adam/programs (7 programs: ADSL -> ADAE -> ADQSADAS -> ADQSCIBI -> ADVS -> ADLBC -> ADLBH) (0.0 s)
tlf programs PASS: out/tlf/programs (12 programs, RESULT: CLEAN) (0.2 s)
6 s
SAPLING BUILD PASS

Each line says PASS or FAIL. Nothing runs in R yet. Read it part by part:

  • The SAP: 234 blocks in the structured SAP, and the PDF made with Quarto and Typst.
  • The specifications: the ADaM specification with 7 data sets, the TLF specification checked against the JSON schema of CDISC ARS (the Analysis Results Standard), 12 shells, 12 QC specifications.
  • The programs: 7 ADaM programs in their order, ADSL first, and 12 table programs.

The full output also has four notes: methods that the prose of the SAP names, such as an ANCOVA of section 4.2, but that no analysis uses yet. Sapling makes nothing of them and says so. A method without a model is not guessed.

The first page of the SAP PDF: the title Statistical Analysis Plan, the subtitle Safety and Efficacy of the Xanomeline Transdermal Therapeutic System in Patients with Mild to Moderate Alzheimer's Disease, the date, and the table of contents with sections 1 to 6.
The SAP as a PDF: the title page and the contents. Every block of sap.qmd is a section or a box of this document, with its protocol source.Source: out/sap/sap.pdf, page 1 (sapling build)

adam-spec.qmd is the programmer’s file. It says how each variable is derived, one command per variable, in the order the programs make them. Here are the population flags of ADSL:

adam-spec.qmd
### Analysis populations []{.cite source="protocol:4.1" words="In general, all patients will"}
::: {.flag variable="ADSL.ITTFL" condition="ARMCD is not missing" label="Intent-To-Treat Population Flag"}
:::
::: {.flag variable="ADSL.SAFFL" condition='ITTFL = "Y" and TRTSDT is not missing' label="Safety Population Flag"}
:::
::: {.flag variable="ADSL.EFFFL"
condition="SAFFL = \"Y\" and any QS(QSCAT = \"ALZHEIMER'S DISEASE ASSESSMENT SCALE\" and VISITNUM > 3) and any QS(QSCAT = \"CLINICIAN'S INTERVIEW-BASED IMPRESSION OF CHANGE (CIBIC+)\" and VISITNUM > 3)"
label="Efficacy Population Flag"}
:::
::: {.derive variable="ADSL.VIS24DT" rule="date(SVSTDTC)" from="SV" where='VISIT = "WEEK 24"' work="true"}
:::
::: {.flag variable="ADSL.COMP24FL" condition="VIS24DT is not missing" label="Completers of Week 24 Population Flag"}
:::
Flag Population Rule
ITTFL intent-to-treat the patient has an arm: randomized
SAFFL safety randomized and has a first dose date
EFFFL efficacy in the safety population, with an ADAS-Cog record and a CIBIC+ record after visit 3
COMP24FL completers of week 24 has a week 24 visit

The heading cites the protocol sentence of section 4.1, as every block of the SAP does.

The ADaM specification as a page in the Sapling editor: the title, the study, a filter, and the ADSL table of variables with their labels, types, lengths, rules and their state against the SAP.
The ADaM specification as a page in the editor, each variable with its rule and its state against the SAP. The study here is a made-up hypertension study.Source: the Sapling manual (sapling-sap.pages.dev)

Your turn 11.1 The dose as a number

Open adam-spec.qmd in the editor and find the rule of ADSL.TRT01PN. Which values does it give, and where does the SAP use them?

Show the answer
adam-spec.qmd
::: {.derive variable="ADSL.TRT01PN" rule='0 if ARMCD = "Pbo"; 54 if ARMCD = "Xan_Lo"; 81 if ARMCD = "Xan_Hi"' label="Planned Treatment for Period 01 (N)" type="N" length="8"}
:::

Placebo is 0, the low dose 54, the high dose 81 (mg of xanomeline). The primary ANCOVA of chapter 7 uses the dose as a number (TRTPN): its coefficient τ tests a linear dose response, the hypothesis H1 of the multiplicity block.

What you learned

  • The SAP says what; the specifications say how; the programs are made from both and never edited by hand.
  • sapling build makes the three parts in order: the SAP, the specifications, the programs.
  • The population flags of ADSL carry the populations of the SAP into the data.

Next: 12 · The ADaM data in R →

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.