feat: Proof-of-concept smartphrase implementation for SAP authoring

[metadatadriven]

Background

The AC/DC framework includes a phrase/sentence layer — a mechanism for generating human-readable descriptions of analyses from machine-readable AC/DC model metadata — but this layer is currently under-specified. This issue elaborates it into a concrete PoC by:

1. Grounding the SAP document structure in the TransCelerate Common Statistical Analysis Plan Template (the industry reference)
2. Defining a smartphrase: XML namespace that links SAP document text to all layers of the AC/DC model
3. Demonstrating the approach with two real study SAPs
4. Building self-contained interactive web demos for the CDISC AC/DC working group

The smartphrase link is bidirectional: a smartphrase: tag in a SAP document can resolve to display text driven by an AC/DC model instance (model → SAP), and authoring a tag can instantiate or reference an AC/DC concept (SAP → model).

---

Deliverables

1. Source documents

• TransCelerate Common SAP Template (.docx) added to repo
• CDISC Pilot Study SAP added to repo
• Breast Cancer study SAP added to repo

2. XHTML SAP document structure

• Analyse the TransCelerate template to identify its section hierarchy, standard content blocks, and text conventions
• Define an XHTML tag hierarchy using namespace sap: that represents a full SAP document
• Cover all major SAP sections (objectives, populations, datasets, methods, missing data handling, multiplicity, subgroups, sensitivity analyses, interim analyses, etc.)
• The base XHTML must be valid XHTML and renderable in a browser without the smartphrase layer active
• Document the sap: tag vocabulary in smartphrase/spec/sap-tags.md

3. Smartphrase layer specification

• Define the smartphrase: XML namespace with tag syntax and attributes
• Specify linkage to all layers of the AC/DC model: DataConcepts, Analysis/Derivation Concept instances and templates, Methods, Cubes (Dimensions, Measures, Attributes), Slices, and Sentences
• Define the bidirectional semantics:
  • Model → SAP: how a smartphrase: tag resolves to display text from an AC/DC instance
  • SAP → model: how tagging a passage instantiates or references an AC/DC concept
• Document in smartphrase/spec/smartphrase-spec.md
• No formal schema (XSD/RelaxNG) required at PoC stage

4. Worked examples

• CDISC Pilot Study SAP encoded in the sap: XHTML structure with smartphrase: tags throughout
• Breast Cancer study SAP encoded similarly
• Both examples should exercise a representative set of smartphrase types across all AC/DC model layers (not exhaustive coverage of every SAP sentence)

5. Interactive demos (self-contained single-page apps)

• Self-contained HTML/JS — no server required; data embedded or loaded from local JSON/XHTML files
• At minimum, one demo per interaction mode:
  • Hover / tooltip: reveal the underlying AC/DC metadata for a tagged smartphrase
  • Resolve: populate smartphrase placeholders with study-specific values from an AC/DC instance
  • Trace: display the full resolution chain (DataConcept → ADaM Class Variable → study variable → physical dataset)
• Entry point at smartphrase/demo/index.html

---

Out of scope

• Exhaustive coverage of every SAP sentence or section
• Integration with live Neo4j backend
• Formal XML schema (XSD/RelaxNG)
• Production tooling (validation pipeline, authoring UI)
• Public release beyond the CDISC AC/DC working group

---

Proposed repo structure

smartphrase/
  spec/
    sap-tags.md              # sap: namespace vocabulary and tag hierarchy
    smartphrase-spec.md      # smartphrase: namespace specification and bidirectional semantics
  source-docs/
    transceleerate-sap-template.docx
    cdisc-pilot-sap/         # source files for CDISC Pilot SAP
    breast-cancer-sap/       # source files for Breast Cancer SAP
  examples/
    cdisc-pilot-sap.xhtml    # Pilot SAP encoded with sap: + smartphrase: tags
    breast-cancer-sap.xhtml  # Breast Cancer SAP encoded similarly
  demo/
    index.html               # Entry point / navigation
    hover-demo.html
    resolve-demo.html
    trace-demo.html
    data/                    # Embedded AC/DC model data (JSON)

---

Labels

enhancement · proof-of-concept · smartphrase · sap-template

[metadatadriven]

An example of how smartphrases are defined within the AC/DC model can be found here:

https://github.com/cdisc-org/analysis-concepts/blob/bb4ff5c8bac71f429a0d60a0c68358512a945d42/lib/transformations/ACDC_Transformation_Library_v06.json

Note: this is one example from the transformations part of the model. All other parts of the AC/DC model — Methods, Concepts, Derivations, Slices, DataConcepts, etc. — would have equivalent smartphrase definitions following the same pattern.

[metadatadriven]

Progress update — branch smartphrase_01

Completed

Deliverable 1 — Source documents

• ✅ TransCelerate Common SAP Template (SAP_CoreTEE_v005.docx) added to smartphrase/source-docs/common-sap-template/
• ⬜ CDISC Pilot Study SAP — to be added
• ⬜ Breast Cancer study SAP — to be added

Deliverable 2 — XHTML SAP document structure (sap: namespace)

• ✅ Full tag vocabulary defined in smartphrase/spec/sap-tags.md
• All 9 analytical sections of the TransCelerate template mapped to sap: tags (Sections 10–13 are administrative and left as plain XHTML)
• Structural controls defined: sap:optional (pick-all-that-apply), sap:choice (pick-one), sap:repeat (repeating sections)
• Reusable sap:endpoint-analysis pattern covers primary, secondary, and other-objective analyses

Deliverable 3 — Smartphrase layer specification (smartphrase: namespace)

• ✅ Full specification defined in smartphrase/spec/smartphrase-spec.md
• Grounded in the 22 phrase templates / 8 roles from ACDC_Transformation_Library_v06.json
• Three-level tag hierarchy: smartphrase:analysis (section), smartphrase:sentence (block), smartphrase:phrase + smartphrase:binding (inline), plus smartphrase:ref for direct model references
• Bidirectional semantics documented: model→SAP resolution and SAP→model instantiation
• Full worked ANCOVA example included

Still to do

• ⬜ Add CDISC Pilot Study SAP and Breast Cancer SAP source documents
• ⬜ Encode both SAPs as sap: XHTML with smartphrase: tags (smartphrase/examples/)
• ⬜ Build interactive demos (smartphrase/demo/)

Note: branch smartphrase_01 cannot currently be pushed to cdisc-org — awaiting write access for metadatadriven.