A first draft from the protocol
In this chapter
- Make a study folder from the protocol (USDM) and the SDTM data with one command.
- Read a block of the SAP and the protocol sentence it cites.
- Read the five passes of the compiler, and tell a warning from an error.
- List what the protocol leaves open for you.
- Time
- 25 minutes
- At the end you have
- the study folder pilot: sap.qmd with 12 tables, every block citing the protocol, 0 errors, 4 warnings and 22 open decisions.
4.1 The idea: a SAP grows out of the protocol
Section titled “4.1 The idea: a SAP grows out of the protocol”ICH E9 describes the SAP as a more technical and detailed elaboration of the principal features of the analysis in the protocol ICH E9 5.1. So a SAP does not start from a blank page. It starts from the protocol: its objectives, its endpoints, its arms, its visits and its estimands.
Sapling reads the protocol as USDM, the structured protocol of CDISC, and the metadata of the SDTM data. It writes a first draft of the SAP in which every block cites the protocol sentence it rests on. A block is one decision of the plan: a population, an estimand, a table, a test.
Two kinds of content come into the draft:
- What the protocol says. Each such block cites its sentence. The compiler finds the cited words in the protocol, word for word; if they are not there, the plan does not compile.
- What the protocol leaves open. Here the draft does not guess. It writes a decision: a question for you, with the protocol sentence that leaves it open.
Sapling also writes the conventional blocks of a study like this one: the populations, the visit windows, the baseline, the derivations and the standard tables. Sapling calls them the omakase defaults (the chef’s choice). Each one is marked as a default, in the open, for you to keep, change or remove.
4.2 Make the study
Section titled “4.2 Make the study”In the terminal of the lab:
$ sapling new pilot --protocol protocol/usdm.json --sdtm data/sdtm --no-opencreate protocol/usdm.jsoncreate sdtm/ (13 SDTM data sets linked from ../data/sdtm; sdtm.json: their metadata)create protocol/protocol.json (the page index of the protocol)create sap.qmd (964 lines: sapc init and the omakase defaults; 12 tables: 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)create README.md, AGENTS.md (the rules of an AI agent), .gitignore, custom/, out/, .sapling/, _extensions/sapling/ (the Quarto extension of Sapling: sapling sap pdf, Quarto preview)create .Rprofile and .sapling/ (the R engine ~/.vscode-remote/extensions/datastep-labs.sapling-sap-0.16.2/sapling/engine, in place)check 0 error(s), 4 warning(s): SAPLING CHECK PASS2.3 s. Next: cd pilot && sapling build (open decisions: sapling decide)What to look at:
sap.qmdis the plan: 964 lines of Markdown (Quarto) with the blocks of a SAP and 12 tables.sdtm/links the 13 SDTM data sets;sdtm.jsonholds their metadata. The draft uses the metadata to name real variables: a population isADSL.EFFFL, not a description in words.AGENTS.mdholds the rules of an AI agent in this folder. Chapter 6 reads it.- The last line already ran the compiler: 0 errors, 4 warnings.
4.3 What a block looks like
Section titled “4.3 What a block looks like”Open sap.qmd in the editor. The plan starts with its settings: the study, the protocol, the treatment groups, the
visits. Each setting cites its source in the protocol.
---title: Statistical Analysis Plansubtitle: Safety and Efficacy of the Xanomeline Transdermal Therapeutic System (TTS) in Patients with Mild to Moderate Alzheimer's Diseasedate: 2026-11-20toc: truesapling: study: PILOT version: 0.1 (first draft from the protocol) protocol: file: protocol/protocol.json name: Protocol H2Q-MC-LZZT, version 2, amendment 1; registered as NCT12345678 usdm: protocol/usdm.json sdtm: sdtm/sdtm.json status: DRAFT drafted-by: sapling new (omakase) alpha-level: level: 0.05 sided: 2 cite: source: usdm:objectives words: To determine if there is treatments: groups: [Placebo, Xanomeline Low Dose, Xanomeline High Dose] variable: ADSL.TRT01A reference: Placebo cite: usdm:arms visits: visits: [Baseline, Week 2, Week 4, Week 6, Week 8, Week 12, Week 16, Week 20, Week 24, Week 26] cite: usdm:encountersfilters: [sapling]---cite: usdm:arms says: the treatment groups come from the arms of the USDM protocol. A block in the body cites a
sentence with its section and its words, for example
[]{.cite source="protocol:4.3.2" words="the last measurement obtained postrandomization"}. Chapter 7 writes such a
block.
4.4 The five passes of the compiler
Section titled “4.4 The five passes of the compiler”sapling check runs five passes over the plan:
| Pass | It checks |
|---|---|
| 1 syntax | the Markdown of each block |
| 2 structure | each block has what its kind needs, and each id is used once |
| 3 data | each variable exists in the data (SDTM, and the ADaM the plan derives) |
| 4 knowledge | the rules of the guidelines: ICH E9, E9(R1), EMA, FDA, the Gamble checklist |
| 5 chain | the plan can be made into specifications and programs |
$ sapling checkpass 1 syntax 0 error(s) 0 warning(s) PASSpass 2 structure 0 error(s) 1 warning(s) WARN sap.qmd:589:22: warning[software]: SAS has no version.... fix: write `::: {.software name="SAS" version="..."}`: the results depend on itpass 3 data 0 error(s) 0 warning(s) PASSpass 4 knowledge 0 error(s) 3 warning(s) WARN sap.qmd:332:1: warning[gamble.17]: the protocol names 2 primary endpoints (ADAS-Cog (11); CIBIC+), and the plan has no multiplicity strategy.... source: Gamble et al. 2017, Table, item 17; ICH E9 5.6; FDA Multiple Endpoints in Clinical Trials 2022 I sap.qmd:381:1: warning[gamble.28]: the primary analysis T14_3_1_CHG (Change from baseline to Week 24) does not say how it handles missing data, or under which assumption.... source: Gamble et al. 2017, Table, item 28; NRC report on missing data 2010, Recommendation 10; EMA missing data guideline 2010 6 sap.qmd:381:1: warning[missing.single-imputation]: the primary analysis T14_3_1_CHG (Change from baseline to Week 24) uses single imputation: its records keep the LOCF rows of ADQSADAS (no condition on ADQSADAS.DTYPE); the plan gives no justification.... source: NRC report on missing data 2010, Recommendation 10; EMA missing data guideline 2010 6.3.1pass 5 chain 0 error(s) 0 warning(s) PASS0 error(s), 4 warning(s)SAPLING CHECK PASSThe whole output (27 lines)
$ sapling checkpass 1 syntax 0 error(s) 0 warning(s) PASSpass 2 structure 0 error(s) 1 warning(s) WARN sap.qmd:589:22: warning[software]: SAS has no version. 589 | ::: {.software name="SAS"} | ^^^ fix: write `::: {.software name="SAS" version="..."}`: the results depend on itpass 3 data 0 error(s) 0 warning(s) PASSpass 4 knowledge 0 error(s) 3 warning(s) WARN sap.qmd:332:1: warning[gamble.17]: the protocol names 2 primary endpoints (ADAS-Cog (11); CIBIC+), and the plan has no multiplicity strategy. 332 | ::: {.estimand #EST1 level="primary" population="EFF" analysis="T14_3_1_CHG"} | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ fix: `::: {.multiplicity #MULT procedure="hierarchy"}` with the title "Control of the type I error" in bold, then `[...]{.hypothesis #H1 analysis="T14_3_1_CHG"}` `[...]{.hypothesis #H2 analysis="<analysis>"}`, then `:::` (or procedure=co-primary, graphical, holm; procedure=none with the reason when the protocol plans no adjustment) source: Gamble et al. 2017, Table, item 17; ICH E9 5.6; FDA Multiple Endpoints in Clinical Trials 2022 I sap.qmd:381:1: warning[gamble.28]: the primary analysis T14_3_1_CHG (Change from baseline to Week 24) does not say how it handles missing data, or under which assumption. 381 | :::: {.analysis #T14_3_1_CHG} | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ fix: write `::: {.missingdata #MD_T14_3_1_CHG analysis="T14_3_1_CHG" assumption="MAR" handling="..."}` with the justification "why this handling fits the estimand" in its body and `[]{.cite source="..."}` after it source: Gamble et al. 2017, Table, item 28; NRC report on missing data 2010, Recommendation 10; EMA missing data guideline 2010 6 sap.qmd:381:1: warning[missing.single-imputation]: the primary analysis T14_3_1_CHG (Change from baseline to Week 24) uses single imputation: its records keep the LOCF rows of ADQSADAS (no condition on ADQSADAS.DTYPE); the plan gives no justification. 381 | :::: {.analysis #T14_3_1_CHG} | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ fix: write `::: {.missingdata #MD_T14_3_1_CHG analysis="T14_3_1_CHG" assumption="..." handling="locf"}` with the justification "why it is acceptable for this estimand" in its body, and a sensitivity analysis under MNAR (`::: {.sensitivity #ID method="tipping-point"}` with the title in bold) source: NRC report on missing data 2010, Recommendation 10; EMA missing data guideline 2010 6.3.1pass 5 chain 0 error(s) 0 warning(s) PASS0 error(s), 4 warning(s)SAPLING CHECK PASSAn error stops the plan: it does not compile. A warning is a real gap that you or the agent must answer. Each
warning has a fix: line with the Markdown to write, and a source: line with the guideline behind it. The four
warnings of the draft:
- The software has no version. The results depend on it.
- Two primary endpoints and no multiplicity strategy (Gamble item 17). The protocol names ADAS-Cog (11) and CIBIC+. Chapter 7 explains why this matters for the type I error.
- The primary analysis does not say how it handles missing data (Gamble item 28).
- The primary analysis uses single imputation (LOCF) without a justification EMA 2010 6.3.1. Chapter 7 explains what LOCF assumes.
4.5 What the protocol leaves open
Section titled “4.5 What the protocol leaves open”$ sapling decide 1 sap.qmd:47 Name the roles and the persons: who writes this SAP, the senior statistician who reviews it, and the chief investigator or sponsor who approves it (Gamble et al. 2017, items 5 and 6). 2 sap.qmd:95 State the allocation ratio of the 3 groups (the allocation option of the design): the protocol does not give it, and the framework of the comparison (superiority, non-inferiority with its margin, or equivalence). 3 sap.qmd:103 State how the patients are randomized: the method, the block size, and the stratification factors. A stratification factor becomes a term of the primary model. 4 sap.qmd:117 Give the assumptions of the sample size from the protocol (power, alpha, sidedness, the effect, its standard deviation, the dropout) as options of the sample size block, so that the compiler recomputes the number.... 8 sap.qmd:162 The protocol asks for one-sided tests of efficacy. State the sidedness and the level of each test, and which p-values the tables show. 9 sap.qmd:170 State the family of hypotheses that control the type I error and the procedure (a multiplicity block: hierarchy, graphical, Bonferroni, Holm or co-primary). 10 sap.qmd:178 State the level of the confidence intervals (for example 95%, two-sided) and the effects that are reported with one.... 16 sap.qmd:342 Complete the estimand EST1: confirm its population (ITT; the study definition says "Patients with Mild to Moderate Alzheimer’s Disease."); the other intercurrent events (for example permanent discontinuation of the treatment) with their strategies; the population-level summary and the analysis that estimates it ([analysis=]).... 18 sap.qmd:425 State how missing data are handled in the primary analysis (the assumption and the method), and why it is acceptable. 19 sap.qmd:436 Plan the sensitivity analyses of each primary estimand under other assumptions on the missing data, and the supplementary analyses....22 open decision(s). A person answers: sapling decide <n> "<answer>" --by "<your name>"The whole output (24 lines)
$ sapling decide 1 sap.qmd:47 Name the roles and the persons: who writes this SAP, the senior statistician who reviews it, and the chief investigator or sponsor who approves it (Gamble et al. 2017, items 5 and 6). 2 sap.qmd:95 State the allocation ratio of the 3 groups (the allocation option of the design): the protocol does not give it, and the framework of the comparison (superiority, non-inferiority with its margin, or equivalence). 3 sap.qmd:103 State how the patients are randomized: the method, the block size, and the stratification factors. A stratification factor becomes a term of the primary model. 4 sap.qmd:117 Give the assumptions of the sample size from the protocol (power, alpha, sidedness, the effect, its standard deviation, the dropout) as options of the sample size block, so that the compiler recomputes the number. 5 sap.qmd:125 The protocol plans the analyses of section 4.6 (Interim Efficacy Analyses). For each look, state its timing, its purpose, whether a futility rule binds, the alpha spending and the committee (an interim block each). 6 sap.qmd:131 The protocol plans the analyses of section 4.7 (Interim Safety Analyses). For each look, state its timing, its purpose, whether a futility rule binds, the alpha spending and the committee (an interim block each). 7 sap.qmd:139 State when the final analysis is done: after the last patient completes the study, the database is locked and the treatment codes are released. 8 sap.qmd:162 The protocol asks for one-sided tests of efficacy. State the sidedness and the level of each test, and which p-values the tables show. 9 sap.qmd:170 State the family of hypotheses that control the type I error and the procedure (a multiplicity block: hierarchy, graphical, Bonferroni, Holm or co-primary). 10 sap.qmd:178 State the level of the confidence intervals (for example 95%, two-sided) and the effects that are reported with one. 11 sap.qmd:186 Define adherence to the treatment and the protocol deviations, and how they are summarized. 12 sap.qmd:221 Review the omakase defaults of this plan (each block marked "default: omakase"): the populations, the visit windows, the baseline, the derivations of the analysis data sets and the standard tables are conventions, not choices of the protocol. Keep, change or remove each. 13 sap.qmd:308 The protocol leaves the endpoint of this objective to be determined: "To assess the dose-dependent improvements in activities of daily living. Improved scores on the Disability Assessment for Dementia (DAD) will indicate improveme...". Define the endpoint, its time point and its analysis, or say that it is not analysed. 14 sap.qmd:315 The protocol leaves the endpoint of this objective to be determined: "To assess the dose-dependent improvements in an extended assessment of cognition that integrates attention/concentration tasks. The Alzheimer's Disease Assessme...". Define the endpoint, its time point and its analysis, or say that it is not analysed. 15 sap.qmd:322 The protocol leaves the endpoint of this objective to be determined: "To assess the treatment response as a function of Apo E genotype.". Define the endpoint, its time point and its analysis, or say that it is not analysed. 16 sap.qmd:342 Complete the estimand EST1: confirm its population (ITT; the study definition says "Patients with Mild to Moderate Alzheimer’s Disease."); the other intercurrent events (for example permanent discontinuation of the treatment) with their strategies; the population-level summary and the analysis that estimates it ([analysis=]). 17 sap.qmd:360 State how the assumptions of the models are checked, and the alternative analysis when they fail. 18 sap.qmd:425 State how missing data are handled in the primary analysis (the assumption and the method), and why it is acceptable. 19 sap.qmd:436 Plan the sensitivity analyses of each primary estimand under other assumptions on the missing data, and the supplementary analyses. 20 sap.qmd:442 List the subgroup analyses: the subgroups, the model with the interaction, and how the results are presented. 21 sap.qmd:593 State the software and the version of every analysis and the version of the dictionaries (MedDRA, WHODrug). 22 sap.qmd:960 Give the references of the methods that are not standard.22 open decision(s). A person answers: sapling decide <n> "<answer>" --by "<your name>"Each line is a place where the protocol does not say what the SAP must say: the roles, the allocation ratio, the randomization, the sidedness of the tests, the level of the confidence intervals. Look at decision 8: the protocol asks for one-sided tests of efficacy, but the plan’s level of significance is 0.05 two-sided. A SAP must settle such a difference, and only you can.

Your turn 4.1 Is this the right sentence?
Run sapling show EFF. Which protocol sentence does the efficacy population cite? Does that sentence say who is in the
efficacy population?
Show the answer
$ sapling show EFFpopulation EFF sap.qmd:205 not judged
| ::: {.population #EFF condition="ADSL.EFFFL" | definition="Randomized and dosed subjects with a value of each primary endpoint after baseline"} | Efficacy population | ::: | []{.cite source="protocol:3.10.2" words="All patients who are enrolled"}
the protocol (3.10.2): "All patients who are enrolled in the study will be included in the efficacy analysis and the safety analysis."
ok [grounded] population EFF rests on protocol 3.10.2 OPEN [agreed] population EFF: not judged yet how: the statistician reads it (sapling show EFF), then: sapling agree EFF --by NAME, or sapling revise EFF "..." --by NAMEIt cites section 3.10.2: All patients who are enrolled in the study will be included in the efficacy analysis and the
safety analysis. The words are in the protocol, so the citation compiles. But the sentence does not define the
population. Section 4.1 does: patients are in the analyses of efficacy if they have a baseline measurement and at
least one postrandomization measurement. You see that sentence in chapter 13, where sapling find traces the flag
ADSL.EFFFL:
$ sapling find ADSL.EFFFL --kind adamadam:ADSL.EFFFL Efficacy Population Flag [sap.qmd section 7.1.2 (Analysis populations)] type: text length: 1 origin: Derived codelist: YN protocol: 4.1: In general, all patients will be included in all analyses of efficacy if they have a baseline measurement and at least one postrandomization measurement. Y if 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), N otherwise is in (adam.dataset): adam:ADSL...The compiler checks that the cited words exist. It does not check that they are the best sentence. That is your
judgment: in chapter 9 you learn to ask the agent for a change with sapling revise.
What you learned
sapling newmakes a first draft of the SAP from the protocol (USDM) and the SDTM metadata.- Every block cites its protocol sentence, and the compiler finds the cited words in the protocol.
- The compiler runs five passes. An error stops the plan; a warning is a gap with its fix and its guideline.
- What the protocol leaves open is a decision, and every decision is yours.
Next: 5 · The scorecard →
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.