Omakase: the Sapling doctrine and the study folder

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

Sapling chooses a complete, coherent stack and its conventions for you, like Ruby on Rails. You start from a protocol and a folder of SDTM data, and a few commands take you to the study dashboard. Every choice it makes is written in the open, in the SAP, where you keep it or change it.

The doctrine#

1. The SAP says what; the specs and the code say how. sap.qmd (Markdown for Quarto, docs/markdown.md) is the statistician's plan. The ADaM and TLF specifications (adam-spec.qmd, tlf-spec.qmd) are the programmer's: made from the SAP, edited by the programmer, checked against the SAP. The programs are made from the specs and are never edited.
2. Convention over configuration. A new study has one layout, one set of populations, one way to window the visits, one standard table set, one engine. A sapling.yml exists only when the study departs from a default.
3. Nothing hidden. Every default is a block of the SAP, marked <!-- default: omakase (<the convention>) --> (or <!-- default: company/<template> --> when your company's standards made it), with a citation of the protocol sentence that supports it. The PDF shows it like any other block.
4. Nobody decides for the statistician. A default is a proposal. The open decisions stay open until a person answers them (sapling decide); the AI drafts, it never approves or decides.
5. Every step says what it did. One verdict line per step, like Rails' generators; sapling status shows each step as fresh, stale, missing, edited or failed, and no step silently uses a stale product.
6. One bad analysis stops only its own output. An analysis no engine computes as the plan asks is an error of sapling check at its place (the method registry, docs/markdown.md "The methods and what they report"); sapling build and sapling run make every other output, and the verdict of tlf run names the output that is not made with its first cause (NOT MADE T14_3_2 (analysis T14_3_2_MMRM (sap.qmd:342): no engine computes ...)). sapling status shows tlf run as failed with that output and its cause; the steps after it (the dashboard, define, the package) say which output stopped them.
7. Everything is editable, in the easiest place for its owner (the table "Edit anything" below).

Getting started#

sapling new cdiscpilot01 --protocol usdm.json --sdtm sdtm/   # the study folder, a first SAP, the omakase defaults
cd cdiscpilot01
sapling generate table teae-severity                          # one more conventional table, in its section
sapling ai "state how missing data are handled in the primary analysis"   # your AI drafts; you apply
sapling decide                                                # the open decisions; a person answers them
sapling build                                                 # the SAP (PDF by Quarto), the specs, the programs
sapling run                                                   # the ADaM data, the TLFs, the ARD
sapling dashboard                                             # the study dashboard on a free port of 3100-3199

sapling doctor checks the machine first (Node, R and its packages, the R engine, DataStep Studio for R, Python, Quarto, the AI provider, the editor), each line with the exact command that fixes it.

The study folder#

The commands#

Every step has its own command, its products in a folder of out/ named like it, and one verdict line. A step knows what it needs: when an input is missing or older than its source, it says which command to run first, or makes it with --with-deps. sapling build and sapling run are these steps in order (one code path).

Options of the steps: --with-deps (make what is missing or stale first), --force (overwrite an edited product), --keep-session (leave the study's R session running).

sapling generate#

Each generator fills its defaults from the plan (its populations, data sets, variables) and from the facts sapling new read from the protocol and the data (.sapling/facts.json). The block is compiled in its place first: a generator that would add an error adds nothing. A second generate of the same block is an error that says where the first is (the line in the plan; --id adds another one). The same convention for the same endpoint (--endpoint N) is the same block. The visual editor offers the same generators in its insert palette, under "Ready-made from your protocol": one code path (src/omakase_service.ts).

The generators write Markdown directly. sapling new (src/init.ts, then src/omakase.ts), the skeleton from a protocol document (src/start.ts) and every sapling generate read the plan by its nodes (the Markdown reader) and write each block in its form of docs/markdown.md (mdCmd of src/qmd_plan.ts: a command of src/commands.ts from its arguments and options). A block a generator adds is inserted at the end of the own text of its section, with one empty line around it; an open decision it answers is removed with its citation. npm test compares the plan of sapling new and the block of each generator with their golden references (test/golden/).

sapling ai: the AI drafts, you apply#

sapling ai "state the primary estimand with its intercurrent events"      # the part of its kind: Estimands
sapling ai "a table of serious adverse events" --section Harms            # the part you name
sapling ai --apply out/ai/20261111-210550-state-the-primary-estimand.qmd  # a saved draft, applied later

Your AI provider (sapling.yml: ai.provider, src/ai.ts) writes the block from your words, the protocol's sentences, the names of the plan and the study, and the language reference. The block is compiled in its place; when it does not compile, the AI gets the compiler's messages and tries again (two times at most).

sapling new --protocol protocol.pdf: a skeleton from the protocol document#

Without a USDM file, sapling new reads the text of the protocol (a PDF through pdftotext, or a text file) into protocol/protocol.txt and writes a skeleton sap.qmd: one part per item of Gamble et al. 2017, each an open decision that names the section of the protocol that speaks of it (by the words of its headings, the statistics chapter first for a part about the analysis; else the section whose text says it most). A part whose section is not found cites nothing, and its decision says "The protocol is silent on it, or its section was not found". sapling new prints the parts it did not find, and a note for each kind of page whose text cannot be read as it is: the pages without text (pictures or scans), the letter-spaced pages and the lines of them it rebuilt, and the pages with cipher text (docs/markdown.md, "A protocol PDF whose text is not its words").

sapling dummy: data before the first patient#

A study with a protocol and the metadata of its SDTM data (sdtm/sdtm.json: the domains, their variables, the values a variable can take), and no data yet:

sapling dummy            # sdtm/*.xpt (DUMMY data) and the report sdtm/DUMMY.md
sapling run              # the ADaM data and the tables of the plan, on the dummy data

sapling dummy [--per-arm N] [--seed S] [--effect SD] [--endpoint DOMAIN.TESTCD] [--force] (src/dummy.ts) makes SAS transport files of DM, EX, DS, SV, AE and every findings domain with a list of test codes. It writes only the variables of the metadata, only values the metadata allow, no text longer than the metadata say. The same seed gives the same bytes. Two things in the data are designed:

1. The cases the imputation rules are for. The first subjects of every arm are one case each: complete, dropout, missed-visit, two-in-window, tie (two records equally far from the target day), late-visit (a record in the next window), no-baseline, two-baselines, partial-dates (a start date without the day in the month of the first dose, one without the month, an event without an end, one before the first dose), not-dosed, open-exposure (no end date of exposure), death, and the screen failures. sdtm/DUMMY.md lists each case with its subjects, and for each imputation or selection rule of the plan (a window, an analysis record flag, a baseline, a date imputation, LOCF, a population flag) the cases that reach it. A rule that no case reaches is named in the verdict. Look for the subjects in the ADaM data to see what the rule does with them.
2. The effect on the primary endpoint, in standard deviations of its test (--effect, default -1; the arms between the reference and the last one have their share). --effect 0 gives data under the null hypothesis. The generator tests the effect itself (Welch's t-test of the change from baseline to the last visit, observed cases; the same numbers as R's t.test) and prints the p-value: the default is significant for every seed tried. The primary test is the one whose name shares the most words with the primary endpoint of the plan, or --endpoint.

sapling dummy check (after sapling run, or sapling adam data --with-deps) reads the analysis data (out/adam/data/*.xpt; no R) and says what each rule did with its designed subjects, against what the generator knows of them (sdtm/dummy.json: an event recorded as 2025-01 started on study day 2). The report is out/dummy/check.md; each row is

• OK: the result every convention agrees on (of two records in a window, the closest one is analysed; a subject without a dose is not in the safety population);
• RULE: the result of a choice of the plan, for the statistician to confirm (of two records equally far from the target day the earlier one; a late visit counts for the window of its day; after a dropout the analysis data have no record, or a record made by LOCF);
• LOOK: a result that loses or changes data. On the second protocol with the omakase defaults there are four: an adverse event with the day missing in the month of the first dose is set to the first of the month, before the dose, and is not treatment emergent; one with the year only is not imputed and not treatment emergent; an exposure without an end date gives a treatment of 1 day (two subjects). They are defaults the statistician changes in the plan (impute=, the rule of TRTEMFL, the rule of TRTEDT); the check then shows the new result.

The guards: sapling dummy never replaces data it did not make (a sdtm/ with transport files and no DUMMY.md is refused); sapling package refuses dummy data. Limits: a domain without a generator (CM, MH, the trial design, the supplemental qualifiers) and a findings domain whose metadata list no test codes are not made, and the verdict says so; the visits are the scheduled ones the metadata name (Screening, Baseline, Week n).

The omakase defaults#

sapling check: a compiler with passes#

Each pass has its verdict line (PASS, WARN, FAIL) and file:line:col diagnostics with their fix. Exit code 0 (pass), 1 (--strict: warnings are errors, for CI and before approval), 2 (errors). --json for tools. Every step command runs the check first and refuses on errors ("fix these first").

How to change what Sapling made#

THE SAP SAYS WHAT, THE SPEC SAYS HOW. Change a thing at its source:

When the SAP changes after you edited a spec, sapling adam spec (or tlf spec) makes the SAP's new spec and merges it with yours, 3-way (the spec the SAP gave before, yours, the new one): your edits are kept, the SAP's change comes in, and a line both changed is marked as a conflict (<<<<<<< yours (the spec) ... >>>>>>> new (the SAP now)), never resolved silently. With no edit, the products are byte for byte what the SAP alone makes.

Edit anything#

sapling templates list shows every default and its layer; sapling templates copy defaults or copy table-<name> starts a file to edit. defaults.yml keys: age_groups, tables (the standard set of sapling new), lab_categories.

A table template is Markdown (docs/markdown.md), templates/table-<name>.qmd: the table as the generator writes it, with placeholders {{id}} (the id of the table), {{n}} (its number, 14.5.3), {{itt}}, {{saf}}, {{eff}} (the populations of the plan) and {{row:X}} (the id <id>_X of a row). The comment at its top is left out; the block gets the mark of its layer (<!-- default: study/table-sae -->):

<!-- The template of sapling generate table sae (study), Markdown (docs/markdown.md): {{id}}, {{n}}, ... -->
:::: {.tlf #{{id}} population="{{saf}}"}
**Table {{n}} Incidence of Serious Treatment-Emergent Adverse Events**

::: {.incidence #{{row:SER}} condition='ADAE.TRTEMFL = "Y" and ADAE.AESER = "Y"' rows="soc;pt"}
Serious treatment-emergent adverse events
:::
::::

A table template of the earlier LaTeX form (table-<name>.tex) is not taken. sapling generate refuses the table with a message that says how to replace the template: sapling templates copy table-<name> --force [--to company] writes the built-in table as table-<name>.qmd in the same folder; make the changes of the old template in it again, then remove the old file. sapling new leaves the table out with that note, and sapling templates list marks the file.

The R engine#

The R engine is r-agentic (its R library, its Python tools, its standards, the study dashboard), used in place from its installed location: no copy, and nothing written there. sapling doctor finds it (in this order): SAPLING_ENGINE, sapling.yml engine:, ~/.sapling/engine, r-agentic next to Sapling.

The study folder holds the engine's view of the study in .sapling/: links to the engine's R/, tools/ and standards/, the app's files linked in a real folder .sapling/apps/dashboard/, and the study as the engine reads it (.sapling/studies/<id>/: study.json, data/sdtm linked to sdtm/, the protocol's index, the structured SAP, the specifications, the programs, the engine's output). The study's .Rprofile loads the engine's R packages and library with options(sma.root = ".sapling"); r-agentic's harness finds its root by that option, and its Python tools run with their root set to .sapling (tools/engine_tool.py). R runs only through DataStep Studio for R (dsr start in the study folder, dsr batch, dsr eval), as r-agentic's AGENTS.md asks. r-agentic's own files and proofs are unchanged.

The proofs#

The MVP, and after it#

The MVP is the smallest end-to-end product a statistician and a programmer can use: sapling new (the study folder, the omakase SAP, Sapling Visual opens), the SAP edited in Sapling Visual or with sapling ai, sapling generate, the step commands with sapling status and sapling doctor, adam-spec.qmd made from the SAP with a basic grid in the editor (Sapling: Open ADaM Spec Grid: filter, sort, inline edit of the label, the length and the rule, the mark of a rule that differs from the SAP with the SAP line to write), the programs made from it, and the pilot from an empty folder to DASHBOARD PASS in 8 commands.

Built beyond the MVP and kept (tested in test/sapling.test.ts, small and self-contained): tlf-spec.qmd, sapling sap sync, the 3-way merge of a spec after an SAP change (conflicts marked), the company and study template layers (standards/, sapling templates), sapling export adam-spec --csv.

After the MVP (not built):

• sapling eject / sapling update (superseded by the specs as the editable source);
• the full panel set of the editor: the study settings and sapling.yml as forms, a template browser, a visual 3-way merge (Take / Keep / Edit), a steps panel with Run buttons, the R code cell of the grid with "test this expression on the data", a codelist editor, add / remove / duplicate rows in the grid;
• the TLF spec grid; sapling import adam-spec spec.xlsx; an Excel export (CSV only today);
• the SAP's declaration of every hook enforced by sapling check (a block for a custom step, a filter with custom=, a table with layout="custom:...": not in the language yet), and the custom-code demo (examples/customize) rewritten around the spec;
• the proof cases of the spec on the pilot with every gate (DURDIS in calendar months through a spec edit, an R-code flag and its subgroup table, a TLF layout edit, an SAP amendment merged);
• efficacy endpoints measured in the laboratory data or as a time to an event (an endpoint of the questionnaires is matched by its category; a vital sign by its name, to its parameter of ADVS; a vital sign measured at several time points per visit is not matched: the statistician says which record);
• the p-value of a table is printed with the pattern x.xxx by the R engine: a very small one shows as 0.000, not <0.001 (the engine's formatting; r-agentic is read only here);
• the regulatory (FDA) work.