io.github.wei-ai-lab/clinical-trial-design

Use when the user wants two-arm Phase 2/3 sample size with a BINARY primary endpoint — responder rate, fixed-time mortality, ORR, ACR20, remission/cure, anything that resolves to event-or-no-event per subject. Set comparison='superiority' (default), 'non-inferiority' (then provide ni_margin), or 'equivalence' (then provide equiv_margin; fixed-sample only). Set design_class='group-sequential' for interim analyses with alpha-spending. Supply an optional `operational` block (any 0–4 of accrual_rate, accrual_duration, follow_up_duration, total_trial_duration) and the kernel fills in the rest. For two or more co-primary binary endpoints with multiplicity control, use design_co_primary instead.

Multi-endpoint co-primary trial design with multiplicity control. Use when a confirmatory trial requires positive results on two or more primary endpoints (oncology PFS+OS, CV death+HHF, etc.). Strategies: fixed-sequence (hierarchical, full alpha per test, the canonical approach for ordered co-primary), alpha-split (partition alpha by weights), bonferroni (equal alpha-split). Each endpoint is sized at its effective alpha via the matching design_<type> wrapper; total N is the max across endpoints. For graphical multiplicity (Maurer-Bretz with alpha recycling), use `design_graphical_multiplicity` instead.

Use when the user wants two-arm Phase 2/3 sample size with a CONTINUOUS primary endpoint — change from baseline in a measured score (HAM-D-17, PANSS, HbA1c reduction, eGFR slope, BP), QoL scale, biomarker level. Provide mean_diff (assumed treatment - control mean) and the common within-arm sd. Set comparison='superiority' (default), 'non-inferiority' (provide ni_margin), or 'equivalence' (provide equiv_margin; fixed-sample only). Set design_class='group-sequential' for interim analyses with alpha-spending. Supports the same `operational` block as design_binary and design_survival. For multi-endpoint designs, use design_co_primary.

Graphical multiplicity (Maurer-Bretz) trial design with alpha recycling. Use when a confirmatory trial has 2+ hypotheses (mixed primary + secondary, dose-response, parent + derived endpoints) where a graph-based procedure preserves family-wise alpha better than Bonferroni. Validates the transition matrix (Rule-3 + row sums) and constructs a graphicalMCP graph object. Sizes each hypothesis at its worst-case alpha; total N is the max across hypotheses. For simpler co-primary or multi-population designs use design_co_primary or design_multi_population instead.

Multi-population (subgroup) trial design with multiplicity control. Use when a confirmatory trial tests the same endpoint in multiple populations — biomarker-positive subgroup + ITT, nested PD-L1 strata, etc. Pick relation='nested' (the canonical case: TPS≥50 ⊂ TPS≥20 ⊂ ITT, all patients enroll into the broadest, total N driven by largest implied-enrolled across strata) or 'disjoint' (strata enrolled separately, total N = sum). Strategies: fixed-sequence (hierarchical), alpha-split, bonferroni. For graphical multiplicity (Maurer-Bretz with alpha recycling between populations), use design_graphical_multiplicity.

Render a clinician-readable design summary in markdown, Word, or PDF. Reasoning chain (when populated on the result) appears as a table; sponsor_confidential entries trigger a redaction warning at the top. Sections: title, design overview, key inputs, headline output, GS analysis plan, reasoning chain, method + version. Default output is markdown text; format='docx' returns a native Word file path (officer); format='pdf' renders via rmarkdown + Pandoc.

Use when the user wants Phase 2/3 sample size with a TIME-TO-EVENT primary endpoint — overall survival, PFS, time to first hospitalization, time to progression, time to a CV composite, etc. Choose the test statistic via `model`: 'ph' (default — log-rank under proportional hazards, gsDesign::nSurv / gsSurv), 'maxcombo' (delayed effect / non-proportional hazards via Fleming-Harrington combo), 'rmst' (restricted mean survival to landmark tau), 'milestone' (survival probability at landmark t*), 'wlr' / 'ahr' (weighted log-rank / average HR for GS NPH). Set design_class='group-sequential' for interim analyses with alpha-spending. Always provide control_median + the relevant effect parameter (hazard_ratio for PH; delay_months + post_delay_hr for NPH models). The `operational` block can solve any 0–4 of {accrual_rate, accrual_duration, followup_duration, total_trial_duration} via the events-tied uniroot. For two co-primary TTE endpoints (PFS+OS) use design_co_primary; for nested PD-L1 strata or biomarker subgroup + ITT use design_multi_population.

Load a benchmark corpus case, re-run the matching design wrapper with its inputs, and diff computed sample_size_total / events_total against expected within the case's tolerance.

Monte Carlo simulation cross-check for a designr result. Closed-form simulation (rbinom / rnorm / rexp) drives empirical power and Type I error estimates against the design's target alpha and power. Supports fixed and group-sequential families on binary, continuous, and PH survival endpoints. NPH families (MaxCombo, RMST, milestone) and equivalence designs are not yet supported and return a clean error.