The ADaM from the SAP

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

The SAP names its variables by the ADaM standard and derives them from SDTM; the ADaM specification, its programs and its data are products of the SAP.

Why#

An ADaM data set is built according to the SAP, and the SAP names ADaM variables (ADSL.EFFFL, ADQSADAS.CHG). Until now Sapling checked the names against an ADaM specification that a programmer had written before (adam: adam under sapling:), and the programs that made the ADaM were written by hand from that specification. The same decision (who is in the efficacy population, which record is the Week 24 value, when an adverse event is treatment emergent) was written three times: in the SAP, in the specification, in the program. Each copy can be wrong in another way.

Now the plan says it once. A chapter of the plan derives every ADaM variable the analyses read, from the SDTM data, with the ADaM IG's names; sapc adam makes from it the specification, the Define-ready table and one R program per data set. Plans with adam: dir under sapling: work as before.

SAP (.qmd) ──sapc check──► the analyses checked against the derivations of the same file
    │
    ├──sapc adam──► specs/adam/*.json, codelists.json (the ADaM specification, r-agentic's format)
    │               define.md, define.csv (the Define-ready table)
    │               programs/*.R (admiral, one per data set; each step headed by its SAP section and protocol quote)
    │               build_order.txt
    │                    │ dsr batch, on SDTM
    │                    ▼
    │               the ADaM data (output/adam/*.xpt)
    └──sapc build──► sap.md ──r-agentic's chain──► TLFs, ARD, CSR numbers ──► the study dashboard

The vocabulary: standards and SDTM#

• Variable names and labels: the ADaM IG v1.2 (standards/adamig_v1.2_variables.csv: ADSL, BDS with time to event) and the ADaM OCCDS standard (standards/adam_occds_variables.csv: ASTDT, TRTEMFL, AOCCFL, CQzzNAM, ...). The numbered names are filled in: TRT01PN is "Planned Treatment for Period 01 (N)", ANL01FL "Analysis Flag 01". A variable the standards do not name needs label=.
• The SDTM data: sdtm: folder under sapling: in the front matter, a folder of .xpt files or its metadata file sdtm.json (sapc sdtm <folder> --out sdtm.json: every domain, every variable with its label, type, length, its longest value, and the values of the variables with at most 60 of them). The compiler checks each source variable against it; a copy takes its label, type and length from it; a short list of values becomes a codelist. examples/cdiscpilot01/sdtm/sdtm.json is the metadata of the pilot's SDTM (r-agentic data/sdtm).
• No ADaM specification is an input. It is an output. A plan has either adam: dir under sapling: (the specification a programmer wrote, as before) or the derivations (dataset ...), not both.

The commands#

One fact in one place: each variable is made by one command; a second one is an error. Each command takes its citation like any block of a plan: a citation after it, or after the heading of its section (the copies, the data set and its parameters need none). The commands are made in the order of the plan, data set by data set: a variable is used after the line that makes it (the compiler checks it).

Each kind of step has one entry in the registry of the step kinds (src/adam_steps.ts): what the statistician writes, its options with their stated defaults, what it guarantees about the result (ties, missing values, a subject without a record, a record on a boundary), its R and its SAS rendering, and a fixture of made-up records with the expected records. The tables below are made from it.

The options and their stated defaults (what a plan does not say, both engines do as written here):

Why each newer kind is a pattern of its own (a kind of step), not a function of the rule language:

The fixtures (made-up records; test/adam_steps-r.test.ts runs each through sapc adam and the R engine and compares every record with the expected records; node tools/adam_steps_sas.ts does the same on the SAS server): 37 fixtures of 33 step kinds.

The decodes of a codelist, in their order: ::: {.codelist codelist="SEX" values="F = Female; M = Male; U = Unknown"} (or ::: {.codelist codelist="ADSL.SEX" values="..."}); the tables show the decode of a value the data give (codelists.json).

Options of every variable command: label= (a name the standards do not have), length=, type= (when the rule does not tell it), work (a work variable: used by later steps, not in the data set).

The rules#

rule      := case (";" case)*                0 if ARMCD = "Pbo"; 54 if ARMCD = "Xan_Lo"; 81 otherwise
case      := value ["if" condition | "otherwise"]
condition := and, or, not; = != < <= > >= (or eq ne lt le gt ge); X is [not] missing; X [not] in ("A", "B");
             any DOMAIN(condition)
value     := numbers, "texts", variables, missing, + - * / **, (...), functions

Functions: date(--DTC), days(from, to) (both days counted; two different days never have 0 days), months(from, to) (days / 30.4375), year(x), month(x) (of a date or an ISO 8601 text, a partial one too), samemonth(x, y), studyday(date, reference), round(x, d) (half away from zero, as SAS), max(...), min(...), abs(x), coalesce(...), contains(x, "A|B"), startswith(x, "_"); over records: sum(x) (missing when all are, as SAS SUM), mean(x), count(condition), any(condition), all(condition).

Missing values as a SAS WHERE: a comparison with a missing value is false (AGE < 65 is false when AGE is missing: no age group); X != "Y" is true when X is missing (a missing value is not "Y"). A case without otherwise leaves the variable missing when no case holds. The generated R keeps this (%in%, case_when()), the way the study's programs make R give the SAS numbers.

What the compiler checks#

• every variable an analysis, population, subset, grouping or model reads is derived or copied in the plan, else an error with the fix: derive it in the plan: ::: {.derive variable="ADSL.EFFFL" rule="rule"}, or copy it: ::: {.copyvars dataset="ADSL" variables="EFFFL" from="DOMAIN"};
• every quoted value against the codelist the derivations give (a block cut's groups, a flag's Y/N, the parameters, the windows, the SDTM values of a copy): ADSL.AGEGR1 = ">=80" is an error;
• every quoted value a derivation compares with a column of its SDTM rows against the values the data have (warning adam.value, with the values and did you mean): ARMCD = "PLACEBO" when the data say PBO is a condition that is never true. It is a warning, not an error: data that are not complete yet can lack a value;
• every variable a derivation reads is a column of its rows or of its from= domain, or made before the line (with did you mean); any DOMAIN(...) against that domain;
• every source against the SDTM metadata (sapling: sdtm:); a data set used before its block dataset; a variable made twice; a non-standard variable without a label; names longer than 8 (transport files); keys; order= that leaves a variable out; a BDS data set without parameters; impute= on something other than a date; LOCF without windows or an analysis flag; the derivations without sapling: sdtm: (a warning: nothing can be checked).

sapc adam: the products#

node src/cli.ts adam examples/cdiscpilot01/pilot-adam.qmd --out examples/cdiscpilot01/out/adam

• specs/adam/<ds>.json, codelists.json: the specification in r-agentic's format (data set, label, structure, class, keys, program; per variable name, label, type, length, format, origin Predecessor/Derived/Assigned, source or method, codelist; sap: the plan's section; protocol: the protocol section and its words), with the params, windows and visits lists r-agentic's derive_vars_param(), derive_vars_window(), derive_vars_visit() read. Lengths: a text the length of its longest value (the SDTM data, the values the rule writes; FDA Technical Conformance Guide 4.1.4.1).
• define.md, define.csv: the Define-ready table, one row per variable (origin, source or derivation as the SAP writes it, codelist, SAP and protocol sections), and the codelists.
• programs/<ds>.R: one program per data set in r-agentic's conventions (sma_setup, sma_map_source, admiral, sma_finalize, sma_check_adam); each step is headed by the SAP section, the line of the plan, the command and the protocol's words. Nothing is typed in from the data: every value is the SAP's.
• build_order.txt: a data set after the data sets it reads.

The pilot: examples/cdiscpilot01/pilot-adam.qmd#

pilot-full.qmd (every analysis of the protocol and every table of the CSR) with adam: adam-full under sapling: replaced by sdtm: sdtm under sapling: and a section "The analysis data sets" (about 400 lines): ADSL, ADAE, ADQSADAS, ADQSCIBC, ADQSNPIX, ADVS, ADLBC, ADLBH, ADLBHY, ADTTE, 415 variables, 175 commands (and 4 codelists of decodes). Its structured SAP has the blocks of pilot-full's (the same analyses, word for word; only the prose of the new section is new), so the chain makes the same TLFs.

The proofs (zsh tools/adam_from_sap.sh, zsh tools/sap_to_dashboard.sh):

The differences of the transport files are attributes only (lengths: the longest value; labels: the standard's), never values: the cell-by-cell comparison is the proof.

Limits and open issues#

• The generator knows the derivations of the commands above. A rule outside them (a rolling window, a derivation over two data sets at once) is written in the SAP in words with ::: {.derive variable="..." rule="..." custom="<hook id>"} (or r="...") and its code in a hook of custom/<ds>.R; a programmer's adjustment of a generated step is a hook too (hook_override, hook_after, ...). The generated programs call the hooks; sapc adam reports the hooks an amendment of the SAP touches: customize.md.
• The total ACTOT of the ADAS-Cog is scored in the SDTM data (QSTESTCD ACTOT); the plan says how (the protocol's 30% rule) and takes AVAL from QSSTRESN. A study whose SDTM lacks the total would write it with parameter.
• The study's own conventions that differ from the standards are kept as differences, not copied: the lengths the pilot define allots, its labels ("Subject Died?"), its shared codelist names (ARMN). A sponsor that wants them writes length= and label=.
• sapc adam writes R; sapling sas adam programs writes SAS from the same model, every step kind with its SAS (sas.md, "The ADaM data sets in SAS"). The SAS of the fixtures had no run on a SAS server yet (node tools/adam_steps_sas.ts): sapling sas adam run says OPEN until it has.