The plan language

This page is the repository's own document docs/markdown.md, shown as it is, so that it never drifts from the product.

A statistical analysis plan (SAP) in Sapling is a Quarto Markdown file (sap.qmd). Quarto and Pandoc read it as ordinary Markdown: front matter in YAML, headings, fenced divs, bracketed spans, $...$ math and HTML comments. About thirty kinds of block give the plan its meaning: a population, a test, a table, a model, an estimand, a citation of the protocol. There are no LaTeX commands in a plan (only the LaTeX math inside $...$ and $$...$$, as Markdown has it).

This page is the reference of the language: how each block is written, what it means, what the compiler checks, and what it makes. To start, read the one page quickstart.md: from a protocol PDF to a first checked part. The same file goes two ways:

The compiler reads a plan (a .qmd or .md file) with the Markdown reader src/qmd.ts. The messages of the compiler name the blocks in their Markdown form: a fix shows the Markdown to write.

Contents. Write: Ask the agent · A small plan · The rules of the form · The front matter · Sections · Blocks: fenced divs · Parts and inline commands: spans · Attributes · Citations · Prose · Models · Comments · Macros · What the reader also accepts · The exceptions. Meaning: Values and conditions · The settings · Citations: the protocol is the source · Populations, subsets, groupings · Tests and statistics · Tables and analyses · Models: a formula or an equation · Estimands · Decisions · The plan around the analyses · Adverse event tables · The options of a model · The review and waivers · The SAP library · The kinds of blocks · What the compiler checks · The ADaM from the SAP · Start a plan · The machine view · Reference card. Tools: Pandoc and Quarto · A study folder · The Quarto extension · All commands

You never need to remember the syntax: ask the agent#

Say what you want in your own words. The agent writes the block, compiles, and shows you the sentence and the table. These ten blocks are 90% of a SAP:

And for the rest of a SAP, which the review asks for (sapc review):

The agent never writes approved: in the front matter, status: APPROVED, or by= and on= on a decision: only you approve a plan or decide an open decision.

A small plan#

---
title: Statistical Analysis Plan
date: 11 November 2026
toc: true
sapling:
  study: CDISCPILOT01
  version: 0.1 (draft)
  protocol:
    file: protocol/protocol.json
    name: Protocol H2Q-MC-LZZT(c)
  usdm: protocol/CDISC_Pilot_Study_v4.json
  adam: adam
  status: DRAFT
  drafted-by: agent
  alpha-level:
    level: 0.05
    sided: 2
    cite:
      source: usdm:objectives
      words: To determine if ... erroralpha=0.05)
  treatments:
    groups: [Placebo, Xanomeline Low Dose, Xanomeline High Dose]
    variable: ADSL.TRT01A
    cite: usdm:arms
---

<!-- drafted by: agent (docs/markdown.md); the statistician reviews it -->
# Analysis populations []{.cite source="protocol:4.1"}

::: {.population #EFF condition="ADSL.EFFFL" definition="Patients with a baseline and at least one postrandomization measurement"}
Efficacy population
:::

# The primary estimand

::: {.estimand #EST1 level="primary" population="EFF" analysis="P_ADAS"}
**Group mean changes from baseline in the primary efficacy parameters**

[Xanomeline TTS at the low dose (54 mg) or the high dose (81 mg), or placebo, once daily for 24 weeks]{.treatment}
[Change from baseline to Week 24 in the ADAS-Cog (11) total score]{.endpoint}
[Temporary treatment interruption]{.intercurrent strategy="treatment policy"}
[]{.cite source="usdm:estimands" words="Estimand EST1 ... regardless of interruption."}
:::

# Efficacy []{.cite source="protocol:4.3.3" words="Effects in the ANCOVA model"}

The change from baseline is analysed by analysis of covariance with the baseline score, the pooled site and the dose
$d_i \in \{0, 54, 81\}$ as effects ([ADQSADAS.CHG]{.var}).

::::: {.tlf #P_EFF population="EFF"}
**Primary Endpoint Analysis: ADAS-Cog (11), Change from Baseline to Week 24**

:::: {.analysis #P_ADAS}
**ADAS-Cog (11), change from baseline to Week 24**

[]{.data dataset="ADQSADAS" records='PARAMCD = "ACTOT" and AVISIT = "Week 24" and ANL01FL = "Y"'}

::: {.model}
$$
Y_{i} = \mu + \beta\,\mathrm{BASE}_{i} + \gamma_{s(i)} + \tau\, d_{i} + \varepsilon_{i}
$$
[]{.where bindings="Y = CHG, s = SITEGR1, d = TRTPN"}
:::
::::
^[The test for linear dose response: the treatment as a number (0, 54, 81 mg).]
:::::

::: {.decision}
The protocol's investigator effect is the pooled site SITEGR1 of the ADaM data. The statistician confirms
that its pooling is this rule.
:::
[]{.cite source="protocol:4.3.3" words="For all ANOVA and ANCOVA models"}

The plans of the repository are in examples/: examples/cdiscpilot01/pilot.qmd (the CDISC pilot study), pilot-full.qmd (every analysis of its study report), pilot-adam.qmd (the ADaM from the SAP), examples/customize/ (the programmer's hooks) and examples/errors/typos.qmd (the mistakes people make).

The rules#

One rule for each role of a command (src/commands.ts); the forms are in src/qmd_forms.ts:

The arguments of a command. The argument named id is the identifier #ID. The prose argument (an argument a person reads as words: title, name, text, task, reason, justification, what, event) is the body of the div or the content of the span. Every other argument and every option is an attribute with its name in src/commands.ts. name as the first argument names the block (dataset, software): it is an attribute (name="ADSL").

Two prose parts in one div. An environment has a title and a body; change has two prose arguments. Then the first is the first paragraph of the div, all in bold (**...**), and the second follows:

::: {.change}
**What the SAP does differently**

Why it does so.
:::

The front matter#

---
title: Statistical Analysis Plan        # Quarto's keys: title, subtitle, date, author
toc: true                               # the table of contents
sapling:                                # every other setting
  study: CDISCPILOT01                   # one argument, no option: a scalar
  protocol:                             # options or more arguments: a map with the names of commands.ts
    file: protocol/protocol.json
    name: Protocol H2Q-MC-LZZT(c)
  alpha-level: {level: 0.05, sided: 2}  # a flow map is the same
  treatments:
    groups: [Placebo, Xanomeline Low Dose, Xanomeline High Dose]   # a Sapling list (a; b; c) is a YAML list
    variable: ADSL.TRT01A
    cite: usdm:arms                     # the citation of the setting: a source ...
  visits:
    visits: [Baseline, Week 2, Week 4]
    cite: {source: "usdm:encounters", words: "the words of the sentence"}   # ... or a source and its words
---

• A setting with one argument and no option is a scalar. With options, more arguments or a citation it is a map whose keys are the names of its arguments and options. A setting written more than once (approved, one per role) is a list of maps.
• The keys of two settings are in kebab case: drafted-by and alpha-level.
• toc: true gives the table of contents. Quarto shows the title block when there is a title:. Other keys of Quarto (format:, lang:, number-sections:, ...) are Quarto's: the compiler does not read them.
• The reader reads a subset of YAML: block maps and lists by indentation, plain, single-quoted and double-quoted values, flow maps {a: b} and flow lists [a, b], comments. It does not read anchors, tags or block scalars (|, >): an error says so, at the line and column. A value with : or #, or one that starts with a character YAML reserves, goes in quotes; the writer uses single quotes, in which a backslash is a backslash.

Sections#

# Introduction []{.cite source="protocol:3.1"}
## Demographics []{.cite source="protocol:4.2" words="The groups will be compared"}
#### Vital signs
# Unnumbered section {.unnumbered}
# Table shells {.appendix}

The citation of a section is a cite span at the end of its heading line. {.unnumbered} (or {-}) makes a heading without a number. A level-1 heading with {.appendix} starts the appendix: its sections are numbered A, B, ...; the writer puts {.appendix} on every section of the appendix, as Quarto expects.

Blocks: fenced divs#

::: {.population #ENR condition="ADSL.ITTFL" definition="All patients enrolled (randomized) in the study"}
All enrolled patients
:::
[]{.cite source="protocol:3.10.2"}

::: {.software name="R" version="4.4.1"}
:::

• A div opens with three or more colons and its attributes, and closes with a line of colons only. A closing line closes the innermost open div (Pandoc's rule). The writer gives an outer div more colons (::::, :::::) so that the eye sees the nesting.
• A block without a prose argument has an empty div.
• Pandoc needs an empty line between a paragraph and a div (or a heading) after it. Without it Pandoc reads the fence as text; the reader of Sapling reports an error at that line (a div needs an empty line before it) and reads the div.

Parts and inline commands: spans#

[Discontinuation of study drug]{.intercurrent strategy="treatment policy" reason="the patient stops the patch"}
[]{.data dataset="ADQSADAS" records='PARAMCD = "ACTOT" and AVISIT = "Week 24"'}
[]{.formula formula="CHG ~ BASE + SITEGR1 + TRTPN" covariance="us"}
[Word Recall Task]{.param paramcd="ACITM01" n="1"}
The groups are compared by [anova]{.test} and [ADSL.AGE]{.var} is described in table [P_DEMOG]{.ref}.

• A part is a span on a line of its own. Its content is its prose argument, or empty.
• An inline command is a span in the text. Its content is its prose argument, or else its first argument ([ADSL.AGE]{.var}, [P_DEMOG]{.ref}, [anova]{.test}).
• Parts on lines that follow each other make one Markdown paragraph; the compiler reads each part on its own.

Attributes#

• key="value", always in quotes in the plans the writer makes. A value with a double quote is written in single quotes (records='PARAMCD = "ACTOT"'); a value with both is in double quotes with \".
• A value is the text as written: a list is separated by ; (fallback="toeph; ar1h"), a flag is "true" (total="true").
• #ID is the argument id; when a command has no argument id and has an option id (test, a model), #ID is the option. id="ID" is the same as #ID (Pandoc's rule).
• The attributes may go over more lines inside the braces (no empty line), of a div and of a span alike. The writers (sapling new, sapling generate, the skeleton; the assistant is asked to) put a head longer than 120 characters over more lines: the next lines of a div's attributes at four spaces, of a span's at two:

[]{.formula formula="CHG ~ BASE + SITEGR1 + TRTP*AVISIT + BASE*AVISIT" covariance="us" fallback="toeph; ar1"
  df="kenward-roger" estimation="reml" visit="Week 24"
  stats="LS mean (SE) = xx.x (xx.xx); Diff (SE) = xx.x (xx.xx); 95% CI = (xx.x, xx.x); p-value = x.xxx"}

• Some values of the example plans have a backslash before % or _ (timing="approximately 50\% of the patients"): the compiler keeps a value as it is written. In a new plan, write % and _ as they are.

Citations#

[]{.cite source="protocol:4.2" words="the words of the sentence"}, []{.cite source="protocol:4.1" sentence="3"}, []{.cite source="usdm:arms"}. The span is empty: the words find the sentence in the protocol, they are not text of the plan. (Quarto shows the content of a span: words in the content would show in the sentence, in a heading, in the anchor of the heading and in the table of contents.) The reader also takes the words as the content, [the words]{.cite source="protocol:4.2"}: the citation is the same.

A citation belongs to what comes before it, by the order of the blocks:

An empty line between a block and a citation makes the citation a paragraph of its own (the paragraph's).

Prose#

The text of a plan is Markdown:

Models#

::: {.model contrast="pairwise"}
$$
Y_{i} = \mu + \beta\,\mathrm{BASE}_{i} + \gamma_{s(i)} + \tau_{k(i)} + \varepsilon_{i}
$$
[]{.where bindings="Y = CHG, s = SITEGR1, k = TRTP"}
:::

The equation is the display math of the div, as written; the where and formula spans come after it. A model as a formula only is a span in the analysis: []{.formula formula="CHG ~ BASE + SITEGR1 + TRTPN" df="kenward-roger"}.

Comments#

A comment is an HTML comment <!-- ... -->: Quarto does not show it, and the reader of Sapling skips it. A comment that a tool of Sapling reads starts a comment of its own, above the block or paragraph it is about: <!-- drafted by: agent (...) -->, <!-- default: omakase (...) -->, <!-- review (Name, date): text -->, <!-- synced from ... -->. A comment inside the arguments of a command goes above the block; a comment inside a paragraph goes above the paragraph.

Macros#

Markdown has no macros: a family of tables is written out, one tlf div each (or made by sapling generate table).

What the reader also accepts#

The reader does not depend on the layout of the writer:

• attributes in any order, with more blanks, over more lines; values in double quotes, single quotes or without quotes (a value without blanks); id="X" for #X;
• a div with one class and no braces: ::: decision;
• empty lines (or none) between the parts of an environment;
• a block without a prose argument as a span on a line of its own ([]{.derive variable="ADSL.AGEGR1N" rule="..."}), and a prose argument as an attribute (::: {.population #EFF name="Efficacy population" condition="ADSL.EFFFL"});
• the front matter in block or flow YAML; a list as [a, b] or as - a lines;
• a class one letter off a Sapling command (.summarise) is read as that command's typo: the compiler says did you mean. Other classes (.callout-note, .column-margin) are Markdown's own: the reader reads their content.

The exceptions#

The forms that are not the rule of their role:

Values and conditions#

Conditions are written on ADaM variables the way you say them; sapc writes the SAS WHERE text of the chain:

A variable without a data set takes the data set of its analysis (the data span), else ADSL. sapc checks every variable against the ADaM specification (adam: in the front matter), the quotes against the type (text in quotes, numbers without), and every quoted value against the variable's codelist: AVISIT = "WEEK 24" is an error with the fix write AVISIT = "Week 24".

The settings#

The settings of the plan are keys of the front matter, under sapling: (Quarto's own keys title, subtitle, date and author are at the top).

toc: true at the top level gives the table of contents. Quarto shows the title block when there is a title:.

Citations: the protocol is the source#

Every block of the structured SAP has a section and a quote: the protocol's words the decision rests on, word for word; the chain's checker finds each quote in the protocol. You do not copy the quote: you point at it with a citation span, and the compiler copies it.

The section is the protocol's own number (4.3.3 is the page Protocol 4.3.3. of the index) or a name (usdm:arms, protocol:title). When the words are not in the section, the error shows the closest sentences; when they are in two, it shows both. In the PDF, a citation in a paragraph is a footnote with the protocol's words; a citation after a block or a heading is a source line under it.

Where a citation belongs (the forms: Citations):

1. on the line right after the closing ::: of a block: the quote of that block;
2. at the end of a heading line: the default quote of every block of that section (and its subsections);
3. inside a paragraph: a citation of the paragraph, and the quote of the tests ([anova]{.test}) of the paragraph;
4. at the top of the body of a tlf, analysis or estimand: the quote of that block.

A table passes its quote to its analyses, an analysis to its subset and its model. The section of a block in the structured SAP is the section of its quote; the HTML and the JSON also give the section of your SAP.

A protocol PDF whose text is not its words. sapling new --protocol protocol.pdf reads the text layer of the PDF (protocol/protocol.txt). On some PDFs that layer is not the words the page shows, and sapling new says which pages:

When the words of a citation are not in the section, the error shows the nearest sentences (by the words they share, else by their letters), from the place where they share a word.

Populations, subsets, groupings, derivations#

::: {.population #ENR condition="ADSL.ITTFL"}
All enrolled patients
:::
[]{.cite source="protocol:3.10.2"}

::: {.population #EFF condition="ADSL.EFFFL"
    definition="Patients with a baseline and at least one postrandomization measurement"}
Efficacy population
:::
[]{.cite source="protocol:4.1"}

::: {.datasubset #SER condition='ADAE.TRTEMFL = "Y" and ADAE.AESER = "Y"'}
Serious treatment-emergent events
:::

<!-- the groups of the values in the data -->
::: {.grouping #AGEGRP variable="ADSL.AGEGR1"}
Age group
:::

<!-- these groups, in this order -->
::: {.grouping #AGEGRP3 variable="ADSL.AGEGR1" groups="<65; 65-80; >80"}
Age group
:::

::: {.derivation #LOCF variable="ADQSADAS.AVAL" rule="the last observation carried forward"
    condition='ADQSADAS.ANL01FL = "Y"'}
:::

Tests and statistics#

A test is declared once, where the SAP names it, and used by name:

The groups are compared by [anova]{.test} for continuous variables and by [chisq]{.test} for categorical
variables[]{.cite source="protocol:4.2" words="The groups will be compared"}.

The text reads "analysis of variance (ANOVA)" and "Pearson's chi-square test". The structured SAP has two method blocks, ANOVA_4_2 and CHISQ_4_2 (the test and the section of its quote), with the cited sentence as quote and sided, alpha from alpha-level:. An analysis then says test="anova": the test of that kind declared in its section (or test="ANOVA_4_2" by id); if none is declared there, the compiler declares it with the analysis's quote. The attributes of a test span: #ID (or id=), sided=, alpha=, pattern= (default x.xxx), text= (other words in the prose).

Tests: anova, ancova, chisq, fisher, cmh, logrank, ttest, wilcoxon, mmrm, logistic, cox, riskdiff, riskratio, oddsratio, poisson, negbin. Which engine computes each, and what it can report: The methods and what they report.

The statistics of a summary are the rows of the shell, each with its cell picture:

::: {.statistics #CONT_SUMM rows="n = xx; Mean (SD) = xx.x (xx.xx); Median = xx.x; Min, Max = xx, xx"}
:::
::: {.statistics #CAT_SUMM rows="n (%) = xx (xx.x%)"}
:::

::: {.statistics #KM_SUMM rows="n = xx; Events = xx; Median = xx.x; 95% CI = (xx.x, xx.x)" estimator="kaplan-meier"}: the statistics are the estimates of a Kaplan-Meier curve (the median time to the event and its CI), not of the values of the variable. The method block gets estimator: kaplan-meier, and the engine of sapling computes them (ars_e_km: the subjects, the events, the median and its 95% CI by Brookmeyer and Crowley; the censoring of CNSR). conftype= is the transformation of the interval: plain (the default, written into the method: what both engines did before it was an option; R survfit's own default is log, SAS LIFETEST's own log-log), log, log-log. time="24" with the row Survival = xx.x gives the survival at that time in percent and its CI (one block per time; its CI is then of the survival, not of the median). unit= (days, weeks, months, years) says the unit of the time; without it a warning says that the time is read in the unit of the analysis variable, and with it the compiler checks it against the parameter where the plan gives its unit (a time-to-event step of the plan gives AVAL in days; a parameter named "... (Months)"): ::: {.statistics #PFS12 rows="Survival = xx.x; 95% CI = (xx.x, xx.x)" estimator="kaplan-meier" time="12" conftype="log-log"}.

The rendered plan states the options of each method that change a number (the ties of a Cox model, the interval of a proportion, the transformation of a Kaplan-Meier interval, ...): the plan's value, or the registry's default marked "(the default)".

::: {.statistics #RESP rows="n (%) = xx (xx.x%); 95% CI = (xx.x, xx.x)" ci="clopper-pearson"}: the confidence interval of each percent (of the subjects of the column, as the percent), by the method of ci=: clopper-pearson (the default: the exact interval), wilson (the score interval, without continuity correction), wald, agresti-coull (both kept within 0 and 100). The method block gets ci: (the default written when the plan says none), and the engines compute it (ars_e_propci; SAS %proportion, PROC FREQ BINOMIAL).

::: {.statistics #EAIR rows="n = xx; Patient-years = xx.x; Rate = xx.xx; 95% CI = (xx.xx, xx.xx)" exposure="ADSL.TRTDUR / 365.25" per="100"}: the exposure-adjusted incidence rate of each group (as the statistics of an incidence): the subjects with the event, the sum of the exposure of the subjects of the group (exposure=: a variable of ADSL, or a variable divided by a number: days to years), the rate per per= units (default 100: per 100 patient-years) and its exact Poisson interval. The exposure of a group is that of all its subjects, not the time to the first event (ars_e_eair; SAS %rate). count="events" (with the row Events = xx) makes the rate of the events, every record of the group, with the exact Poisson interval of the number of events (method eventrate; SAS %rate(count=events)); a block with a rate and the row Events and no count= is an error (the rate of the subjects or of the events?).

Row labels: n, Mean, SD, Median, Q1, Q3, Min, Max, %, Events, p-value, LS mean, SE, Diff, 95% CI, Estimate, OR, HR, RD (risk difference), RR (relative risk), Rate ratio, Rate, Patient-years, Survival. One pattern per statistic, in order; the parentheses of a percent belong to its pattern ((xx.x%)). Without =, the library's pattern. A p-value that its pattern rounds to 0 or 1 prints as <0.001 or >0.999 (x.xxx; its number is unchanged), and a category of a ::: {.codelist} prints its label (F = Female). summarize, tabulate and incidence use the library's CONT_SUMM, CAT_SUMM, AE_INCID; declare a statistics block with the same id to change the study's decimals, or a new id and stats="ID".

The methods and what they report#

One registry says what each method computes (src/methods.ts): its inputs, its options with their defaults, the rows it can report, the engine that computes it in R (r-agentic) and in SAS (the macro library), what it cannot do, and a small known answer. The compiler reads it: a statistic a method makes is never warned about; a statistic it does not make, an input its engine cannot take (an interaction, strata, a censoring variable other than CNSR) and a test no engine computes are each an error chain-engine at the place of the plan, which says which method can, and the output of that analysis is not made (only that output: sapling build and sapling run make the others). The table below is made from the registry (node tools/methods_doc.ts); test/methods-r.test.ts runs every row of every method through r-agentic's contract maker and R engines on the known answer.

The test words of the plan that no engine computes yet (an analysis that uses one is an error, and its output is not made):

The options and their defaults (what a plan does not say, the engine does as written here):

The known answer of each method (a small data set of 12 subjects, FIXTURE_STUDY of src/methods.ts; the numbers by tools/method_answers.R; test/methods-r.test.ts runs every row through the real contract maker and R engine):

Tables and analyses#

A table of the plan is the block tlf (table, listing or figure). Its analyses are its rows, in order:

:::: {.tlf #P_DEMOG population="ENR" total="true"}
**Demographics and Patient Characteristics Measured at Baseline**

::: {.summarize #P_AGE variable="ADSL.AGE" test="anova"}
Age (years)
:::
::: {.tabulate #P_SEX variable="ADSL.SEX" test="chisq"}
Gender
:::
::: {.tabulate #P_RACE variable="ADSL.RACE" test="chisq"}
Origin
:::
^[The p-values are descriptive: the treatment groups were randomized.]
::::

The footnote ^[...] of a table is a footnote of its shell.

The parts of an analysis: []{.data dataset="DS" records="..."} (the data set, and its records as a subset <id>_REC), []{.variable variable="CHG"}, []{.by groupings="G1; G2"}, []{.stats method="METHOD"}, and the model (a formula span or a model div).

Models: a formula or an equation#

::::: {.tlf #T_MODEL population="EFF"}
**Two forms of one model**

:::: {.analysis #A_FORMULA}
**ADAS-Cog (11), change from baseline to Week 24: the formula (R, Wilkinson)**

[]{.data dataset="ADQSADAS" records='PARAMCD = "ACTOT" and AVISIT = "Week 24" and ANL01FL = "Y"'}
[]{.formula formula="CHG ~ BASE + SITEGR1 + TRTPN"}
::::

:::: {.analysis #A_EQUATION}
**ADAS-Cog (11), change from baseline to Week 24: the equation, with the meaning of its symbols**

[]{.data dataset="ADQSADAS" records='PARAMCD = "ACTOT" and AVISIT = "Week 24" and ANL01FL = "Y"'}

::: {.model}
$$
Y_{i} = \mu + \beta\,\mathrm{BASE}_{i} + \gamma_{s(i)} + \tau\, d_{i} + \varepsilon_{i}
$$
[]{.where bindings="Y = CHG, s = SITEGR1, d = TRTPN"}
:::
::::
:::::

The model div is a numbered equation; the where span binds each symbol to an ADaM variable ($\mathrm{BASE}$ needs no binding). The compiler reads the terms: $\mu$ the intercept; a coefficient times a variable ($\beta\,\mathrm{BASE}_i$, $\tau\, d_i$) a covariate, or the dose when the variable is the treatment; an effect with an index ($\gamma_{s(i)}$, bound by $\gamma$ = ... or s = ...) a class factor; $\varepsilon_i$ the error. A formula span inside the model is checked against the equation. Round trip from the command line: node src/cli.ts math "CHG ~ BASE + SITEGR1 + TRTPN" prints the equation; node src/cli.ts math --tex "<equation>" --where "Y = CHG, d = TRTPN" prints the formula.

The treatment term is the variable of treatments: or its analysis twin (TRTP, TRTPN, TRTA, TRTAN, TRT01P, ...). Numeric (TRTPN: 0, 54, 81): the test for linear dose response, method id <analysis>_DR. Text (TRTP): the overall test of the groups, <analysis>_CMP; contrast="pairwise" asks for the pairwise comparisons. The ANCOVA above compiles to:

id: A_FORMULA_DR
name: "ANCOVA, test for linear dose response"
test: ancova
statistics:
  - {op: pvalue, pattern: "x.xxx"}
model: {dose: ADQSADAS.TRTPN, covariates: [ADQSADAS.BASE], factors: [ADQSADAS.SITEGR1]}
sided: 2
alpha: 0.05
formula: "CHG ~ BASE + SITEGR1 + TRTPN"

Estimands#

::: {.estimand #EST1 level="primary" population="EFF" analysis="P_ADAS"}
**Group mean changes from baseline in the primary efficacy parameters**

[Xanomeline TTS at 54 mg or 81 mg, or placebo, for 24 weeks]{.treatment}
[Change from baseline to Week 24 in the ADAS-Cog (11) total score]{.endpoint}
[Temporary treatment interruption]{.intercurrent strategy="treatment policy"}
[]{.cite source="usdm:estimands" words="Estimand EST1 ... regardless of interruption."}
:::

The five attributes of ICH E9(R1): population=, the treatment span, the endpoint span (the variable), [event]{.intercurrent strategy="..."} (one per event; strategies treatment policy, hypothetical, composite, while on treatment, principal stratum), the summary span (without it, written from the model of analysis=). level= is primary, key secondary, secondary or exploratory; when no estimand says its level, the first estimand is the primary one. The rules e9r1.* check the attributes, the strategy, death under treatment policy, and that a primary estimand names its analysis in its population (rules.md). The structured SAP has an estimand block (the chain does not read it yet; its source is under source_section/source_quote, which the chain's checker does not claim to check).

What the newer SAPs add to an estimand (read from ten public SAPs, 2026-11):

What the SAP adds to the protocol#

The protocol is cited for what the protocol says. What it does not say is either open (a decision) or the statistician's addition: a population the protocol does not define, a crude rate, a rule of the time to event, an interim look an agency asked for. An addition never borrows the nearest protocol sentence: it is named by a change block with what the SAP adds and why, and that change is its source.

::: {.population #MITT condition="ADSL.EFFFL" definition="The randomised patients with a centrally confirmed diagnosis"}
Modified intent-to-treat population
:::

::: {.change #CH_MITT adds="MITT"}
**The SAP adds the MITT population.**

The central confirmation of the diagnosis is the SAP's (SAP 5.2); the protocol names the ITT population only.
:::

• adds= names blocks of any kind: population, datasubset, grouping, derivation, statistics, estimand, tlf, analysis, a plan block (interim, sensitivity, ...). A block inside an added block (the method and records of an added analysis) is added with it. An added block needs no citation (no no-source); the change with adds= needs none either (its reason is the source). A change that alters what the protocol says still cites it. A block named by adds= that also cites the protocol is a warning (addition-cited): one of the two is not true.
• The rendered plan shows each added block as an addition (the row "Added by the SAP" in its box, with its change), and lists every change in one place before the table shells: "Changes from the protocol", with the blocks each adds and its reason. The JSON has changes[]; the review counts the additions (SAPLING REVIEW: ..., 2 addition(s) of the SAP to the protocol) and lists them under "CHANGES FROM THE PROTOCOL".
• In the structured SAP an added block has source: sap and added_by: CH_MITT instead of a protocol quote; the checker of r-agentic (sapling build) takes it. The SAS project's checker (sas-macro-agentic, read only) asks a quote of every block: sapc chain reports the added blocks there.
• Only the statistician writes adds=: the MCP server, the assistant and the editor's agent refuse a change with adds= (src/service.ts guard). An agent proposes the addition in a decision.

Decisions#

::: {.decision}
The protocol's investigator effect is the pooled site SITEGR1. The statistician confirms the pooling rule.
:::
[]{.cite source="protocol:4.3.3" words="For all ANOVA and ANCOVA models"}

An open decision is a todo block with its quote (the chain counts it for the approver). When a person has decided, that person adds answer="...", by="Name" and on="2026-12-01" to the div (sapling decide writes them with the person's name); it becomes a decision block. The compiler never writes by=; an agent never writes it.

A decision cites the protocol sentence that leaves the question open. When the protocol is silent, the decision cites nothing and says so in its text: a decision is the one block that needs no citation (a guessed section would send the reader to the wrong place). The skeleton of sapling new writes "The protocol is silent on it, or its section was not found" in the decision of each part whose section it did not find.

The design plan and the assumptions block#

A design plan is a plan written before the protocol is final: the statistician's design of the statistics (docs/design.md). It is the same language and the same compiler as a SAP. The one difference is kind: design under sapling:: with it the plan has no protocol to cite, and that is said once, as information, instead of a warning. Every other rule applies (a design plan that names a protocol: is checked against it like a SAP). sapling design to-sap makes a SAP from it.

sapling:
  kind: design        # sap (the default) or design
  study: HTN-201

The one new block is the assumptions block: what the simulation needs and what the protocol's sample size section states. A scenario overrides some of its numbers. Every number has a basis= (a publication, an earlier study, an expert, "a guess"); a part without one is warned, because the protocol must justify it.

::: {.assumptions #A_BASE analysis="P_SBP" samplesize="SS_SBP"}
Why these numbers (prose, optional).

[Change in SBP (mmHg)]{.effect difference="-6" sd="12" control="-3" profile="0.5; 0.8; 1" baseline_coef="-0.2" basis="earlier trial"}
[Correlation of the visits]{.correlation rho="0.6" structure="ar1" basis="guess"}
[Dropout by Week 12]{.dropout rate="0.15" mechanism="MAR" slope="0.6" basis="the sample size"}
[Treatment discontinuation]{.ice rate="0.08; 0.20" after="effect-lost" retain="0" collected="yes" basis="guess"}

[Pessimistic effect]{.scenario #PESS difference="-4.5" dropout="0.20" curve="true" basis="three quarters of the effect"}
:::

sapling check reads the block: a number out of range, the wrong number of per-group values, MNAR without delta=, a rescue event without shift=, a scenario named twice or named NULL, an effect without its sd= are errors with their fix; a part without basis= is a warning.

The plan around the analyses: design, sample size, multiplicity, missing data#

These blocks state what a SAP must say beyond its tables (Gamble et al. 2017, ICH E9(R1)). The structured SAP of the chain has no place for them yet: they go to the JSON (sapc json, "in_structured_sap": false), the preview and the PDF. Each cites the protocol like any block; a block the SAP adds (not in the protocol) is named by a change block (adds=): What the SAP adds to the protocol.

::: {.design type="parallel" allocation="1:1:1" blinding="double" framework="superiority" strata="ADSL.SITEGR1"}
:::
[]{.cite source="protocol:3.1"}

::: {.samplesize #SS_ADAS n="300" power="0.90" alpha="0.05" sided="2" effect="3.0" sd="6.5" dropout="0.10" test="ttest"}
:::
[]{.cite source="protocol:3.4.4" words="Previous experience ... standard deviation of 6.5"}

::: {.multiplicity #MULT procedure="graphical" alpha="0.05"}
**The primary and key secondary hypotheses**

[ADAS-Cog (11) dose response]{.hypothesis #H1 analysis="P_ADAS" weight="0.5"}
[CIBIC+ dose response]{.hypothesis #H2 analysis="EST2" weight="0.5"}
[]{.transition from="H1" to="H2" weight="1"}
[]{.transition from="H2" to="H1" weight="1"}
:::

::: {.missingdata #MD_ADAS analysis="P_ADAS" assumption="MAR" handling="mmrm"}
The MMRM uses all observed values; under MAR a patient who stops is like a patient who stays with the same history.
:::

::: {.sensitivity #SENS_TP estimand="EST1" method="tipping-point" assumption="MNAR" delta="0 to 6 by 0.5"
    imputations="100" seed="20261109"}
**Tipping point**

The imputed values of the active groups are made worse by delta until the conclusion changes.
:::

::: {.supplementary #SUP_COMP estimand="EST1" population="COMP24" method="completers"}
**Completers**

The same analysis in the patients who complete Week 24.
:::

::: {.interim #IA1 timing="50% of the patients complete Week 8" purpose="futility" futility="non-binding"
    spending="none" committee="the DMC"}
A look for futility only.
:::

::: {.software name="R" version="4.4.1" packages="mmrm 0.3.14; emmeans 1.10.7"}
:::

::: {.dictionary name="MedDRA" version="27.1" for="adverse events"}
:::

::: {.change adds="SENS_TP"}
**The SAP adds a tipping point analysis.**

LOCF is not a sensitivity analysis (EMA 2010, 7).
:::
[]{.cite source="protocol:4.3.2"}

The adjusted p-values. When every hypothesis of a multiplicity block names the same analysis and one of its pairs (comparison=), and the procedure is bonferroni (weighted by weight= when the hypotheses have weights), holm, hochberg or hierarchy (the fixed sequence: the adjusted p-value of a hypothesis is the largest p-value of it and of those before it; it is rejected when that is at most alpha), the engines make the adjusted p-value of each pair (the row Adjusted p-value; R stats::p.adjust, SAS %adjust, PROC MULTTEST INPVALUES=). The method block of the analysis gets adjust: {procedure, family} and the statistic padj. "Hochberg over two doses":

::: {.multiplicity #MULT procedure="hochberg" alpha="0.05"}
**The two doses against placebo**

[High dose]{.hypothesis #H1 analysis="A_RESP" comparison="High Dose vs Placebo"}
[Low dose]{.hypothesis #H2 analysis="A_RESP" comparison="Low Dose vs Placebo"}
:::

A family over several analyses, a graphical procedure, Dunnett's test and the co-primary criterion are stated in the plan; the engines do not adjust them (an error says so when a hypothesis names a pair).

None, as data. A plan says "no adjustment for multiplicity", "no interim analysis is planned" or "no sensitivity analysis is planned" with the value none of the attribute that says what is done, and the reason (in the body) or the protocol's sentence (a citation after the block, or of the heading of its section):

::: {.multiplicity #MULT procedure="none"}
**No adjustment for multiplicity**

The study is a dose-finding study: each dose is compared with placebo at the two-sided 5% level.
:::
[]{.cite source="protocol:4.3.3" words="Effects in the ANCOVA model"}

::: {.interim #IA purpose="none"}
No interim analysis is planned.
:::

::: {.sensitivity #SENS_NONE estimand="EST1" method="none"}
**No sensitivity analysis**

The primary analysis is descriptive: it tests no assumption about the missing values.
:::

A none block without a reason and without a citation is an error. The review no longer says "the protocol plans interim analyses" when every sentence of the protocol on interim analyses says there is none ("No interim analyses ... are planned").

Subgroup analyses#

One block declares the subgroup analyses of one or more analyses: the factors, what each level reports, the test of the interaction of the treatment and each factor, the minimum size of a level and the forest plot. Each factor is a grouping (its variable and its levels, from the plan or from the data).

::: {.grouping #SG_SEX variable="ADSL.SEX" groups="F; M"}
Sex
:::
::: {.grouping #SG_AGE variable="ADSL.AGEGR1" groups="<65; 65-80; >80"}
Age group
:::

::: {.subgroup #SG_PRIM analyses="A_ANCOVA" factors="SG_SEX; SG_AGE" interaction="0.10" minimum="10"
    level="exploratory"}
**Subgroup analyses of the primary endpoint**

Exploratory: the difference of the LS means and its 95% CI in each level; no adjustment for multiplicity.
:::

What the compiler makes (in the structured SAP, each with the subgroup block's citation as its source): for each analysis A and factor F an analysis of the levels (<SG>_<F>, or <SG>_<A>_<F> with several analyses: A's data and records, by the treatment and F, its method <SG>_<A>_LEVEL the method of A: the same model, engine and options, its statistics without the p-value unless pvalue="true"), the test of the interaction (<SG>_<F>_INT with the method <SG>_<F>_INTERACTION, test: interaction), the count of the subjects of each group in each level (<SG>_N), and one table <SG>_T with these analyses. The engines:

• each level is A's own engine on the records of the level (r-agentic makes one fit per value of a further grouping of the results; ars_e_subgroup around it applies minimum=). No second computation of a method.
• the interaction (ars_e_interaction): A's model with the factor as a main effect, against the same model with the treatment-by-factor terms. A linear model (ANCOVA, ANOVA): the F test of the terms (SAS PROC GLM, the Type III F test of the interaction). A logistic, Poisson, negative binomial (the dispersion estimated in each model) or Cox model: the likelihood-ratio test, chi-square with the number of terms the data estimate. The Wald test is not made. No engine tests the interaction of a t-test, a Wilcoxon test or the comparison of two proportions: an error says so (interaction="none", or write the analysis as a model). Known answers: the methods interaction-lm, -logistic, -poisson, -negbin, -cox of the table above (the fits written out in tools/method_answers.R).
• SAS (not yet run on a SAS server): each level is the macro of A with within= the factor (%cox, %logistic, %rateratio, %lsmeans); the interaction is %interaction_glm, %interaction_logistic, %interaction_phreg or %interaction_genmod (each holds its procedure); the forest plot is %forestplot of the same results. minimum= is applied by R only (the SAS program says so above the call).

What the products show: the table shell has, for each factor, one row per level with the subjects of each group and the estimate of each pair with its 95% CI across the groups, then the interaction p-value of the factor; the ARD of the table has the factor's grouping and level in each result; the forest plot (sapling tlf companions: R; SAS %forestplot) draws the same results; the box of the block in the rendered plan says what is made in one sentence (each default marked) with the table of its analyses; the dashboard has the table as a page whose source is the block's citation.

The review: e9.covariates-subgroups (no interaction test and no reason), e9.multiplicity (p-values of the levels or of the interaction, and no multiplicity block that says the other tests are nominal or names the analysis), ema-subgroups.prespecify (no level=; a factor whose levels come from the data).

Interim analyses tied to their hypotheses#

An interim look that may stop for efficacy names the hypotheses it tests (hypotheses=: hypotheses of multiplicity blocks). The compiler then makes the group-sequential design of each such hypothesis: its looks (each interim block that names it, in the order of the information, and its final analysis at information 1), its level (its share of the alpha of its family: the family's alpha for hierarchy and co-primary; alpha= or weight= times the family's alpha for bonferroni; the first step for holm, hochberg and graphical), and the efficacy boundary of each look as data. NCT05505734 (one look at half of the events, O'Brien-Fleming spending, two-sided 0.05; stop only when both hypotheses are rejected; 0.049 at the final analysis):

::: {.multiplicity #MULT_IA procedure="hierarchy" alpha="0.05"}
**The primary hypothesis, then the first key secondary one**

[Change at Week 24, high dose against placebo]{.hypothesis #H1_IA analysis="A_PRIM" final_alpha="0.049"}
[Change at Week 16, high dose against placebo]{.hypothesis #H2_IA analysis="A_ANCOVA" final_alpha="0.049"}
:::

::: {.interim #IA_EFF2 hypotheses="H1_IA; H2_IA" information="0.5" events="172" purpose="efficacy"
    spending="obrien-fleming" alpha="0.003" stop="all" committee="the independent data monitoring committee"}
One look for efficacy at half of the planned events. The study stops only when both hypotheses are rejected.
:::

What the compiler computes (src/gsd.ts): the recursive numerical integration of Armitage, McPherson and Rowe (1969; Jennison and Turnbull 2000, chapter 19) of the joint normal distribution of the statistics of the looks (no simulation). The efficacy boundaries are one-sided at the one-sided level (a two-sided 0.05 has the boundaries of one-sided 0.025, and the p-values are shown two-sided); a futility boundary is not used in the computation (the boundaries of a non-binding rule; with a binding rule the type I error is then at most the level, and the rendered plan says so). With haybittle-peto or fixed the boundaries of the interim looks are the stated ones and the final boundary is the one that keeps the level. A look with spending="fixed" and no information= (an analysis at a data cutoff an agency asks for) spends its alpha by Bonferroni: the other looks share the rest. Known answers: Jennison and Turnbull (2000) Tables 2.1 and 2.3, the gsDesign technical manual, and the two SAPs above (test/gsd.test.ts); the crossing probabilities again by mvtnorm::pmvnorm (test/gsd-r.test.ts).

What it checks: each hypothesis of hypotheses= is a hypothesis of a multiplicity block; each look has its information fraction; one spending function per hypothesis; an efficacy look without hypotheses= is a warning (no family accounts for its alpha). A stated number (alpha=, z= with a spending function; final_alpha=) that is not the computed one at the precision it is written with is a warning with both numbers. The review (interim.alpha-spending): an efficacy look without a spending function or a boundary is an error; without its information fraction a warning; the looks of a hypothesis that spend more than its level with the plan's own numbers is an error with both numbers.

What it shows: the box of the interim analysis in the rendered plan has one row per hypothesis with the design in a sentence (the function, the level, the final alpha that results, what all looks spend) and the boundary table (look, information, events, hypothesis, z, p, cumulative alpha, the plan's own number, the futility boundary). The JSON has the table as boundaries of the interim block and the design as group_sequential of each hypothesis.

What Sapling does not compute: the boundaries after the real information differs from the plan (the plan states the rule in words: recomputed by the same spending function at the real fraction), a sample size re-estimation and conditional power (prose, or an open decision), repeated confidence intervals, boundaries that move when a graph passes alpha on (Maurer and Bretz 2013: the table is at the first level of each hypothesis).

Adverse event tables and the treatment-emergent period#

The safety part of a plan states its definitions and its tables as data (guides/safety.md: how real SAPs state them). Five forms, each made by both engines from the same contract (R: r-agentic; SAS: the macro library, not yet run on a SAS server):

::: {.treatmentemergent #TEAE variable="ADAE.TRTEMFL" start="TRTSDT" end="TRTEDT + 30" missing="emergent"}
:::
[]{.cite source="protocol:4.4" words="Treatment-emergent adverse events (also referred to as"}

::: {.grouping #SEV variable="ADAE.AESEV" groups="MILD; MODERATE; SEVERE"}
Severity
:::

:::: {.tlf #T_AE population="SAF" columns="ACTUAL"}
**Treatment-emergent adverse events**

::: {.incidence #AE_SEV condition='ADAE.TRTEMFL = "Y"' rows="soc;pt" worst="SEV" order="alphabetical"}
By system organ class, preferred term and maximum severity
:::
::: {.incidence #AE_RD condition='ADAE.TRTEMFL = "Y"' rows="pt" threshold="5" order="frequency" test="riskdiff"
    ci="newcombe" pvalue="false"}
The preferred terms in 5% or more of a group, with the risk difference of each
:::
^[Descriptive comparisons: not adjusted for multiplicity.]
::::

Known answers: the fixture's made-up adverse events with their severities, counted by hand (tools/method_answers.R: the Wilson and Newcombe intervals written out, Pearson's X2, the exact Poisson limits; test/methods-r.test.ts), the same plan through the contract maker, the engines and ars_table (test/safety-r.test.ts: the worst severity of each subject, the rows of a threshold, the order of the rows, the column of each comparison), and the flag of the period on SDTM records through R (test/adam_steps-r.test.ts, step kind flag.teae). The review (safety.*, rules.md): the treatment-emergent definition, the order of the rows, the worst grade and its scale (CTCAE with its version), the value of a shift table, a p-value said to be descriptive, an event of special interest with its query or terms.

sapling generate table makes the conventional tables: teae-severity (by the maximum severity), teae-grade (by the maximum toxicity grade, the terms in descending frequency), teae-frequent (the terms in 5% or more of a group), teae-riskdiff (the risk difference of each of them, no p-value), teae-rate (the rates of the subjects and of the events per 100 patient-years); each default (5%, the order, the interval) is said in the plan for the statistician to change.

What these forms cannot say yet: an existing event that worsens after the first dose; the grades as columns; the system organ classes by frequency; the time at risk to the first event of each term; a threshold with Fisher's exact test or the chi-square test of each row; the denominator of each parameter or cycle of a laboratory table.

The options of a model: MMRM, Cox, estimates#

The method's options are attributes of the model: of the formula span or of the model div. They go into the method block of the structured SAP (model:, the chain's place for the model), and the hover shows the R call and the SAS procedure of this model with them.

[]{.formula formula="CHG ~ BASE + TRTP*AVISIT" covariance="us" fallback="toeph; ar1h; ar1" df="kenward-roger" estimation="reml" visit="Week 24"}
[]{.formula formula="Surv(AVAL, CNSR) ~ TRTP" test="cox" ties="efron" strata="SITEGR1"}

A Cox model gives the hazard ratio of each pair of comparisons= (by default each other group against the reference group of treatments:) from one fit of all groups, its 95% CI (Wald) and the p-value of the pair (stats="HR = xx.xx; 95% CI = (xx.xx, xx.xx); p-value = x.xxx", the default). The p-value is the Wald test of the pair in the model; pvalue="logrank" makes it the log-rank test of the two groups in the same strata, the usual "stratified log-rank test and the hazard ratio of the stratified Cox model" in one analysis:

[]{.formula formula="Surv(AVAL, CNSR) ~ TRTP + strata(STRAT1) + strata(STRAT2)" test="cox" ties="efron" pvalue="logrank"}

The direction of a comparison#

A hazard ratio, an odds ratio, a relative risk, a rate ratio and a difference compare two groups in one direction. Sapling never chooses it silently:

• treatments: names the control group with reference: (sapling new writes the arm whose type the USDM gives as a placebo control or no intervention; else the statistician writes it). As soon as a model compares pairs of groups and the treatments have no reference, the check is an error (comparison-reference) whose fix is the line to write.
• A pair "A vs B" is the estimate of A against B: the hazard ratio of A relative to B, the difference A minus B. Without comparisons= a model compares each other group against the reference, in the order of the groups. A comparison of two other groups (High vs Low) is written in comparisons=.
• A pair whose first group is the reference ("Placebo vs Drug") is a warning (comparison-direction) that names the pair and its inverse.
• The rendered plan (the box of the analysis, the HTML preview) prints the pairs with the estimate in words, and the table shell has a row per pair: Drug vs Placebo: Hazard ratio. The R engines and the SAS macros take the pairs as written (pairs = "Drug" "Placebo" in the SAS call, the pairs separated by #); test/direction-r.test.ts runs both directions of one pair through the contract maker and the R engine on the known answer: the hazard ratio of B vs A is 1 / that of A vs B, the risk difference turns its sign.

  treatments:
    groups: [BDA MDI 160/180 ug, AS MDI 180 ug]
    reference: AS MDI 180 ug
    variable: ADSL.TRT01P

Pairwise comparisons of the LS means, and what the chain cannot take yet#

:::: {.tlf #T14_3_01 population="EFF"}
**ADAS-Cog (11): ANCOVA at Week 24**

::: {.analysis #T14_3_01_LSM}
**Pairwise comparisons of the LS means**

[]{.data dataset="ADQSADAS" records='PARAMCD = "ACTOT" and AVISIT = "Week 24" and ANL01FL = "Y"'}
[]{.stats method="MODEL_N"}
[]{.formula formula="CHG ~ BASE + SITEGR1 + TRTP" contrast="pairwise"}
:::
::::

The treatment is a factor (TRTP), and contrast="pairwise" asks for the difference of the adjusted means of each pair of groups, with its standard error, 95% CI and p-value (the default statistics Diff (SE), 95% CI, p-value; stats= changes them, for example LS mean (SE) = xx.x (xx.xx) first for the LS mean of each group). The method block has test, model: {treatment, covariates, factors, contrast: pairwise} and comparisons (the list of pairs). The template (Appendix A) has a row per pair: the difference (SE) and its CI across the columns, the p-value on the pair's row (CSR Table 14-3.01). An MMRM takes the same attributes (with visit= the visit of the contrast). (MODEL_N is a statistics block of the full pilot plan: n = xx, the number of patients in the model.)

The engine of sapling computes them (ars_e_lsmeans; an MMRM: ars_e_mmrm): sapling build writes them into the structured SAP. Pending in the checker of the SAS project (warning chain-pending, only from sapc check and sapc build without --chain-pairwise): the unchanged checker of sas-macro-agentic takes an ANCOVA only as the test for linear dose response (model.dose), and it makes a comparison as a data subset of the two groups. For that checker the analysis is in the plan, its JSON ("in_structured_sap": false, with chain_pending: why) and its template, and its structured SAP has an open task (a todo with the analysis's quote) in its place. An ANCOVA that compares the groups without contrast="pairwise" stays an error (chain-model).

What each model makes is in The methods and what they report: the estimate, its SE and its CI of an ANCOVA with the dose (stats="Estimate = xx.xx; SE = xx.xx; 95% CI = (xx.xx, xx.xx); p-value = x.xxx"), the estimates of a Kaplan-Meier curve, an ANOVA with a dose and factors (the engine of the dose response). A model no engine computes (an MMRM with the dose, a Cox model or a logistic regression of a dose) is an error chain-engine that says which method can.

The review: the rules and waivers#

Every check of the knowledge base runs as you write (sapc check, the editor): a finding says what is missing or wrong, the fix in the Markdown of the plan, and the guideline with its section, for example

examples/cdiscpilot01/pilot.qmd:142:1: warning[missing.single-imputation]: the primary analysis P_ADAS (ADAS-Cog (11),
  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.
  142 | :::: {.analysis #P_ADAS}
      | ^^^^^^^^^^^^^^^^^^^^^^^^
  fix: write `::: {.missingdata #MD_P_ADAS analysis="P_ADAS" 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.1

The check and the review give the findings to act on first (the errors, then the warnings that ask for something: a seed, a version, a reason), and the kinds that need no action one by one as one line each, with the count and the first three names: the variables of the study the compiler cannot check yet (unknown-variable without an ADaM specification), the analyses the SAS project's checker cannot take yet (chain-pending), the values and steps of an ADaM derived in part before the data. sapling check --verbose (sapc check --verbose, sapc review --verbose) lists each one; the review file out/review.txt always has every one. The counts of the passes are those of every finding.

The rules, their severities and conditions: rules.md. sapc review plan.qmd writes the whole review (out/review.txt, review.json, review.html): the findings, the checklist items no program can check ("for the reviewer"), and the coverage of the 55 items of Gamble et al. 2017, the SPIRIT items that touch the SAP and the five ICH E9(R1) attributes of each estimand.

A plan silences a rule only with a reason, which is part of the plan (the PDF shows it):

::: {.waive rule="gamble.18" block="P_ADAS"}
P_ADAS keeps the layout of the study report; the estimate and its CI are in P_EFF_EST.
:::

::: {.waive rule="gamble.20"}
The protocol includes all enrolled patients in the safety analysis.
:::
[]{.cite source="protocol:3.10.2"}

block="ID" waives the findings on that block only; without it, every finding of the rule. A waiver of a rule that finds nothing is a warning (remove it); of a rule that does not exist, an error. The reason is the statistician's (or the protocol's, cited): an agent does not invent it.

The SAP library#

The block use makes the blocks of a pattern of standards/sap_library/ (the attribute answers= holds the pattern's questions as key=value; a missing key is an error that prints the question):

:::: {.tlf #P_EFF2 population="EFF"}
**Primary endpoint analysis**

::: {.use pattern="ancova_dose_response"
    answers="id=P_ADAS2, title={ADAS-Cog (11), change from baseline to Week 24}, dataset=ADQSADAS, param=ACTOT, visit=Week 24, dose=TRTPN, covariates=BASE, factors=SITEGR1"}
:::
::::

It compiles to the same blocks as the analysis with its formula span. Markdown has no macros: a family of tables is written out, one tlf div each (Macros), or made by sapling generate table <template> from the company's or the study's table templates (docs/omakase.md).

The kinds of blocks#

What the compiler checks#

sapc check plan.qmd: the syntax (every div closed, the front matter, the attributes of each block); every id once and every reference defined; every variable in the ADaM specification of its data set, the type of each value, the codelist of each quoted value; every citation (source, section, words, with the closest sentences); every model (variables, treatment term, method, the options of its method); the plan blocks (ratios, weights, transitions, references, numbers; the sample size recomputed); the approval (status: APPROVED needs approved:, written by a person, never "agent"); and the completeness rules of the knowledge base (src/rules/, rules.md: ICH E9(R1), Gamble et al. 2017, FDA and EMA guidance, the method pages; more with --rules module.mjs), each silenced only by a waive block with a reason; and what the chain refuses: a quote of a block that only the USDM file has, not the protocol index the chain checks (error chain-quote), an ANCOVA that compares the groups instead of the dose (error chain-model: the chain makes an ANCOVA only as the test for linear dose response, or the pairwise comparisons with contrast="pairwise"), and what no engine computes as the plan asks (error chain-engine, from the method registry: The methods and what they report). Then the chain's own checker on the product: tools/sap_build.py <study> --file sap/<name>.md ends SAP BUILD PASS (tools/chain_proof.sh).

examples/errors/typos.qmd:24:60: error[codelist]: "WEEK 24" is not a value of ADQSADAS.AVISIT (codelist AVISIT).
  24 | []{.data dataset="ADQSADAS" records='PARAMCD = "ACTOT" and AVISIT = "WEEK 24"'}
     |                                                            ^^^^^^^^^^^^^^^^^^
  fix: write AVISIT = "Week 24"

A message names a block by its class ("there is no block summarise"), and a fix shows the Markdown to write: the opener of a div with its attributes (::: {.software name="SAS" version="..."}) and what goes in its body, a span ([]{.data dataset="ADQSADAS" records="..."}), an attribute (population="SAF"), a heading (## Missing data) or a key of the front matter (alpha-level: {level: 0.05, sided: 2} under sapling:). The messages are written once (src/compile.ts, src/rules/); src/say.ts says them in their Markdown form. The test test/messages.test.ts checks that every message is in Markdown form and that every block a fix shows is Markdown the reader accepts.

The ADaM from the SAP#

Instead of naming an ADaM specification (adam:), a plan can derive its ADaM itself: a chapter names every variable the analyses read by the ADaM IG and derives it from SDTM (sdtm: folder under sapling: in the front matter); sapc adam plan.qmd makes the ADaM specification (r-agentic's format), the Define-ready table and one admiral program per data set. Every block, the rule language and the proofs: adam-from-sap.md. The full pilot: examples/cdiscpilot01/pilot-adam.qmd; these blocks are from it:

::: {.dataset name="ADSL" label="Subject-Level Analysis" structure="one record per subject" adam-class="ADSL"
    from="DM" where='ARMCD != "Scrnfail"' keys="USUBJID"
    order="STUDYID; USUBJID; SUBJID; SITEID; SITEGR1; ARM; TRT01P; TRT01PN; TRT01A; TRT01AN; TRTSDT; TRTEDT; TRTDUR; AVGDD; CUMDOSE; AGE; AGEGR1; AGEGR1N; AGEU; RACE; RACEN; SEX; ETHNIC; SAFFL; ITTFL; EFFFL; COMP8FL; COMP16FL; COMP24FL; DISCONFL; DSRAEFL; DTHFL; BMIBL; BMIBLGR1; HEIGHTBL; WEIGHTBL; EDUCLVL; DISONSDT; DURDIS; DURDSGR1; VISIT1DT; RFSTDTC; RFENDTC; VISNUMEN; RFENDT; DCDECOD; DCREASCD; MMSETOT"}
:::
::: {.derive variable="ADSL.TRT01PN" rule='0 if ARMCD = "Pbo"; 54 if ARMCD = "Xan_Lo"; 81 if ARMCD = "Xan_Hi"'}
:::
::: {.derive variable="ADSL.TRTSDT" rule="date(SVSTDTC)" from="SV" where="VISITNUM = 3"}
:::
::: {.flag variable="ADSL.SAFFL" condition='ITTFL = "Y" and TRTSDT is not missing'}
:::
::: {.cut variable="ADSL.AGEGR1" source="AGE" groups="<65; 65-80; >80" codes="AGEGR1N"}
:::
::: {.flag variable="ADQSADAS.ANL01FL" condition="AVISITN is not missing" mode="first" by="USUBJID; PARAMCD; AVISITN"
    order="AWTDIFF; ADY" label="Analysis Record Flag 01"}
:::
::: {.impute dataset="ADQSADAS" method="LOCF" records='PARAMCD = "ACTOT"'}
:::
::: {.baseline variable="ADQSADAS.BASE" source="AVAL"}
:::
::: {.changefrombase variable="ADQSADAS.CHG" rule="AVAL - BASE" records="AVISITN > 0"}
:::

Then every variable of every analysis is checked against these derivations: a variable no derivation makes is an error whose fix is the derive or copyvars block to write.

Before the data: part of the ADaM. The strict check above is for a plan with its SDTM data (sdtm:): it derives its whole ADaM. A plan without sdtm: may derive part of it (the time-to-event parameters with their ordered censoring rules, a window, a baseline, the imputation of a date) while the rest is named by the ADaM IG:

• a data set the plan does not declare (dataset) is checked against the ADaM IG, as in a plan without ADaM (a variable the IG does not have is a warning, not in the ADaM IG and not derived in the plan); a variable a declared data set does not derive is the same warning; a value of a derived codelist (a parameter not derived yet) a warning;
• a pattern writes without SDTM metadata: the columns of a source the plan does not derive are not checked (one warning per data set names them); a column read as a date is taken as a date (a warning names it); the type of a derivation from a domain is the ADaM IG's (a name ending in DT a date, a standard variable its IG type) or text, said in a warning; a copy without its SDTM label takes its name, said;
• with sdtm: every one of these is checked again, and an undeclared data set an analysis reads is the error unknown-dataset whose fix is the dataset block to write.

sapling build of a plan that derives no ADaM skips the ADaM specification, programs and data (it says so once: skipped: adam spec, adam programs: the SAP derives no ADaM ...) and goes on to the table specification, the shells, the QC specification and the programs: the contract takes a provisional ADaM specification of the variables the plan names (out/tlf/spec/adam: the derived variables, the ADaM IG's, and the others typed by their use in the plan, labelled "not specified yet"); sapling sas programs reads it. A study made from a protocol PDF (protocol/protocol.txt) gives the chain its page index from Sapling's reader of the text. The hooks of custom/ of a data set the plan does not derive (a companion plan in the same folder) are a warning: the programs of this plan do not run them.

Dates, results with limits, periods, computed parameters, censoring rules, intercurrent events#

These blocks state the patterns that real analysis plans need; each is a step kind with its guarantees and its fixture (adam-from-sap.md, "The commands"), made the same way in R and in SAS. A choice the plan must make has no hidden default: the compiler asks for it.

::: {.derive variable="ADAE.TRTEMFL" rule='"Y" if ASTDT >= TRTSDT or samemonth(AESTDTC, TRTSDT); "N" otherwise'}
:::
::: {.derive variable="ADAE.ASTDT" rule="date(AESTDTC)" impute="first" level="month" not-before="TRTSDT" flag="ASTDTF"}
:::
::: {.numeric variable="ADLB.AVAL" source="LBSTRESC" below="half" above="limit" flag="AVALQFL"}
:::
::: {.period variable="ADAE.APERIOD" date="ASTDT" periods="1: TR01SDT - TR01EDT; 2: TR02SDT - TR02EDT"
    text="APERIODC" names="Period 01; Period 02"}
:::
::: {.computed parameter="ADVS.BMI" rule="WEIGHT.AVAL / (HEIGHT.AVAL / 100) ** 2" by="AVISIT; AVISITN"}
:::
::: {.intercurrentevent variable="ADSL.RESCFL" records='CMCAT = "RESCUE"' from="CM" at="date(CMSTDTC)"
    start="TRTSDT" end="TRTEDT + 7" date="RESCDT"}
:::
::: {.timetoevent parameter="ADTTE.PFS" start="RANDDT" mode="ordered"}
[]{.censor records="LASTADT is missing" date="RANDDT" censor="1" set='EVNTDESC = "No adequate assessment"'}
[]{.censor records="NACTDT is not missing and (PDDT is missing or NACTDT < PDDT)" date="NACTDT" censor="1"}
[]{.censor records="PDDT is not missing and days(LADTPD, PDDT) > 91" date="LADTPD" censor="1"}
[]{.event records="PDDT is not missing" date="PDDT"}
[]{.censor records="" date="LASTADT" censor="1"}
:::
::: {.timetoevent parameter="ADTTE.DIL3X" start="TRTSDT" end="DCUTDT"}
[]{.event from="ADLB" records='PARAMCD in ("ALT", "AST") and R2A1HI >= 3' date="ADT" priority="PARAMCD" set='EVNTDESC = "ALT/AST >= 3x ULN"'}
[]{.censor date="DCUTDT" censor="1" set='EVNTDESC = "Cutoff date"'}
:::

The template and the programmer's hooks#

The generated programs are a template. The programmer's code goes into custom/ next to the plan, which sapc never writes: hooks the generated programs call at a named step (hook_before, hook_after, hook_override, hook_add, hook_filter in custom/<ds>.R; hook_layout in custom/tlf/<output>.R). Logic the rule language cannot say is still stated in the SAP, in words, with its code in a hook (custom=) or in one line of R (r=). These blocks are from examples/customize/custom-adam.qmd:

::: {.derive variable="ADSL.WTLOSFL"
    rule="Y when the mean of the weights of three consecutive visits after baseline (VS, WEIGHT) falls to 95 percent of the baseline weight WEIGHTBL or less at any time, N otherwise"
    custom="adsl_wtloss" type="C" length="1" label="Weight Loss (3-Visit Rolling Mean) Flag"}
:::

The compiler binds every hook to its step (an error with the fix when it cannot), lists the custom code, and sapc adam reports the hooks whose generated input changed after an amendment (hook drift). The rules, the custom report and the proof on the pilot: customize.md.

Start a plan#

A new study starts with sapling new (omakase.md): the study folder with its plan sap.qmd, made from the protocol (USDM) and the SDTM data.

sapling new <study> --protocol protocol/study_usdm.json --sdtm sdtm
node src/cli.ts init --protocol protocol/study_usdm.json --text protocol/protocol.json --adam adam --study STUDY01 study.qmd
node src/cli.ts import sap.md study.qmd --protocol protocol/protocol.json [--usdm F] [--adam DIR]

sapc init writes the first plan (study.qmd) from the protocol as CDISC USDM. The sections follow Gamble et al. 2017 (administrative information, introduction, study methods, statistical principles, trial population, analysis, references). What the USDM gives as data becomes the front matter and blocks: treatments: (the arms), visits: (the Baseline and Week encounters), alpha-level: (from the objective), a design block (the model and the blinding), a samplesize block (the planned number), the objectives and endpoints, estimand blocks (with their intercurrent events and strategies). What the protocol names in a sentence becomes a block with that sentence cited: the populations (their ADSL flag from the labels of the ADaM specification, or the ADaM IG), the tests (a test span, the chain's ids such as ANOVA_4_2), the software. Everything else is a decision block that cites the sentence that leaves it open, so sapc review shows what remains. Without --text, the protocol's page index is made from the USDM (protocol/protocol.json beside the plan, page for page the chain's protocol_to_sap.py index). sapc init never writes approved:; the one waiver it writes (a primary estimand that names no analysis yet) says why and asks to be removed.

sapc import reads a structured SAP (the chain's format) and writes the plan that compiles to the same blocks: each table with its rows (summarize, tabulate, incidence, byvisit, or an analysis with its data, by and the model as a formula), each test as a test span with its id, each quote as a citation (a sentence, or the words "from ... to"), each open task as a decision block. An approval or a decided decision of the source is kept as a comment: a person writes it again.

When the plan has usdm:, the structured SAP also carries the protocol's study definition: a todo with the visits (section: "USDM encounters") and one per endpoint (section: "USDM endpoints", the pattern of the library that fits or the gap), without a quote, as the chain's protocol_to_sap.py writes them; the chain's dashboard reads them.

The machine view: sapc json#

sapc json plan.qmd (and out/sap.json) is the whole plan as stable JSON for agents and tools: every heading and block with its kind, id, fields, protocol source and exact position in the file. Schema: json.md.

Reference card#

---
title: Statistical Analysis Plan            # Quarto: title, subtitle, date, author; toc: true
sapling:
  study: ID
  version: 0.1 (draft)
  status: DRAFT
  drafted-by: agent
  protocol: {file: protocol/protocol.json, name: Protocol X}
  usdm: protocol/study_usdm.json
  adam: adam                                # or sdtm: sdtm (the ADaM from the SAP)
  alpha-level: {level: 0.05, sided: 2, cite: {source: "usdm:objectives", words: "the words"}}
  treatments: {groups: [A, B, C], reference: A, variable: ADSL.TRT01P, cite: "usdm:arms"}
  visits: {visits: [Baseline, Week 2], variable: AVISIT}
  # approved: {by: Name, on: Date, role: statistician}    a person only, one per role
---

# Section []{.cite source="protocol:4.2" words="the words of the sentence"}
## Subsection []{.cite source="protocol:4.2" sentence="2"}

::: {.population #ID condition="ADSL.FLAG" definition="..."}
Name
:::
::: {.datasubset #ID condition="..."}
Name
:::
::: {.grouping #ID variable="DS.VAR" groups="a; b"}
Name
:::
::: {.derivation #ID variable="DS.VAR" rule="..." condition="..."}
:::
::: {.statistics #ID rows="n = xx; Mean (SD) = xx.x (xx.xx)" name="..." estimator="kaplan-meier"}
:::

Text with [anova]{.test}, [DS.VAR]{.var}, [ID]{.ref} and a citation []{.cite source="protocol:4.2" words="..."}.

::::: {.tlf #ID population="..." total="true" columns="..." pvalue="true" template="..." figure="true"}
**Title**

::: {.summarize #ID variable="DS.VAR" test="..." stats="..."}
Title
:::
::: {.tabulate #ID variable="DS.VAR" test="..." categories="a; b"}
Title
:::
::: {.incidence #ID condition="..." test="..." rows="soc;pt" comparisons="..." stats="..." worst="..." threshold="..."
    order="..." ci="..." pvalue="false"}
Title
:::
::: {.byvisit #ID dataset="DS" timepoint="true" visits="..." records="..."}
Title
:::
:::: {.analysis #ID population="..." test="..." worst="..."}
**Title**

[]{.data dataset="DS" records="..."}
[]{.variable variable="V"}
[]{.by groupings="G1; G2"}
[]{.stats method="M"}
[]{.formula formula="Y ~ ..." test="..." contrast="..." covariance="..." fallback="..." df="..." visit="..." ties="..." strata="..." stats="..."}
::::
^[a footnote of the shell]
:::::

::: {.model contrast="..." treatment="..."}
$$
Y_i = \mu + \tau\, d_i + \varepsilon_i
$$
[]{.where bindings="Y = CHG, d = TRTPN"}
:::

::: {.estimand #ID level="primary" role="main" of="..." target="..." population="..." analysis="..."}
**Title**

[...]{.treatment}
[...]{.endpoint}
[event]{.intercurrent strategy="treatment policy" reason="..." data="..."}
[...]{.summary}
:::

::: {.decision}
The task; a person adds answer="...", by="..." and on="..." when it is decided.
:::

::: {.design type="parallel" allocation="1:1" blinding="double" framework="superiority" margin="..." strata="..." randomisation="..."}
:::
::: {.samplesize #ID n="N" power="..." alpha="..." sided="..." effect="..." sd="..." rates="..." hr="..." events="..." dropout="..." test="..." per_group="..." joint_power="..." analysis="..."}
:::
::: {.multiplicity #ID procedure="..." alpha="..."}
**Title**

[words]{.hypothesis #H1 analysis="..." weight="..." alpha="..."}
[]{.transition from="H1" to="H2" weight="..."}
:::
::: {.missingdata #ID analysis="..." estimand="..." after="..." pattern="..." assumption="..." handling="..." imputations="..." seed="..."}
Justification.
:::
::: {.sensitivity #ID estimand="..." method="..." assumption="..." delta="..." reference="..." imputations="..." seed="..." analysis="..."}
**Title**
:::
::: {.supplementary #ID estimand="..." population="..." analysis="..." method="..."}
**Title**
:::
::: {.interim #ID information="..." timing="..." purpose="..." futility="..." spending="..." alpha="..." committee="..."}
Words.
:::
::: {.software name="R" version="..." packages="..." validation="..."}
:::
::: {.dictionary name="MedDRA" version="..." for="..."}
:::
::: {.treatmentemergent #ID variable="ADAE.TRTEMFL" start="TRTSDT" end="TRTEDT + 30" missing="..."}
:::
::: {.change adds="..." version="..." date="..."}
**What**

Reason.
:::
::: {.waive rule="rule-id" block="..."}
Reason.
:::
::: {.use pattern="..." answers="key=value, ..."}
:::

<!-- the ADaM from the SAP (docs/adam-from-sap.md; sdtm: in the front matter) -->
::: {.dataset name="AD.." label="..." structure="..." adam-class="..." from="..." where="..." keys="..." order="..."}
:::
::: {.copyvars dataset="DS" variables="VAR; NEW = OLD" from="..."}
:::
::: {.derive variable="DS.VAR" rule="..." from="..." where="..." first="..." last="..." impute="..." flag="..." label="..." length="..." type="..." work="true"}
:::
::: {.derive variable="DS.VAR" rule="the rule in words" custom="hook id" type="..." label="..."}
:::
::: {.flag variable="DS.VAR" condition="..." false="N" from="..." mode="first" by="..." order="..." label="..."}
:::
::: {.cut variable="DS.VAR" source="..." groups="<65; 65-80; >80" codes="..."}
:::
::: {.pooling variable="DS.VAR" source="..." by="..." minimum="..." into="..."}
:::
::: {.baseline variable="DS.BASE" source="AVAL" by="..." flag="..."}
:::
::: {.changefrombase variable="DS.CHG" rule="AVAL - BASE" records="..."}
:::
::: {.impute dataset="DS" method="LOCF" records="..." flag="..."}
:::
::: {.rangeindicator variable="DS.ANRIND" value="AVAL" low="..." high="..." fallback="..."}
:::
::: {.addrecords dataset="DS" records="..." set="V = value; ..."}
:::
::: {.relativechange dataset="DS" value="..." prefix="..." limit="..." separately="..."}
:::
::: {.parameter parameter="DS.PARAMCD" rule="mean(AVAL)" records="..." by="..." set="..."}
:::
::: {.codelist codelist="SEX" values="F = Female; M = Male"}
:::
::: {.parameters dataset="DS" from="..." value="..." select="true"}
[name]{.param paramcd="PARAMCD" n="..." code="..." derived="true"}
:::
::: {.windows datasets="DS; DS" by="day" day="..." as="..."}
[]{.window avisit="AVISIT" avisitn="AVISITN" range="2-84" target="..."}
:::
::: {.timetoevent parameter="DS.PARAMCD" start="..." end="..." start_time="..." end_desc="..." end_censor="..."}
[]{.event records="..." from="..." date="..." time="..." priority="..." set="..."}
[]{.censor records="..." from="..." date="..." censor="..." set="..."}
:::

Pandoc and Quarto#

The constructs are those Quarto documents: YAML front matter, ATX headings with attributes, fenced divs with attributes, bracketed spans, inline footnotes ^[...], $/$$ math, {#eq-...} on display math, definition lists, pipe tables, HTML comments.

node tools/quarto_check.ts [plan.qmd ...] [--no-render] checks them with Quarto. It copies each plan to a temporary folder outside the repository (rendering writes files next to its source), reads it with quarto pandoc -f markdown -t json, and renders it with quarto render --to html. Every div and span the reader of Sapling reads must be a Div or Span of Pandoc with the same class, id and attributes, and no fence or attribute may be left over as text: QUARTO CHECK PASS. npm test runs the Pandoc part on pilot.qmd when quarto is on the PATH.

With Quarto 1.11.9 (Pandoc of Quarto), all eight example plans pass: Pandoc reads every div and span as Sapling does (pilot-adam.qmd: 461 divs and 541 spans), every HTML comment as raw HTML, and Quarto renders each plan to HTML without a warning. What Pandoc reads differently:

• in a quoted attribute value, Pandoc reads a backslash before punctuation as an escape: Pandoc sees 50% and _ALB where the compiler keeps 50\% and \_ALB (values of the example plans, 40 in pilot-adam.qmd; see Attributes);
• $$...$$ {#eq-1} is a numbered equation for Quarto's cross-references; plain Pandoc shows {#eq-1} as text;
• without a filter, Quarto shows a span's content as text and the attributes of a div or span as data- attributes. Sapling's blocks show as their prose (a population as its name, a table as its title and rows); the citations, being empty spans, show nothing. The Quarto extension of Sapling (below) shows each block as a box.

A study folder: sap.qmd#

sapling new writes the plan as sap.qmd. Every study command reads it: check, status, find, decide, generate, sap sync, and every step of build and run. A study folder with a plan of the earlier LaTeX form and no sap.qmd is refused in one line.

The Quarto extension#

quarto/_extensions/sapling/ (_extension.yml and the Lua filter sapling.lua, about 250 lines). The plan names it in its front matter (filters: [sapling]); sapling new copies it into the study, so a Quarto preview in the editor shows the boxes. sapling sap pdf renders a copy of the plan in .sapling/render/pdf/ with the study's extension (or Sapling's, when the study has none) by quarto render sap.qmd --to typst (Typst). When Quarto fails, the step fails with Quarto's first error line (the whole log: .sapling/render/pdf/quarto.log.txt).

The PDF: a block is a box of the extension's own (Typst block(breakable: true)), not Quarto's callout, which cannot break across pages (it left gaps at the bottom of pages, and a box in a box at the bottom of a page was cut). The title of a box stays on the page of the first line of its body. HTML: Quarto's callout. Word (quarto render --to docx): a block is its title in bold and the table of its attributes (Quarto refuses a callout in a callout in Word); for the Word file of Sapling, with the way back, see docs/word.md.

Without the filter (plain Pandoc, or another tool) a block is plain prose; with plain Pandoc (quarto pandoc --lua-filter sapling.lua) the filter makes a div with the title in bold instead of a callout. The legibility is the aim. A study made before this extension has its own older copy in _extensions/sapling/: copy quarto/_extensions/sapling/ over it to get the boxes that break.

All commands#

The form of every command and environment of src/commands.ts. Made by node tools/qmd_doc.ts; npm test fails when it is stale.