CSR template objects — what the report framework still has to be taught

The question underneath the ask

@jwildfire asked for additional template objects for the test study, referencing the consortium submission projects, before showing open.csr to colleagues. The literal ask is small. The question underneath it is not, and it is worth stating before the answer: is the template layer a framework, or is it one ICH E3 file with two names?

Until tonight there was no way to tell. A template object in open.csr is a pair of files — a document model that says what this kind of document is, and an assembly that says what this report puts in it — and the code that walks that pair is entirely generic. But the library held exactly one instance, and the assembler hard-coded its path. Generic was a property of the code, not a property anything checked.

1 · What a template object actually is

Two YAML files in a directory under library/templates/. That is the whole contract, and it is worth reading once because everything below depends on the split.

The split is what makes the numbering claim possible. A display is identified by its slug, never by its number; the number is assigned at build time from the order it appears in the assembly. That is design decision D6, and until tonight it was a claim in a comment.

2 · The second one, and what it proves

The ICH E3 Annex I synopsis. E3 prints it as a labelled form — sponsor, title, investigators, studied period, phase, objectives, methodology, number of patients, and so on to the conclusion and the date of the report. Encoding that form as a document model gives a document that is short enough to read in two minutes and complete enough to exercise everything.

Three things it demonstrates that a second copy of the CSR model would not have:

Two documents cannot disagree about a number

The synopsis and the report both draw from one store of named values. 254 randomised, 43.3% completed, 217 patients with a treatment-emergent adverse event: the same figures appear in both because both bind the same value, not because someone checked. Every value is re-derived from the committed analysis results dataset at build time, so a value that has drifted fails both builds in the same breath.

The same display carries a different number in each

From the same display specifications and the same unchanged prose. Nothing in library/tfl/ knows which document it is in.

A gap stays visible instead of disappearing

Both documents declare their efficacy sections and leave them marked unpopulated. No efficacy analysis dataset exists for this study in pharmaverseadam, and the reference report for the same study devotes thirteen tables to efficacy. A synopsis that quietly dropped the efficacy headings would have looked more finished and told the reader less.

3 · The twelve documents a CSR framework plausibly needs

Written from what a study actually has to produce, not from what would be easy. The last column is the honest one: what stands between open.csr and building it.

4 · What the consortium actually publishes

The R Consortium Submissions Working Group runs a series of pilots that submit R-based analyses to the FDA and publish the whole package. Twenty-six repositories under the RConsortium organisation carry submission in their name. Each pilot splits in two: a development repository, and a -to-fda repository holding the eCTD package as submitted.

The artifact closest to what open.csr does is Pilot 1's four TLF programs — tlf-demographic, tlf-primary, tlf-efficacy, tlf-kmplot — and Pilot 6's t_14_1_1.r, which builds an analysis results dataset and renders from it, the same shape open.csr uses. That is a genuine convergence and worth saying out loud: two independent efforts arrived at ARD-first rendering.

5 · The licence position, which decides most of this

open.csr is Apache-2.0, in LICENSE, in package.json and in the R package DESCRIPTION. Every consortium repository was checked against the GitHub API rather than assumed.

Nothing in tonight's pull request derives from any of it. Both document models are encoded from ICH E3, a public guideline, on the same footing the existing model already used, and the pull request says so in the file header where a future reader will find it.

This is a question worth asking the working group rather than working around. Several of these repositories would probably carry a permissive licence if someone asked; none of them will start doing so on their own.

6 · What the consortium work does give us

Three things, none of which required copying anything.

The test-study data, under a licence that works

open.csr already builds on pharmaverseadam, which is Apache-2.0 — the same licence open.csr uses. That is the one clean lane, and it is the one already in use.

A convergent design, independently arrived at

Pilot 6 computes an analysis results dataset and renders the table from it, rather than computing inside the table program. open.csr does the same. Two efforts reaching the same architecture is worth a sentence in the README, and costs nothing.

An honest measure of how far along we are

Pilot 6 carries the CDISC pilot study's own statistical analysis plan, which lists the displays a real report for our test study contains: thirty-one tables and one figure, in seven groups. Reading that as a fact about the study — not copying it — gives a gap analysis nothing else could:

Six of thirty-two, and the six are the safety spine. That is a fair position for a framework at this stage, and it is a far more useful sentence to put in front of a colleague than a claim that the framework is complete.

7 · Steps to the next template object

Written so someone could execute them, and split by whether they need @jwildfire.

Mechanical — no decision required

1. Create library/templates/<id>/sections.yaml with the document's sections. Numbers must be dotted and numeric, slugs unique and permanent, and every section declares what content it accepts.
2. Create library/templates/<id>/assembly.yaml naming only the sections this report populates. A section left unclaimed appears as a heading marked unpopulated, which is the honest default.
3. Declare a section that accepts generated provenance, and point provenance_section at it. The assembler refuses to build without one.
4. Run node scripts/assemble.mjs --template <id>. Every gate runs. Cross-references are the usual first failure: a text block written for another document may point at a section this model has not got.
5. Add requirement rows and a test file carrying their IDs. The requirement checker fails on an ID no test references and on a test referencing an ID no matrix row defines.

Needs a decision

• Whether prose is shared or per-document. Tonight's synopsis got its own eighteen blocks because the report's blocks cross-reference E3 section numbers a synopsis has not got. The alternative is a cross-reference that resolves per-document, which is a real design change and should not be made by accident.
• Whether the Text Library stays flat. Two document models share one directory, distinguished only by an id prefix. A third would want a per-model index.
• Whether to ask the working group about licensing. Reusing their ADRG structure or their eCTD skeleton is blocked on a licence nobody has been asked for.
• Whether the reviewer's guides are in scope at all. They need dataset-level metadata open.csr does not currently hold, which is a bigger commitment than a template object.

8 · What I could not establish

Where this leaves the ask

• A template was delivered, not a plan for one. open.csr PR #29 adds the synopsis, assembles it against the test study, and puts every template object in the library through CI.
• The consortium reference was researched read-only, and its answer is a licence answer rather than a design one. Nothing was adapted, quietly or otherwise.
• Two more template objects are within reach with no new prose and no decision — the post-text display package, and the abbreviated report.
• The synopsis is not yet reachable from the demo site, which still reads a single assembled document. That is the one visible loose end, and it is deliberate: a parallel session was editing the site this evening.