Smartphrase: estimands and intercurrent events as smartphrases

[metadatadriven]

Smartphrase: estimands and intercurrent events as smartphrases

Sub-issue of #9. The smartphrase layer demonstrated in #9 expresses an analysis; this extends it to express an estimand.

Purpose

Make ICH E9(R1) estimands a first-class thing the smartphrase layer can author and read back, so that an SAP passage carrying an estimand description and the model instance behind it remain two views of one thing — the same claim #9 makes for analyses.

The motivating observation is that four of the five E9(R1) attributes are already covered by the v0.7 phrase roles, without anyone having designed for it: treatment maps onto grouping, variable onto endpoint/parameter/timepoint, population onto population. The gaps are attribute 4 (intercurrent-event handling) and attribute 5 (the summary measure). That makes this a targeted extension rather than a new workstream.

Requirements

The extension succeeds if these are true. Solution choices are separate — see "Proposed approach", which is a design input, not a constraint.

1. An estimand is expressible end-to-end. All five E9(R1) attributes can be authored as prose and read back as model metadata, bidirectionally, with no second copy — the one-state architecture of Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 is preserved.
2. Intercurrent-event handling is explicit and typed. Each declared ICE carries exactly one ICH E9(R1) strategy per estimand, drawn from the typed enum rather than free text, and the prose states it in language a reviewer would accept.
3. Strategy is connected to what actually implements it. A strategy is not merely asserted in prose; it resolves to the transformation(s) that operationalise it, so "hypothetical" in a sentence and an imputation step in the model cannot drift apart.
4. The summary measure is verifiable, not decorative. The summary named in prose must be an output the bound method provably produces.
5. Intercurrent events are traceable. An ICE phrase can be followed to how its per-subject occurrence is ascertained, and on to the data — a different trace axis from the analysis-value traces in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9.
6. Per-estimand strategy overrides work. The same ICE handled one way for the primary estimand and another for a sensitivity estimand is expressible without duplicating the ICE.
7. Standards alignment holds. Grounding in USDM/eSAP/ARS/ICH as Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 established; nothing invented where a term exists, and anything unregistered flagged illustrative.
8. Zero-install still. Static files, file://, no build step, no server.

Proposed approach

Recorded in smartphrase/DESIGN.md under "Planned extension — estimands and intercurrent events", written during #9 and revisable. Summary:

• The estimand is the instance level, not a phrase. The analysis instance grounds in a usdm:Estimand IRI as it grounds in an objective today. A correction falls out: the instance's free-string sentenceRole should bind to the typed Analysis.analysisRole (MainEstimator | SensitivityAnalysis | SupplementaryAnalysis).
• Two new roles — a library minor-version event: ice_handling (repeating, like covariate) and summary_measure, the latter binding to a method output via the summarizedByOutputClass hook (e.g. M.ANCOVA's contrasts_t becomes "difference in least-squares means").
• One smartphrase per strategy, strategy carried in anchors: SP_ICE_TREATMENT_POLICY ("regardless of {ice}"), SP_ICE_HYPOTHETICAL ("as if {ice} had not occurred"), SP_ICE_COMPOSITE ("with {ice} treated as {outcome}"), SP_ICE_WHILE_ON_TREATMENT ("using measurements taken prior to {ice}"), SP_ICE_PRINCIPAL_STRATUM ("in the stratum of participants in whom {ice} would not occur"). {ice} is a concept reference to a new registry kind IntercurrentEvent.
• Strategy phrases change the shape of the instantiated model, not just slice values — the first phrases to do so, and the main thing to scrutinise. TreatmentPolicy modifies nothing; Hypothetical inserts an imputation transformation; Composite redefines the variable via a derivation producing a composite endpoint concept; WhileOnTreatment adds a timing-bounded slice constraint; PrincipalStratum changes the population definition.
• Estimand-aware validation: one strategy phrase per declared ICE; exactly one MainEstimator per estimand; the summary phrase names a real method output; conditional template validity (e.g. SP_ICE_HYPOTHETICAL only where an imputation transformation exists to implement it).

Target prose:

Change from baseline in ADAS-Cog(11) at Week 24 in the efficacy population comparing treatment groups, as if discontinuation of study treatment had not occurred and regardless of use of concomitant AD medication, using ANCOVA … summarised as the difference in least-squares means, will be assessed as the primary estimand's main estimator.

The model side already exists

Verified on methods_02 (model/linkML/study_esap.schema.yaml, plus intercurrent-event-derivation.md for the ascertainment-versus-handling split):

Artefact	What it gives this extension
Estimand	USDM-referenced; carries variableOfInterest, analysisPopulation, interventions, intercurrentEvents
IntercurrentEvent	The ICE itself, referenced by id and never modified
IceAscertainment	eSAP-owned overlay: study-default strategy, event-driven ScheduleTimeline, and ascertainedBy — either OccurrenceCriterions naming a BC ▸ property ▸ code path, or a derivation. Strategy-independent, which is what makes the ICE trace a separate axis.
IceHandling	Reified (Estimand, IntercurrentEvent, Strategy) triple with implementedBy — precisely the hook requirement 3 needs, and why requirement 6 works without duplicating the ICE
IchE9R1Strategy	Typed enum: TreatmentPolicy, Hypothetical, Composite, WhileOnTreatment, PrincipalStratum
Analysis.analysisRole / AnalysisRole	MainEstimator / SensitivityAnalysis / SupplementaryAnalysis
Analysis.summarizedByOutputClass	The method-output hook for requirement 4

Notably IceHandling.implementedBy's own documentation already lists the per-strategy transformation patterns the proposed approach assumes (Composite → folding derivation, Hypothetical → imputation, TreatmentPolicy → omitted, WhileOnTreatment → censoring, PrincipalStratum → population subsetting). The model and phrase layers already agree on the semantics — this extension is a surface over them, not a redesign.

Suggested worked example — PrE0102

The breast-cancer SAP converted in #9 (smartphrase/SAP/) carries real intercurrent events rather than illustrative ones, in §4.4–4.5: everolimus discontinued for suspected toxicity while fulvestrant continues; treatment interruption capped at 3 weeks with permanent discontinuation beyond it; discontinuation at the subject's request; and disease progression itself. That supports a genuine Hypothetical-versus-TreatmentPolicy contrast on the same event, on a real document, in a therapeutic area where estimand framing is actively contested.

Known implementation consequences

• This one does touch the language packs. Unlike the Kaplan-Meier work in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9, which needed no new role, adding ice_handling and summary_measure is a library minor-version event — and because each pack's sentence_template enumerates role tokens explicitly, a role absent from a template is dropped from the rendered sentence entirely. All three packs (EN/FR/DE) need their word order revised: ice_handling after grouping, summary_measure after the method qualifiers.
• i18n stress test. The hypothetical strategy wants the German subjunctive — "als ob … nicht aufgetreten wäre" — inside the existing wird … untersucht verb bracket. Per-language phrase templates (decision D7) should accommodate this; it is a good test of whether they really do.
• New registry kind. IntercurrentEvent concepts, as Event was added for time-to-event endpoints in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9.
• Regression surface. Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 leaves three runnable gates (tools/verify.mjs with 69 pinned outputs across two studies, tools/build-library-subset.mjs --check, tools/verify-ui.mjs). All existing output must stay byte-identical except where a change is intended and justified.

Out of scope

• Estimand selection guidance — which strategy is appropriate clinically. This is about expressing a chosen estimand, not recommending one.
• The standard SAP document structure (owned by the sister project).
• Production authoring tooling, live Neo4j, formal schema/validation pipeline — as in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9.
• Multiplicity / MultiplicityStrategy, Hypothesis and the testing hierarchy: adjacent in the eSAP model, deliberately not bundled here.
• A generic formula resolver (tracked in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's out-of-scope list).

Dependencies and branching

• Branches off smartphrase_01, not main — this work builds directly on Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's engine generalisation (decision D10, the slot-name join), the STUDY_GRAPHS registry (D9), the proposed-additions overlay (D8) and the PrE0102 study layer. Base commit at time of writing: afffb84.
• Model side pinned to methods_02 (81a04b1 at time of writing; Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's library subset is generated from ffee5df).
• New phrases and roles are a library change, so the proposed-additions overlay pattern from D8 applies until they are accepted upstream.

Inherited open questions from #9

These are working-group decisions that bear on this extension and are not resolved yet:

1. Who accepts phrase and template contributions into the library, and what does that review look like? This extension proposes two new roles as well as phrases — a larger change than Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's single template.
2. Registration of currently-illustrative identifiers, including a term for Kaplan-Meier estimation.
3. Whether the identifier policy — resolve into USDM/ARS/STATO/NCIt wherever they cover the entity — becomes an AC/DC principle.

[metadatadriven]

Implementation plan — on estimands_01

Plan committed at smartphrase/PLAN-estimands.md (8d03732). Twelve TDD-ordered tasks, each ending green on all three gates. Branch fast-forwarded to smartphrase_01's tip (7e0b9fc) and the baseline verified before anything was written: verify.mjs 69 outputs PASS, build-library-subset.mjs --check PASS, verify-ui.mjs PASS.

Five deviations from the design note, and why

The issue says the proposed approach in DESIGN.md is revisable. Reading the code and the upstream schema turned up five places where it needs revising. These are settled in the plan rather than mid-task because each changes what gets built.

A. Roles cannot simply be "added". roleDefinitions lives in the generated subset, so new roles must arrive through the D8 overlay — but ctxOf merges only transformations and smartPhrases, and index.html reads LIB.roleDefinitions off the raw global at two places. That is the same bug class the UI gate caught in #9 (the proposed-provenance note reading the unmerged global). Task 1 fixes both, and new roles declare an insertion point rather than appending — appending would put ice_handling after covariate.

B. The sentence template needs optional groups. ICE clauses need commas: "…comparing treatment groups, as if X had not occurred, using ANCOVA…". Today an absent role leaves whitespace, which the normaliser collapses harmlessly — but literal punctuation would strand as ", ," on every one of the seven existing instances. Task 2 adds [...] optional groups to the template language first, and proves all 69 outputs byte-identical.

C. buildTrace needs a focus parameter. It keys on role and gathers data tokens from all bound concepts in role order, first-wins. ice_handling repeats, so two ICEs in one instance would both trace to whichever came first — and the endpoint concept's {dataset} would shadow both anyway. This is the largest engine change.

D. Summary-measure validation needs the template threaded through resolveBinding. Requirement 4 wants the summary to be an output the method provably produces; that check needs the active template, which binding resolution never receives.

E. analysisRole must be added beside sentenceRole, not substituted for it. The design note says the free-string sentenceRole "should bind to the typed Analysis.analysisRole". It cannot. AnalysisRole is per-estimand, so "a secondary analysis" is the MainEstimator of a secondary estimand — not a distinct enum value. The display string needs the estimand's rank as well as the role, so it is not derivable from the enum alone. The plan adds typed estimand + analysisRole and validates consistency (exactly one MainEstimator per estimand) instead of replacing anything. This also preserves every existing sentence and golden.

Two findings worth the working group's attention

The library's output-class vocabulary is not written for document prose. I found the authoritative source for requirement 4 — lib/vocabulary/output_class_templates.json on methods_02, carrying conceptId/name/label/statistics[] per output class. It is real pinned content, so it enters through the generator rather than the overlay. But upstream contrasts_t is labelled "T-based contrasts", and the target prose wants "the difference in least-squares means". Rendering the library label mid-sentence produces bad SAP English. Resolution: the language packs supply SAP-facing wording via an outputClasses overlay, exactly as they already do for concepts and methods — English is a language pack like any other. The upstream label stays visible in the inspect panel so the divergence is shown, not hidden.

Requirement 3 can be met with real upstream content, not invented content. T.LOCF_Imputation (derivation, M.ImputedValue_LOCF) is already in v0.7 and unused by the demo, so the Hypothetical strategy's implementedBy resolves to a genuine library transformation — added by widening SELECT_TRANSFORMATIONS, the legitimate route. And TreatmentPolicy correctly implements by nothing, which upstream IceHandling.implementedBy documents as "omitted". Having one strategy with an implementer and one without is the ideal pair to demonstrate, because it shows the model distinguishing "nothing needed" from "missing". The plan enforces this: a strategy the ICE declares no handling for is a resolution error, so prose cannot claim a handling the model can't deliver.

Worked examples — one real, one illustrative

PrE0102 carries a genuine, source-quoted ICE with a genuine strategy. SAP §4.3: "Subjects who discontinue everolimus/placebo because of suspected everolimus-associated toxicity should continue treatment with fulvestrant alone until disease progression", handled by "All subjects who have discontinued protocol therapy will be followed for survival and for progression, even if protocol therapy was discontinued because of toxicity or for other reasons." That is an explicit TreatmentPolicy stated in prose in a published SAP — precisely the claim this layer makes machine-readable. Its summary measure is source-grounded too (§7.7.2, median with 90% CI → output class median_survival).

The CDISC Pilot carries the illustrative pair, because requirement 6 — the same ICE handled two ways — is not in PrE0102. The SAP's own sensitivity analysis (§7.7.2) changes the population, not an ICE strategy. So rather than invent an estimand and quietly break the sapRef discipline every PrE0102 concept follows, the per-estimand override goes on the Pilot study with its concepts explicitly marked ILLUSTRATIVE — not from a source SAP. That keeps the "real document" claim honest where it is made.

Deliberately bounded

All five strategy phrases are authored, so the E9(R1) enum is fully covered. Only TreatmentPolicy and Hypothetical are exercised by worked instances. Composite, PrincipalStratum and WhileOnTreatment will be listed as authored but not exercised, each with what it would need — Composite wants a folding derivation, WhileOnTreatment a censoring derivation, neither of which exists in v0.7. SP_ICE_HYPOTHETICAL is deliberately excluded from the Kaplan-Meier template's valid-phrase set for the same reason: offering it would be prose the model cannot honour. That conditional template validity is the design note's own idea, now enforced.

Open questions carried into execution

1. No resolvable identifier for the E9(R1) strategies. The enum is eSAP-owned and a guideline is not a registry. I will search NCIt before falling back to illustrative, and will not invent one — same discipline as Kaplan-Meier in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9, which is still unresolved.
2. Is LOCF really the right implementer for a Hypothetical strategy? LOCF is a missing-data method; a hypothetical estimand strictly wants imputation under an explicitly stated alternative assumption. It is the only imputation derivation v0.7 affords, so I will flag the gap rather than paper over it.
3. The ascertainment criteria use illustrative BC paths. BC_DS_001/Disposition Event follows the OccurrenceCriterion shape, but those BC ids are not from a published BC library. I will check methods_02 for real ones first.
4. Two new roles is a library minor version. This is a bigger ask than Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's single template, and it lands on the governance question already open there — who accepts role-level library changes.

Estimated shape: ~12 commits. Happy to start on your word, or to adjust the deviations above first — E in particular is a modelling judgement, not a mechanical fix, and it is the one I would most want checked.

[metadatadriven]

Complete — estimands and intercurrent events on estimands_01

All twelve planned tasks executed and verified. Twelve commits, 8d03732..6b5c91d. Entry point unchanged: double-click smartphrase/demo/index.html.

node smartphrase/tools/verify.mjs                          # 86 pinned outputs
node smartphrase/tools/build-library-subset.mjs --check     # generated file unmodified
NODE_PATH=<dir>/node_modules node smartphrase/tools/verify-ui.mjs   # real DOM

All three green, working tree clean.

What you can now do in the demo

The CDISC Pilot primary passage carries a full ICH E9(R1) estimand:

Change from baseline in Alzheimer's Disease Assessment Scale - Cognitive Subscale (11 items) (ADAS-Cog(11)) at Week 24 in the efficacy (intent-to-treat) population comparing treatment groups, as if discontinuation of study treatment had not occurred and regardless of use of concomitant AD medication, using ANCOVA with 95% confidence intervals adjusting for baseline ADAS-Cog(11), summarised as the difference in least-squares means, will be assessed as the primary analysis.

Four of the five attributes were already carried by v0.7 roles without anyone designing for it. The two new roles supply attributes 4 and 5. Both German and French render it correctly, with the ICE clause inside the German wird … untersucht bracket and the hypothetical in Konjunktiv II.

Clicking an ICE phrase traces on a different axis. Not to an analysis value but through the occurrence criterion that ascertains it: BC_DS_001/Disposition Event → (occurred, when) → ADSL.DCSREAS → adsl.xpt. Click the second ICE chip and you land in adcm.xpt instead — two chains from one sentence. That ascertainment is strategy-independent, exactly as ascertainedBy is separate from implementedBy upstream.

The reuse grid now shows the per-estimand override. Two ADAS-Cog cards, same EST.PRIMARY, same intercurrent event, different strategy — Hypothetical on one, TreatmentPolicy (override) on the other. One event handled two ways, no duplicated event, because IceHandling is a reified (estimand, event, strategy) triple.

PrE0102's intercurrent event is real. The ICE, its strategy and its summary measure are all quoted from the source SAP: §4.3 for the everolimus discontinuation and for the treatment-policy handling ("All subjects who have discontinued protocol therapy will be followed for survival and for progression, even if protocol therapy was discontinued because of toxicity"), §7.7.2 for the median-with-90%-CI summary. The Pilot's two events are constructed and marked ILLUSTRATIVE — not from a source SAP.

Requirement 3 is enforced, not asserted

A strategy resolves to what operationalises it, and the engine refuses an ICE phrase whose event declares no handling for the strategy asserted. Hypothetical resolves to T.LOCF_Imputation — real upstream v0.7 content added by widening the generator's selection, not invented. TreatmentPolicy resolves to nothing, which is correct: data used as observed, which IceHandling.implementedBy documents as "omitted". Having one strategy with an implementer and one without is the useful pair, because it shows the model distinguishing "nothing needed" from "missing".

Requirement 4 likewise: a summary measure is rejected unless the named output appears in both the template's declared outputs and the bound method's own outputs[]. median_survival on an ANCOVA template is an error, with the message naming what the template does declare.

Deliberately bounded — please read this bit

All five strategy phrases are authored, so the enum is covered, but only two are exercised:

Strategy	Exercised	Why not
TreatmentPolicy	yes — PrE0102 (real) and Pilot	—
Hypothetical	yes — Pilot, via T.LOCF_Imputation	—
WhileOnTreatment	no	needs a censoring derivation; none in v0.7
Composite	no	needs a folding derivation and an Outcome concept kind
PrincipalStratum	no	needs counterfactual population subsetting

SP_ICE_HYPOTHETICAL is deliberately excluded from the Kaplan-Meier template's valid-phrase set for the same reason — offering it there would let an author write prose the model cannot honour.

Corrections to the design note, and findings

Five deviations were flagged in the plan comment and all held up in implementation. Two are worth the working group's time:

1. analysisRole cannot replace sentenceRole (D15). The design note said the free-string sentenceRole "should bind to" the typed Analysis.analysisRole. It cannot: AnalysisRole is defined per estimand, so "a secondary analysis" is the MainEstimator of a secondary estimand, not an enum value. Rendering that string needs the estimand's rank as well as the role. So both are carried and the pair is validated (exactly one MainEstimator per estimand) rather than one derived from the other. Every existing sentence and golden survived unchanged as a result. Whether sentenceRole should eventually be retired in favour of a rendering rule computed from (rank, role) is your call, not mine.

2. The library's output vocabulary is not written for document prose (D14). I found the authoritative source for requirement 4 — lib/vocabulary/output_class_templates.json, real pinned content, so it enters through the generator. But upstream contrasts_t is labelled "T-based contrasts", and the prose wants "the difference in least-squares means". Rendering the library label mid-sentence produces bad English. SAP wording now lives in the language packs, English included, and the inspect panel shows the upstream label alongside so nothing looks renamed.

3. The i18n stress test found a real limit of the model. German assigns a case to the ICE noun phrase and it differs by strategy: "unabhängig von …" and "vor …" want the dative, "als ob … wäre" wants the nominative — and a concept carries one name. Per-language phrase templates cannot fix this; it needs per-case declined forms the registry does not carry. Worked around by making all five strategy templates nominative-compatible. A language with richer case marking would strain it further.

What the process caught

• The same bug class as Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's proposed-provenance note, again. ctxOf merged only transformations and phrases, and index.html read LIB.roleDefinitions off the raw generated global — so proposed roles would have been invisible in the browser. All library reads now go through ctx.lib.
• The sentence template needed optional groups before anything could use them. An ICE clause needs commas, and literal punctuation beside an absent role stranded as ", ," on all seven pre-existing instances. [ … ] groups elide with their clause. A probe test demonstrates the failure it prevents.
• Two holes in the gate itself, both found by an ICE chain rather than by inspection: the per-instance trace loop ran for roles the instance did not use — producing ADQSADAS.ITTFL, the endpoint's dataset crossed with the population's flag, and pinning it as a golden — and the "no unfilled tokens" check only looked for ⟨name⟩, so a surviving {token} passed silently. Both fixed.
• Two prose defects found by reading rendered output, the same way Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's "estimation estimation" was caught: an ICE clause opening a comma it never closed, and "intervals , summarised" where an elided group met an empty covariate role.
• Test fixtures were coupled to live data. Three blocks pushed ICE phrases onto instances[0]; once that instance had its own, "push two ICEs" silently became "push two more". Fixtures now state their own preconditions.
• REFERENCE.md §6 had been stale since Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 — still describing the phrase-OID keying that D10 replaced. Rewritten.

New tool: tools/diff-goldens.mjs. Goldens are captured from behaviour, so the question after --update-goldens is never "are they right?" but "did anything move that I did not intend?" — which a 35KB textual JSON diff cannot answer. It reports one line per changed leaf, so an intended addition reads as N × ADDED. Every recapture here was reviewed with it; the Task 9 recapture confirmed zero CDISC Pilot sentence changes.

Open questions for the working group

1. No resolvable identifier for the ICH E9(R1) strategies. The enum is eSAP-owned and a guideline is not a registry. Listed in the standards table as AC/DC ids flagged illustrative rather than omitted — I did not invent one. (The Kaplan-Meier identifier from Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9 is still open too.)
2. Is T.LOCF_Imputation the right implementer for a Hypothetical strategy? It is the only imputation derivation v0.7 affords, but LOCF is a missing-data method and a hypothetical estimand strictly wants imputation under an explicitly stated alternative assumption. The mechanism is right; I am asking about the content.
3. Who accepts role-level library changes? This is a bigger ask than Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9's single template: two new roles, six phrases, and a widened valid-phrase set on an existing released template — a library minor version, which forced all three language packs' sentence templates to change. It lands squarely on the governance question already open in Smartphrase: demonstrate SAP <-> AC/DC model linkage (PoC for the working group) #9.
4. Ascertainment criteria use illustrative BC paths. BC_DS_001/Disposition Event follows the OccurrenceCriterion shape faithfully but those BC ids are not from a published BC library.

Not included, deliberately

Multiplicity, MultiplicityStrategy and Hypothesis — adjacent in the eSAP model, not bundled. Estimand selection guidance: this expresses a chosen estimand, it does not recommend one. And the generic formula resolver remains out of scope from #9.

WALKTHROUGH.md has a ~2-minute estimand beat and is now ~15 minutes, with drop-order guidance if time is short. Two asks were added, covering questions 2 and 3 above.

[metadatadriven]

Correction — the per-estimand override above was modelled wrong

Two commits after the completion comment (c1ab386, eddd5a6) correct it. The description of the override in that comment is superseded — please read this before the walkthrough.

What was wrong

I reported "two ADAS-Cog cards, same EST.PRIMARY, same intercurrent event, different strategy — Hypothetical on one, TreatmentPolicy (override) on the other", encoded as AC.SENS.ADASCOG.TP being a SensitivityAnalysis of the primary estimand.

That is not what changing an ICE strategy means. Intercurrent-event handling is ICH E9(R1) attribute 4. Change it and you have changed the question — so you have a different estimand, addressed by its own main estimator. A sensitivity analysis varies things that are not estimand attributes.

IceHandling's own documentation on methods_02 says exactly this, and I had quoted it in the issue without reading it closely enough:

"…e.g., primary estimand uses Hypothetical while a sensitivity estimand uses TreatmentPolicy on the same ICE."

Requirement 6 in this issue says the same thing in the same words — "for a sensitivity estimand". I implemented it as "for a sensitivity analysis". The model corrected me, not the other way round.

Now: AC.SENS.ADASCOG.TP is the MainEstimator of EST.SENS.TP, a sensitivity estimand referencing the same two event concepts rather than copying them. Requirement 6 — one event, two handlings, no duplicated event — is still met, and met the way it was actually asked for.

For contrast, PrE0102's ITT analysis remains a genuine SensitivityAnalysis of EST.PFS: it varies the analysis set, which is not an estimand attribute.

A second problem the same review found

Asked what estimand examples the demo contained, I found AC.SUPP.ADASCOG.WK16 — a supplementary analysis of EST.PRIMARY — emitting handlesIntercurrentEvent: []. That reads as "this analysis handles no intercurrent events", which is a materially different claim from "handles them as standard".

The cause was a shortcut: intercurrent events were derived from an instance's phrases, so an estimand's ICE set was whatever the analysis you happened to be looking at declared, and nothing could detect an omission.

Estimands now live in a study-level registry and declare their own intercurrentEvents[] scope (per Estimand.intercurrentEvents), referenced by id from the analyses addressing them. Scope belongs to the estimand because it is part of the question; strategy still comes from the analysis's phrase, falling back to the event's own icheStrategy. So a strategy is never stored twice, and silence now correctly means "handled as standard", marked source: "studyDefault" and labelled (inherited) in the UI.

That also removed real duplication — EST.PRIMARY had been written out identically three times, EST.PFS twice.

Current state

CDISCPILOT01
  EST.PRIMARY        (primary)     ICEs: TRT_DISCONT, CONMED
      MainEstimator          AC.PRIMARY.ADASCOG      Hypothetical [phrase] · TreatmentPolicy [phrase]
      SupplementaryAnalysis  AC.SUPP.ADASCOG.WK16    both [studyDefault, inherited]
  EST.SENS.TP        (sensitivity) ICEs: TRT_DISCONT, CONMED
      MainEstimator          AC.SENS.ADASCOG.TP      TreatmentPolicy [phrase, OVERRIDE] · TreatmentPolicy [phrase]
  EST.SECONDARY.NPIX (secondary)   ICEs: none declared

PRE0102
  EST.PFS            (primary)     ICEs: TOX_DISCONT
      MainEstimator          AC.PRIMARY.PFS
      SensitivityAnalysis    AC.SENS.PFS.ITT         ← varies the ANALYSIS SET, so genuinely one estimand
  EST.OS / EST.TTP   (secondary)   ICEs: none declared

Six estimands, not the four implied earlier. New validation: every instance resolves to a registered estimand; every estimand is addressed by at least one analysis and states its scope explicitly (an empty array is a valid answer, an absent one is not); every declared ICE is accounted for; no analysis handles an event outside its estimand's scope.

A distinction this exposed, worth a working-group view

The claim that four of five E9(R1) attributes were already covered leans on population mapping to attribute 3. Strictly, attribute 3 is the estimand's target population — which patients the question is about — whereas SP_POPULATION binds an analysis set (ITTFL, EFFIFL). They are related but not the same thing, and the difference is exactly what makes PrE0102's ITT case a sensitivity analysis rather than a second estimand.

I have not restructured this: separating them would change every existing sentence, and it is a modelling call rather than a fix. Recorded as D16 in smartphrase/DESIGN.md.

Since then

Issue #12 (document anchoring) has also landed on this branch and touches estimands: each now carries a verified sapRef, and the "(SAP 3.1, 7.7.2)" section references I had embedded in estimand labels during this issue are gone — #12 named that convention as an anti-pattern, correctly, and it was mine.

estimands_01 now carries this issue, that correction, and #12. It remains unmerged.