Proposal: extend simulation framework to binary and normal endpoints

Read the existing sim_pw_surv() API and its enrollment, allocation, stratification, and data-cut helpers to understand the shared trial bookkeeping described in the proposal. Then review issue #258 for the related multiple-testing context. Done would require agreement on a participant/outcome schema and callback contract, followed by staged binary and normal generators, availability cuts, and evaluation examples; the issue leaves those design decisions open.

Motivation

Could simtrial's simulation framework be extended to binary and normally distributed continuous outcomes, while retaining its existing time-to-event workflows?

We are developing a concept for a complete design and analysis package for weighted parametric group sequential testing in gsDesignWP. Useful evaluation examples include multiple treatments versus a common control, nested or overlapping biomarker populations, and repeated analyses. simtrial already provides a useful foundation for enrollment, stratification, randomization, data cuts, and time-to-event simulation. Reusing these concepts for other outcomes would avoid building a separate trial simulator in each design package.

This is a feature proposal for discussion, not a request to implement everything at once or a claim that the current API supports these endpoints.

Suggested initial scope

• Binary outcomes: Bernoulli risks by treatment and disjoint population stratum, initially one prespecified assessment per participant. Supply baseline risks and treatment effects with explicit direction and scale, so analysis callbacks can evaluate risk difference or risk ratio (usually log risk ratio for asymptotic methods). Validate that implied probabilities lie in [0, 1].
• Normal outcomes: means and standard deviations by treatment and stratum, initially one assessment per participant. Keep the generating model separate from the chosen known-variance, pooled-variance, or unequal-variance analysis.
• Outcome availability: enrollment dates, assessment delays, and a declared missingness mechanism. Interim cuts should use available outcomes or a prespecified calendar/sample-size rule, rather than reinterpreting TTE event counts. Unobserved binary outcomes must not silently become failures, and unavailable observations must not count toward information.
• Shared trial structure: stable participant IDs, treatment allocation, and disjoint population-membership strata. A tested population can be a union of these strata. Generate each participant and shared control outcome once, then reuse the same records across populations and cuts so the intended dependence is preserved.

Endpoint-specific generators and cut helpers could share common trial bookkeeping and analysis callbacks. They need not be forced into the existing sim_pw_surv() arguments or a TTE event/censoring representation. Keep any new interface backward compatible with current TTE calls.

Analysis and results

Support external analysis callbacks returning estimates, standard errors, information when defined, test statistics or exact p-values, and method identifiers. Preserve simulation, analysis, endpoint, population, contrast, and hypothesis identifiers in results. Multiple tests at a cut are relevant; this relates to #258, while adding outcome families is a separate extension.

Exact-binomial methods should be usable as callbacks where appropriate. However, adding a binary generator does not establish an exact sequential or multiplicity-adjusted test: two-arm risk-difference/risk-ratio nulls, nuisance parameters, discreteness, and shared controls require separate statistical methods. Those testing and graphical-recycling rules can remain the responsibility of the calling design/analysis package.

For multiple endpoints on the same participants, joint generation should require an explicit dependence model. Unknown endpoint correlation should not silently become independence. Single-endpoint simulations would be a useful first release.

Evaluation and staged delivery

1. Add and document single-assessment binary and normal generators using the shared enrollment/allocation/stratum concepts.
2. Add calendar and outcome-availability cuts, plus fixed and group sequential examples.
3. Demonstrate a shared-control example and a nested-population example, reporting marginal power, appropriate joint power/FWER, stopping, and expected sample size or observed outcomes.
4. Check moments, allocation, cut bookkeeping, and simple analytic or exact benchmarks; include global and relevant partial-null scenarios with Monte Carlo uncertainty. Preserve reproducibility across sequential and parallel execution using the package's existing RNG conventions.

In gsDesignWP, deterministic design and boundary calibration would remain the default. simtrial would be an optional tool for finite-sample and operational evaluation, not a required Monte Carlo backend for routine numerical integration.

Does this belong in simtrial's intended scope? If so, an initial agreement on the common participant/outcome schema and callback contract would be useful before choosing new function names or a broader API.