How a number reaches a sentence

The short version

• Displays. A table is declared twice — what to compute, and how to show it — and the pipeline turns that pair into a dataset of statistics called an ARD, then into a rendered table.
• Addresses. Every statistic in that ARD can be named precisely. Prose never types a number; it cites the address, and the build substitutes the value.
• Values. A number the report reuses gets a name in one small central file, so a writer cites randomised-n instead of re-deriving the address in every sentence.
• Templates. One file says what a document of this kind is; a second says what this particular study puts in each of its sections. Table numbers are assigned at build time, never typed — so one display specification serves the full report and its synopsis, numbered differently in each.
• Gates. CI fails the build if any digit in the finished prose did not come from one of those bindings.

The picture

Part 1 · The atoms

What an ARD is here

An Analysis Results Dataset is the table of numbers before it is a table. Instead of a formatted grid, it is a long dataset with one row per computed statistic, and enough columns on each row to say exactly which statistic it is: which analysis produced it, which treatment group it belongs to, which variable and which level of that variable, and what the statistic is called.

open.csr uses the {cards} package to compute them and serializes them to a JSON file it owns, so the shape is fixed and the JavaScript half of the build can rely on it. Every row carries the same thirteen keys. Here are three real rows from the demographics display:

{"analysis":"age","group1":"TRT01A","group1_level":"Total","group2":null,"group2_level":null,
 "variable":"AGE","variable_level":null,"context":"continuous",
 "stat_name":"N","stat_label":"N","stat":254,"warning":null,"error":null}

{"analysis":"age","group1":"TRT01A","group1_level":"Total", ... "variable":"AGE",
 "stat_name":"mean","stat_label":"Mean","stat":75.0866141732284, ...}

{"analysis":"sex","group1":"TRT01A","group1_level":"Total", ... "variable":"SEX",
 "variable_level":"F","context":"categorical",
 "stat_name":"p","stat_label":"%","stat":0.562992125984252, ...}

Two properties of that file matter more than they look:

• Nothing is rounded. The mean age is stored to full precision and percentages are stored as proportions between 0 and 1. Rounding and scaling are decisions the display or the sentence makes, so the same stored number can appear as 75.1 in a table and 75.09 in a sentence without either of them being a different number.
• Every row is addressable. t-demographics:sex:p;variable_level=F;group=Total selects exactly one of those 236 rows. That address is the only way a number ever leaves this file. If it selects zero rows or more than one, the build fails.

Alongside the rows, the same file carries a provenance envelope: the hash of each spec that produced it, the hash and row count of every input dataset with the package version it came from, the R version and package versions of the session, and the git commit — or null where the working tree was dirty and the artifact cannot honestly name one.

The three files that declare a display

A display lives in one directory named for its slug — library/tfl/t-demographics/ — and holds three files. The split is the point: a statistician changes the first, a medical writer or a shell reviewer changes the second, and neither has to read the other to work.

The demographics display declares six analyses. This is the whole of what it asks to be computed:

id: t-demographics
regulatory_id: DMT01
type: table
dataset: adsl
analysis_set: safety
denominator: adsl
group: [TRT01A]
total: true
analyses:
  - { name: age,      method: continuous,  label: "Age (years)",  variables: [AGE] }
  - { name: agegr,    method: categorical, label: "Age group",    variables: [AGEGR1] }
  - { name: sex,      method: categorical, label: "Sex",          variables: [SEX] }
  - { name: race,     method: categorical, label: "Race",         variables: [RACE] }
  - { name: ethnic,   method: categorical, label: "Ethnicity",    variables: [ETHNIC] }
  - { name: baseline, method: continuous,  label: "Baseline vital signs",
      variables: [BLWT, BLHT, BLBMI] }

There are six built-in methods — a continuous summary, a categorical breakdown, a unique-subject count with denominator and percentage, a nested count for system-organ-class over preferred term, a row passthrough for listings, and a figure. Anything a method cannot express is written as an R function in a custom.R file beside the two YAML files, and named from the analysis; it receives the data and the spec and must hand back an ARD like any other analysis. One of the six demo displays uses that escape hatch.

display.yaml then says how those numbers become a page. Its rows block is a printing plan, not a computation:

columns:
  order: [Placebo, "Xanomeline Low Dose", "Xanomeline High Dose", Total]
format:
  digits: { p: 1, mean: 1, sd: 2, median: 1, min: 0, max: 0 }
rows:
  - { label: "Age (years)", section: true }
  - { analysis: age, variable: AGE, pattern: "{N}",   label: "n",         indent: 1 }
  - { analysis: age, variable: AGE, pattern: mean_sd, label: "Mean (SD)", indent: 1 }
  - { label: "Sex, n (%)", section: true }
  - { analysis: sex, variable: SEX, levels: all, pattern: n_pct, indent: 1,
      level_order: [F, M] }
variants:
  post_text: {}
  in_text:
    title: "Demographic Characteristics (Summary)"

pattern names a cell template. Eleven are built in — n, N, n_pct, pct, continuous, mean_sd, median, median_range, range, q1_q3 and value — and the display's own format block can add to or override any of them with a template such as "{n} ({p}%)". No closures ever enter a spec — presentation stays declarative, which is what makes a spec reviewable as a diff.

Part 2 · How a display becomes an output

One R function does the whole of it. regenerate("t-demographics") reads the two specs, validates them and checks they agree with each other, prepares only the datasets this display asks for, computes the ARD, allocates the next version directory, and writes eight files into it.

analysis.yaml         a byte copy of the spec that produced this, not a reference to it
display.yaml          likewise
ard.json              236 rows + the provenance envelope
table.html            the Section 14 variant, rendered
table.rtf             the same rendered cells as a submission artifact
table-in-text.html    the reduced variant used inside the narrative
table-in-text.rtf
manifest.json         who, why, when, which hashes, how many rows, which variants

• Versions accumulate; they do not replace. v001 stays exactly as it was when v002 is written, and current.json is a one-line pointer at whichever is live. A display's history is a directory listing rather than a git archaeology exercise.
• The specs are copied in, not referenced. An iteration can be read years later without resolving a commit, and the copy is what the hashes in the manifest are taken over.
• One render, two formats. The RTF and the HTML come from the same rendered cells in the same loop, so the submission artifact and the on-screen table cannot disagree, and the manifest stores the SHA-256 of the RTF as written — a test re-hashes every committed RTF against it, so a hand-edited file is caught.
• The change request travels with the version. iterations.yaml records, in the author's words, why v002 exists.

The reason this matters for the rest of the framework: everything downstream binds against the current iteration's ARD. Regenerating a display is therefore the event that can move a number in a sentence, and it is a single, dated, attributed, hashed act.

Part 3 · Values — a number with a name

An address is precise but unfriendly. t-disposition:randomised:n;group=Total is the number of subjects randomised, and a writer who wants that number in four different sentences would otherwise retype the address four times — and, worse, would have to re-derive it if the disposition display were restructured.

library/values/values.yaml gives such a number a name, once, centrally. It is source: a human or an agent edits it, and the pipeline regenerates the store. There are two kinds of entry, and exactly one kind per value.

values:
  - id: randomised-n
    label: "Subjects randomised"
    source: t-disposition:randomised:n;group=Total
    format: { digits: 0 }
    notes: "The denominator for every disposition percentage in section 10.1."

  - id: completed-pct
    label: "Percentage of randomised subjects who completed"
    source: t-disposition:completed:p;group=Total
    format: { scale: 100, digits: 1 }

  - id: ae-any-n-xanomeline
    label: "Subjects with at least one adverse event, both xanomeline arms"
    derived: { op: sum, inputs: [ae-any-n-low, ae-any-n-high] }
    format: { digits: 0 }

Why the arithmetic is declared rather than written

The derivation vocabulary is deliberately closed: sum, difference, ratio, percent, and nothing else. It would have been easier to allow a free-text expression. The reason it is a fixed list is that two different programs have to agree about the answer without running each other's code:

• The R pipeline evaluates the derivation when it builds the store.
• The JavaScript build re-evaluates it, independently, when it assembles the report and re-checks every value against the committed ARDs.

An arbitrary expression would mean either a shared interpreter or a trusted single implementation. A four-operator vocabulary means both sides can implement it correctly and a disagreement between them is a build failure rather than a silently different number. A derived value's inputs are themselves named values, so the chain back to an ARD row never breaks.

Why the generated store is never edited

outputs/values/values.json is what the store looks like after the pipeline runs it. Each entry carries the resolved number, the formatted string, and the citation: the address, the display, the iteration, the ARD file it was read from and that file's hash.

{ "id": "randomised-n", "label": "Subjects randomised", "kind": "ard",
  "value": 254, "formatted": "254", "format": { "scale": 1, "digits": 0 },
  "source": { "address": "t-disposition:randomised:n;group=Total",
              "display": "t-disposition", "analysis": "randomised",
              "iteration": "v002", "ard_file": "outputs/t-disposition/v002/ard.json",
              "ard_hash": "sha256:..." } }

The same principle covers outputs/, docs/assembled/, docs/evidence/ and the built site: they are all generated, all overwritten on the next run, and the repository's standing instruction to agents is that they may write source and only source. The pipeline is the only thing that regenerates.

Part 4 · Text — a sentence that binds a number

A text block is a markdown file with a YAML header, named for the ICH E3 section it belongs to. library/text/TXT-E3-1102.md is Section 11.2, Demographic and Other Baseline Characteristics.

The header carries what a reviewer needs to know about the block, not about its prose: which E3 section it fills, which displays it depends on, which requirements it satisfies, its approval state and who granted it, whether it was model-generated and with what prompt, and any digits it is explicitly allowed to state in words.

---
id: TXT-E3-1102
e3_section: "11.2"
title: "Demographic and Other Baseline Characteristics"
tier: parameterized
displays: [t-demographics]
allow_digits: []
approval: { state: approved, by: "@jwildfire", at: "2026-07-25" }
provenance: { model: null, prompt: null }
requirements: [TXT-DEMO-001]
---

Demographic and baseline characteristics were comparable across the three treatment
groups in the safety analysis set of
{{ard:t-demographics:age:N;group=Total}} patients.

Women accounted for {{ard:t-demographics:sex:n;variable_level=F;group=Total}} patients
({{ard:t-demographics:sex:p;variable_level=F;group=Total;scale=100;digits=1}}%) overall.

At build time that becomes:

Demographic and baseline characteristics were comparable across the three treatment
groups in the safety analysis set of 254 patients.

Women accounted for 143 patients (56.3%) overall.

Three kinds of token can appear in prose, and all three are the same idea — the sentence names something the build owns rather than stating it:

Two qualifiers ride on an address and are worth separating in your head, because only one of them can change which number you get:

• Selection. group, group2, variable and variable_level narrow which ARD row is meant. Get these wrong and the build stops.
• Presentation. scale multiplies (a proportion of 0.563 becomes 56.3) and digits rounds. They never touch the stored value, so the same row can be quoted to different precision in different sentences without any of them being inconsistent.

The gate that makes it stick

None of this would hold if a writer could simply type a number, so the build checks. After the bindings are substituted, it scans the rendered prose for digits and requires every digit run to have come from a resolved binding, a cross-reference, or a short explicit allow-list in the block's header for things that genuinely are text — an E3 section number, a protocol identifier, a threshold like “30 days” in a block about exposure windows. Digits inside inline code and markdown links are exempt.

The consequence is the thing worth telling a colleague: a typed number does not become a QC finding weeks later, it becomes a red build, in the pull request that typed it.

Tiers and approval

A block declares one of three tiers — boilerplate (standing text), parameterized (prose written once, numbers bound), generated (drafted by a model). A generated block that is not approved is not a failure; it is excluded from the assembled report and reported as pending review. In the current demo, 10 of the 15 blocks are in the report and 5 generated-tier drafts are held out, each named with the reason.

Part 5 · The template — what assembles all four

A template object is a directory under library/templates/ holding two files, and the division between them is the useful part.

Two properties of that pair are the reason a second object exists at all, and both are the framework paying off rather than new machinery:

• One display specification, numbered per document. t-disposition is Table 14.1.1 in the report and Table 13.1 in the synopsis, from the same unchanged spec, because a display's identity is its slug and its number is assigned at build time.
• The two documents cannot quote the same quantity differently. Where both state a number they state it through the same named value, so a disagreement between the report and its synopsis is a build failure rather than a review finding.

Gates judge the document being assembled rather than the whole Text Library — an E3 block legitimately cross-references Section 16.2.1 and must not fail against a synopsis model that has no Section 16. A block the library holds but this build did not assemble is reported as a warning, so “not gated” cannot read as “gated and clean”. The rest of this section walks ich-e3.

A section in sections.yaml declares its content model from a four-word vocabulary: text for narrative supplied by the Text Library, in_text_display for a reduced display rendered inline, post_text_index for a Section 14 container, and generated_provenance for the appendix the assembler writes itself. An empty list means a structural heading. Across the 119 sections that comes out as 62 text-only, 20 text plus an in-text display, 15 post-text containers, 21 structural headings and one provenance appendix.

# sections.yaml — the standard
- number: "11.2"
  title: "Demographic and Other Baseline Characteristics"
  slug: demographics
  content: [text, in_text_display]

# assembly.yaml — this report
slots:
  - section: "11.2"
    text: [TXT-E3-1102]
    displays: [t-demographics]     # rendered here as the in_text variant

post_text:
  - section: "14.1"
    displays: [t-disposition, t-demographics]

What a section actually pulls in

Section 11.2 of the demo report, assembled, is:

• The E3 heading and number, from sections.yaml.
• The block TXT-E3-1102, with its 16 bindings resolved against the current demographics ARD, rendered from markdown, and carrying its own approval state and fidelity result alongside the prose.
• The demographics display, in_text variant — the same ARD as Section 14, rendered under the shorter title the display declares for narrative use.
• A cross-reference in the last sentence that resolves to Table 14.1.2, because t-demographics is the second display listed under the 14.1 slot.

The assembler also writes a provenance appendix into Section 16.1.9 with no human involvement: for each display, its number, the hashes of both specs, the input datasets with their versions and hashes, the R environment, and the commit. It is the audit trail as a generated section of the document rather than a separate exercise.

One command does all of it. node scripts/assemble.mjs --all walks each object's section model, resolves the text library against the current ARDs, places the display variants, assigns the numbering, runs the gates, and writes the assembled JSON and HTML for every template object. It exits non-zero if any gate fails in any document, and CI runs it on every pull request.

What CI enforces, in one list

Six checks stand between a change and a merged report. None of them is a review activity; all of them are a red build.

• Structure. Every section referenced by the assembly exists in the E3 model, and no assigned table number collides with a section number.
• Binding resolution. Every {{ard:...}} address matches exactly one row of the display's current ARD.
• Named values. Every value in the store is re-derived from the committed ARDs, its cited hash checked, its formatting re-applied, and its arithmetic re-evaluated.
• Numeric fidelity. Every digit in the rendered prose traces back to a binding, a cross-reference, or a declared exemption.
• Cross-references. Every {{xref:...}} resolves to a display or section that exists in this report.
• Approval. Model-generated blocks without an approval record are excluded and reported, rather than quietly included.

Alongside those, the R suite is re-run from scratch and compared against its committed results, so the evidence in the repository can never be stale, and the site build fails on a broken internal link or any reference to an external host.

Where the code and the documentation disagree

These came out of reading the code against the written contracts. None is a defect in the framework; all five are things a reviewing colleague would otherwise trip over, and the first is the one worth acting on.

Where to read next

• The framework, in the repository — the same walkthrough as a document that sits beside the code and is published on the project site.
• Interface contracts — the normative file formats and schemas. This is what to read before changing anything.
• Design — the architecture and the twelve design decisions behind it, including why the ARD serialization is owned rather than borrowed and why numbering is derived.
• The project site — the assembled demo report, the display gallery with the ARD behind every table, and the requirements-to-evidence pages.
• library/ — the four source directories themselves. They are small, and reading t-demographics plus TXT-E3-1102.md plus assembly.yaml is about twenty minutes.

The demo study is CDISCPILOT01 from {pharmaverseadam} — public, regenerable, and the only data anywhere in the repository.