Short course
Simulating Modern Clinical Trial in R
A Versatile Framework for Complex and Adaptive Trial Designs
Empowering clinical trial design with simulations
Han Zhang
Innovative Statistical Science, Astellas
zhangh12.github.io/TrialSimulator
2026 NIC-ASA and ICSA Midwest Chapter
Joint Fall Meeting
October 15, 2026 · Northbrook, IL
Before we start
Install TrialSimulator
From CRAN
Prebuilt binary on Windows and macOS
install.packages("TrialSimulator")
From GitHub
Development version, built from source
if(!requireNamespace("remotes", quietly = TRUE)){
install.packages("remotes")
}
remotes::install_github(
"zhangh12/TrialSimulator",
dependencies = TRUE,
upgrade = "never"
)
Needs a compiler: Rtools on Windows, Xcode Command Line Tools on macOS.
Copy the code from the package website
zhangh12.github.io/TrialSimulator
Disclaimer: The views and opinions expressed in this presentation are those of the presenter and do not necessarily reflect the official policy or position of Astellas Pharma Inc. or any of its affiliates.
Why simulate · FDA guidance, 2019
Adaptive designs: FDA expects simulation
Adaptive Designs for Clinical Trials of Drugs and Biologics
Guidance for Industry
FDA (CDER, CBER), November 2019
§VI.A Simulations in Adaptive Design Planning, p. 18
⋯
Why simulate · FDA draft guidance, 2026
Bayesian designs: simulate widely, show the code
Use of Bayesian Methodology in Clinical Trials of Drug and Biological Products
Draft Guidance for Industry
FDA (CDER, CBER), January 2026
§IV.B.1, p. 8 · §VIII.A, p. 22
§VIII.A Documenting plans for Bayesian analyses · p. 22
Why simulate · operating characteristics
Crossover after a promising interim
One OS trial, two looks
600 patients, true HR 0.7. Final at 330 deaths, interim at 30%, 50% or 70% of them. Efficacy is tested at both looks, ITT; the trial never stops at the interim.
If the interim is promising (observed HR below 0.8), control patients who progress are offered the experimental drug; those who accept live their remaining survival on its hazard. Otherwise everybody stays on the randomized arm.
deaths so far
165 (50%)
330 (100%)
control patients of this trial
on control
progression
death
switched to experimental
death had it not switched
1
dies before the interim
2
progressed before the interim
3
progresses after the interim
4
declines the switch
5
enrolls after the interim
0
6
12
18
24
30
36
42
calendar time (months)
interim · 165 deaths (50%)
final · 330 deaths
observed HR < 0.8: open crossover
otherwise: no crossover
← crossover opens
Two looks. The interim reads 165 deaths (50%), the final 330. Efficacy is tested at both; the trial never stops at the interim.
At the interim: a promising result (observed HR below 0.8) opens crossover; otherwise nobody switches.
Control patients on study at the interim, and those enrolled later, can be offered the switch when they progress.
60% accept. They switch at progression, or at the interim if they progressed before it; their remaining survival follows the experimental hazard.
ITT: switchers still count as control at the final look. How much power is left?
Why simulate · more designs
Two more choices that only simulation can price
Graphical testing in a group sequential design
Futility on ORR, efficacy on OS
H1
PFS · biomarker+
H2
PFS · all-comers
H3
OS · biomarker+
H4
OS · all-comers
initial α₁
initial α₂
initial 0
initial 0
α₁ + α₂ = α; each hypothesis has its own two-look boundary
γ
γ
1 − γ
1 − γ
1
1
Which split α₁/α₂, which γ? Power of each hypothesis depends on the PFS–OS correlation, the biomarker prevalence and when each look comes: simulate every candidate.
Interim when 200 patients have a 3-month ORR: stop if the ORR difference (experimental − control) is below a bound. Final OS log-rank at 380 deaths. Which bound?
Effective drug: ORR 35% vs 20%, OS median 16 vs 12 months. Futile drug: 20% and 12 months in both arms. ORR and OS correlated. 2,000 trials each.
100%
50%
0%
-5%
0
+5%
+10%
+15%
futility bound on the ORR difference
no futility look: 82%
82
82
79
68
45
overall OS power, effective drug
17
47
79
95
99
stops a futile drug at the interim
Bound 0: stops 47% of futile trials for 0.5 points of power. +10%: stops 95%, but costs 14 points.
Why it is hard · simulation code
Simulation code is easy to start and hard to trust
generate_trial_data <- function(...){
...
}
analyze_trial_data <- function(...){
...
}
arg1 <- ...
...
argk <- ...
run_simulation <- function(n, ...){
for(i in 1:n){
dat <- generate_trial_data(...)
res <- analyze_trial_data(dat, ...)
# update output with res
}
summarize(output)
}
The usual hand-written simulation
1 Data generation by hand
Several endpoints and arms, enrollment, dropout, and the data cut at every look: when do 150 events happen, who is censored then. Re-coded for each design.
2 Analysis coded look by look
Each look needs its own data cut, tests, estimates and boundaries (alpha spending, multiplicity), written and checked by hand.
3 A long list of parameters
Distributions, boundaries and timings as loose arguments with ad hoc names: hard to manage and to vary across scenarios.
4 Hard to reuse, check and submit
A small design change means a new script; a reviewer has to read all of it. The FDA 2026 draft asks for the simulation code in the report.
5 Adaptation: the two functions cannot be decoupled
In a complex adaptive design, the data still to be generated depend on the analysis of the data already observed. An interim result can drop an arm, change the allocation ratio, add patients or narrow the population, and the remaining patients are generated under the new design.
generate
patients up to the look
analyze
the data at the interim
adapt
the design: arms, ratio, size
changes how the remaining patients are generated
This feedback is the adaptation. Inside one replicate, generation and analysis call each other; they cannot be two functions run one after the other.
Why it is hard · existing tools
Existing tools: validated, but closed or narrow
Commercial platforms
East Horizon (Cytel) · FACTS (Berry) · ADDPLAN
+ Broad, validated, familiar to regulators.
− Closed engines. Your R code plugs only into vendor-defined integration points, and which ones you get depends on the design and endpoint. Licensed.
Validated open-source packages
gsDesign · gsDesign2 · rpact · simtrial
+ Open, tested, widely used for group sequential designs.
− Design-first. gsDesign and gsDesign2 compute designs analytically; rpact simulates one endpoint type per function through fixed hooks; simtrial focuses on time-to-event.
Method-centric packages
e.g. MAMS, adaptr, and the CRAN Task View
+ Each solves its own design family well.
− One family each. “The majority of the provided software is very specialized” (Meyer et al., Trials 2021).
The gap: an open, general engine where any design is assembled from parts, every patient is simulated, and the code reads like the protocol.
Example · sample size re-estimation
Two looks, each with its own trigger
0
200
400
600
800
1000
0
12
24
36
48
60
Calendar time (months)
Enrolled
ORR readouts
PFS events
OS events
interim · 21.15
final · 41.34
Interim analysis
Interim analysis · month 21.15
Triggered when
200 PFS events and 300 ORR readouts (read 6 months after entry), whichever comes later
max(19.41, 21.15) = 21.15
What happens
Re-estimate the sample size: 600 → 800 patients
Interim analysis · month 21.15
200 PFS events and 300 ORR readouts; sample size 600 → 800
Final analysis
Final analysis · month 41.34
Triggered when
400 OS events or month 48, whichever comes first
min(41.34, 48) = 41.34
What happens
Lock the data; final test; the trial ends
Condition system · the building blocks
Time and enrollment trigger milestones
Each condition resolves to the earliest calendar time it holds; if it can never hold, t = ∞ with a warning.
Condition system · eventNumber()
One function counts events or readouts
Time-to-event endpoint
eventNumber('pfs', n = 340)
Counts observed events: 340 PFS progressions or deaths, after dropout
340
0
12
24
36
t = 22.1 months
Any other endpoint
eventNumber('orr', n = 300)
Counts non-missing readouts: 300 ORR values, each ready 6 months after randomization (gray: enrollment)
300
0
12
24
36
t = 16.3 months
Same call, two meanings: events for a time-to-event endpoint, non-missing readouts for any other.
Condition system · what gets counted
Count only the arms and patients you mean
900
450
0
340
0
12
24
36
48
PFS events · calendar time (months)
22.1
29.0
283 events at most → t = ∞
35.9
all arms
arms = c('pbo', 'high')
arms = 'pbo'
biomarker == 'positive'
eventNumber(
endpoint = 'pfs',
n = 340
)
eventNumber(
endpoint = 'pfs',
n = 340,
arms = c('pbo', 'high')
)
eventNumber(
endpoint = 'pfs',
n = 340,
arms = 'pbo'
)
eventNumber(
endpoint = 'pfs',
n = 340,
biomarker == 'positive'
)
→ t = 22.1
Counted on every arm still in the trial.
→ t = 29.0
Only placebo and high dose count; the low dose is ignored.
→ t = ∞
Placebo alone peaks at 283 events, so the milestone never fires and a warning is raised.
→ t = 35.9
Unnamed arguments in … filter the rows, here on a baseline endpoint: 450 positive patients.
calendarTime(time)
enrollment(n, ...,
arms = NULL,
min_treatment_duration = 0)
eventNumber(endpoint, n, ...,
arms = NULL)
... keeps the rows matching any dplyr::filter() condition, e.g. on a baseline endpoint.
arms = NULL counts arms still in the trial; an arm you list is counted even after it is removed, with a warning.
Condition system · time after randomization
Treatment exposure and readouts shift the clock
enrollment(n = 400, min_treatment_duration = 3)
400 patients randomized, each treated for at least 3 months
900
400
0
0
6
12
18
24
+3 months
t = 13.3 months
t = 13.3 + 3 = 16.3 months
eventNumber('orr', n = 300) # readout = c(orr = 6)
300 non-missing ORR readouts, each 6 months after randomization
900
300
0
0
6
12
18
24
6-month readout
t = 16.3 months
Dropout counts too: a patient who drops out before an event or readout never adds to the count.
Condition system · vignette recipes
Read a compound condition like a sentence
(enrollment(n = 500) & eventNumber(endpoint = 'os', n = 200)) | calendarTime(time = 12)
“500 patients in and 200 OS events — or 12 months, whichever comes first.”
month 12
200th OS event · 20.9
500th patient · 16.6
0
36 mo
min( max(16.6, 20.9), 12 ) = 12
The 12-month cap fires first; neither count is waited for.
calendarTime(time = 6) & (eventNumber('os', n = 320) | eventNumber('pfs', n = 480))
“At least 6 months in, and then either 320 OS or 480 PFS events.”
month 6
320th OS event · 27.4
480th PFS event · 27.9
0
36 mo
max( 6, min(27.4, 27.9) ) = 27.4
Six months is only a floor; the first of the two event counts decides.
Every recipe plugs straight into milestone(name = 'final', when = …, action = …), and the engine solves it for every replicate.
Chapter · Endpoints and arms
Endpoints and arms: define, combine, check
Say what each patient's data look like; TrialSimulator draws them, and printing an arm checks them.
endpoint()
One call defines one or more endpoints with any generator whose first argument is n; its other arguments go through ...
type
'tte' (time + event), 'non-tte' (a value at a readout time) or 'baseline' (known at randomization).
arm()
Name the arm, add inclusion criteria if needed, then add_endpoints(). Printing it summarizes 10,000 simulated patients.
Vignettes · scan for details
Define Time-to-Event Endpoints
defineTimeToEventEndpoints
Define Non-Time-to-Event Endpoints
defineNonTimeToEventEndpoints
Define Longitudinal Endpoints
defineLongitudinalEndpoints
Define and Summarize Arms in Clinical Trials
defineArms
Endpoints and arms · signatures
endpoint() and arm(), checked by printing
endpoint(name, type, readout = NULL, generator, ...)
arm(name, ...)
Arguments
endpoint()
name
Name(s) of the endpoint(s); one call can define several.
type
'tte', 'non-tte' (continuous, binary, categorical, repeated measures) or 'baseline' (non-tte, known at randomization).
readout
Named numeric vector: time from randomization to each non-tte value, e.g. c(orr = 2). NULL if all are tte; leave baseline endpoints out.
generator
Random number generator, first argument n. Returns n values, or a data frame of n rows: a column per name, plus <name>_event for each tte endpoint.
...
Arguments passed to generator.
arm()
name
Label of the arm in the generated data, e.g. in get_locked_data(); no '@' or ';'.
...
Inclusion criteria: dplyr::filter-style conditions on the endpoints. None: all generated patients are used.
arm$add_endpoints()
...
One or more objects returned by endpoint().
Viewer
Endpoints (1)
ttp
No
Variable
Stats / Freqs
Graph
1
ttp
[time-to-event]
Median time: 6.32
Events: 10000
Missing: 0 (0%)
2
ttp_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
Viewer
Arm Name: treatment
Endpoints (1):ttp
No
Variable
Stats / Freqs
Graph
1
ttp
[time-to-event]
Median time: 6.32
Events: 10000
Missing: 0 (0%)
2
ttp_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
ttp <- endpoint(name = 'ttp', type = 'tte',
generator = rweibull,
shape = 1.5, scale = 8)
trt <- arm(name = 'treatment')
trt$add_endpoints(ttp)
my_gen <- function(n, par1, par2){
tte_ep <- ... # n event times (pseudo-code)
non_tte_ep <- ... # n values (pseudo-code)
age <- ... # n ages at randomization
data.frame(tte_ep = tte_ep,
tte_ep_event = 1, # 1 = event, 0 = censored
non_tte_ep = non_tte_ep,
age = age)
}
eps <- endpoint(name = c('tte_ep', 'non_tte_ep', 'age'),
type = c('tte', 'non-tte', 'baseline'),
readout = c(non_tte_ep = 3),
generator = my_gen,
par1 = 0.5, par2 = 2)
ttp <- endpoint(name = 'ttp', type = 'tte',
generator = rweibull,
shape = 1.5, scale = 8)
trt <- arm(name = 'treatment')
trt$add_endpoints(ttp)
> set.seed(1)
> ttp
> set.seed(1)
> trt
A time-to-event endpoint needs no readout.
Any R random number generator works, or one you write yourself.
A custom generator: its first argument is n, the number of patients to draw.
Its other arguments are yours to name; their values arrive through the ... of endpoint().
The body draws n values for each endpoint, any way you like (pseudo-code here).
It returns a data frame of n rows: one column per name.
NAMING RULE a time-to-event endpoint x needs one more column, x_event: the event indicator (1 = event, 0 = censored). Here tte_ep → tte_ep_event.
Types follow the names. Only non_tte_ep gets a readout: age is 'baseline', known at randomization (readout 0, set for you).
Back to rweibull: shape and scale travel through ..., and ttp_event = 1 is added for you.
Typing the endpoint prints a summary of 10,000 draws. Weibull median = scale × (log 2)^(1/shape) = 6.27; the table shows 6.32.
type = 'tte' adds ttp_event: all 1 here; censoring comes later, from dropout and data locks.
arm() takes inclusion criteria through ...; the last example of this chapter uses one.
Typing the arm prints the same summary for every endpoint registered to it.
Endpoints and arms · independent endpoints
Several endpoint() calls, one arm
Arguments
endpoint()
name
Name(s) of the endpoint(s); one call can define several.
type
'tte', 'non-tte' (continuous, binary, categorical, repeated measures) or 'baseline' (non-tte, known at randomization).
readout
Named numeric vector: time from randomization to each non-tte value, e.g. c(orr = 2). NULL if all are tte; leave baseline endpoints out.
generator
Random number generator, first argument n. Returns n values, or a data frame of n rows: a column per name, plus <name>_event for each tte endpoint.
...
Arguments passed to generator.
arm()
name
Label of the arm in the generated data, e.g. in get_locked_data(); no '@' or ';'.
...
Inclusion criteria: dplyr::filter-style conditions on the endpoints. None: all generated patients are used.
arm$add_endpoints()
...
One or more objects returned by endpoint().
Viewer
Arm Name: placebo
Endpoints (3):pfs, os, orr
No
Variable
Stats / Freqs
Graph
1
pfs
[time-to-event]
Median time: 5.01
Events: 10000
Missing: 0 (0%)
2
pfs_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
3
os
[time-to-event]
Median time: 14.12
Events: 10000
Missing: 0 (0%)
4
os_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
5
orr
[numeric]
Mean (sd): 0.3 (0.46)
Min < median < max:
0 < 0 < 1
IQR (CV): 1 (1.53)
Missing: 0 (0%)
Viewer
Arm Name: placebo
Endpoints (3):pfs, os, orr
No
Variable
Stats / Freqs
Graph
1
pfs
[time-to-event]
Median time: 5.01
Events: 10000
Missing: 0 (0%)
2
pfs_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
3
os
[time-to-event]
Median time: 14.12
Events: 10000
Missing: 0 (0%)
4
os_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
5
orr
[categorical]
0: 6977 (69.8%)
1: 3023 (30.2%)
Missing: 0 (0%)
pfs <- endpoint(name = 'pfs', type = 'tte',
generator = rexp, rate = log(2) / 5)
os <- endpoint(name = 'os', type = 'tte',
generator = rexp, rate = log(2) / 14)
orr <- endpoint(name = 'orr', type = 'non-tte',
readout = c(orr = 2), generator = rbinom,
size = 1, prob = 0.3)
pbo <- arm(name = 'placebo')
pbo$add_endpoints(pfs, os, orr)
> set.seed(1)
> pbo
> set.seed(1)
> print(pbo, categorical_vars = 'orr')
Three endpoint() calls, three endpoints, three separate generators.
orr is read out 2 time units after randomization; pfs and os need no readout.
Medians 5 and 14 come back as 5.01 and 14.12. A 0/1 endpoint is numeric by default: its mean, 0.3, is the response rate.
categorical_vars = 'orr' shows the same column as frequencies: 30.2% responders.
Separate endpoint() calls are independent: in these 10,000 patients PFS > OS for 26% (5/19 = 26% expected). Endpoints that depend on each other need one generator.
Endpoints and arms · one built-in generator, two endpoints
Correlated PFS and OS: CorrelatedPfsAndOs2
Arguments
endpoint()
name
Name(s) of the endpoint(s); one call can define several.
type
'tte', 'non-tte' (continuous, binary, categorical, repeated measures) or 'baseline' (non-tte, known at randomization).
readout
Named numeric vector: time from randomization to each non-tte value, e.g. c(orr = 2). NULL if all are tte; leave baseline endpoints out.
generator
Random number generator, first argument n. Returns n values, or a data frame of n rows: a column per name, plus <name>_event for each tte endpoint.
...
Arguments passed to generator.
arm()
name
Label of the arm in the generated data, e.g. in get_locked_data(); no '@' or ';'.
...
Inclusion criteria: dplyr::filter-style conditions on the endpoints. None: all generated patients are used.
arm$add_endpoints()
...
One or more objects returned by endpoint().
Viewer
Arm Name: placebo
Endpoints (2):pfs, os
No
Variable
Stats / Freqs
Graph
1
pfs
[time-to-event]
Median time: 4.93
Events: 10000
Missing: 0 (0%)
2
os
[time-to-event]
Median time: 13.88
Events: 10000
Missing: 0 (0%)
3
pfs_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
4
os_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
pfs_os <- endpoint(name = c('pfs', 'os'),
type = c('tte', 'tte'),
generator = CorrelatedPfsAndOs2,
median_pfs = 5, median_os = 14,
kendall = 0.6)
pbo <- arm(name = 'placebo')
pbo$add_endpoints(pfs_os)
> set.seed(1)
> pbo
One call, two endpoints: names and types are vectors.
A built-in generator returning pfs, os, pfs_event, os_event together.
Model details (vignette): how the Gumbel copula links time to progression and OS, and how kendall is set.
zhangh12.github.io/TrialSimulator/
articles/simulatePfsAndOsGumbel
Medians 5 and 14 come back as 4.93 and 13.88.
The table lists the generator’s four columns in its order.
> set.seed(1)
> d <- pfs_os$test_generator(n = 1e4)
> cor(d$pfs, d$os, method = 'kendall')
[1] 0.5959365
> mean(d$pfs <= d$os)
[1] 1
The link is checked on the data: τ ≈ 0.6, and PFS never exceeds OS.
Registered together, updated together: update_generator() must name c('pfs', 'os').
Endpoints and arms · custom generator, two endpoint types
Response and PFS from one generator
Arguments
endpoint()
name
Name(s) of the endpoint(s); one call can define several.
type
'tte', 'non-tte' (continuous, binary, categorical, repeated measures) or 'baseline' (non-tte, known at randomization).
readout
Named numeric vector: time from randomization to each non-tte value, e.g. c(orr = 2). NULL if all are tte; leave baseline endpoints out.
generator
Random number generator, first argument n. Returns n values, or a data frame of n rows: a column per name, plus <name>_event for each tte endpoint.
...
Arguments passed to generator.
arm()
name
Label of the arm in the generated data, e.g. in get_locked_data(); no '@' or ';'.
...
Inclusion criteria: dplyr::filter-style conditions on the endpoints. None: all generated patients are used.
arm$add_endpoints()
...
One or more objects returned by endpoint().
Viewer
Arm Name: treatment
Endpoints (2):orr, pfs
No
Variable
Stats / Freqs
Graph
1
orr
[categorical]
0: 6964 (69.6%)
1: 3036 (30.4%)
Missing: 0 (0%)
2
pfs
[time-to-event]
Median time: 5.08
Events: 10000
Missing: 0 (0%)
3
pfs_event
[event indicator]
1: 10000 (100%)
Missing: 0 (0%)
ep <- endpoint(name = c('orr', 'pfs'),
type = c('non-tte', 'tte'),
readout = c(orr = 2),
generator = orr_pfs,
p_resp = 0.3,
med_resp = 10, med_non = 4)
trt <- arm(name = 'treatment')
trt$add_endpoints(ep)
orr_pfs <- function(n, p_resp, med_resp, med_non){
orr <- rbinom(n, size = 1, prob = p_resp)
med <- ifelse(orr == 1, med_resp, med_non)
data.frame(orr = orr,
pfs = rexp(n, rate = log(2) / med),
pfs_event = 1)
}
ep <- endpoint(name = c('orr', 'pfs'),
type = c('non-tte', 'tte'),
readout = c(orr = 2),
generator = orr_pfs,
p_resp = 0.3,
med_resp = 10, med_non = 4)
trt <- arm(name = 'treatment')
trt$add_endpoints(ep)
> set.seed(1)
> print(trt, categorical_vars = 'orr')
Two endpoints of different types from one call.
Only the non-tte endpoint gets a readout.
The custom generator: n first, one column per name. Responders get the longer PFS.
NAMING RULE pfs is time-to-event, so the generator also returns pfs_event (1 = event, 0 = censored).
p_resp = 0.3 → 30.4% responders.
Pooled PFS: 30% with median 10 and 70% with median 4 give 5.10; the table shows 5.08.
> set.seed(1)
> d <- ep$test_generator(n = 1e4)
> tapply(d$pfs, d$orr, median)
0 1
3.923916 10.581403
Responders progress later: 10.6 vs 3.9 months.
Endpoints and arms · custom generator, longitudinal
Repeated measures from one generator
Arguments
endpoint()
name
Name(s) of the endpoint(s); one call can define several.
type
'tte', 'non-tte' (continuous, binary, categorical, repeated measures) or 'baseline' (non-tte, known at randomization).
readout
Named numeric vector: time from randomization to each non-tte value, e.g. c(orr = 2). NULL if all are tte; leave baseline endpoints out.
generator
Random number generator, first argument n. Returns n values, or a data frame of n rows: a column per name, plus <name>_event for each tte endpoint.
...
Arguments passed to generator.
arm()
name
Label of the arm in the generated data, e.g. in get_locked_data(); no '@' or ';'.
...
Inclusion criteria: dplyr::filter-style conditions on the endpoints. None: all generated patients are used.
arm$add_endpoints()
...
One or more objects returned by endpoint().
Viewer
Arm Name: treatment 1
Endpoints (3):bp_cfb2, baseline, bp_cfb4
No
Variable
Stats / Freqs
Graph
1
baseline
[numeric]
Mean (sd): 139.99 (1.42)
Min < median < max:
133.93 < 140 < 145.77
IQR (CV): 1.94 (0.01)
Missing: 0 (0%)
2
bp_cfb2
[numeric]
Mean (sd): -15 (1.41)
Min < median < max:
-19.99 < -15 < -9.81
IQR (CV): 1.96 (0.09)
Missing: 0 (0%)
3
bp_cfb4
[numeric]
Mean (sd): -19.99 (2.01)
Min < median < max:
-27.13 < -20.01 < -12.5
IQR (CV): 2.69 (0.1)
Missing: 0 (0%)
ep <- endpoint(
name = c('bp_cfb2', 'baseline', 'bp_cfb4'),
type = 'non-tte',
readout = c(baseline = 0, bp_cfb4 = 4, bp_cfb2 = 2),
generator = bp_gen,
bp_means = c(140, 125, 120), bp_vcov = vcov1)
trt <- arm(name = 'treatment 1')
trt$add_endpoints(ep)
vcov1 <- matrix(c(2, 1.5, 1, 1.5, 3, 1.5, 1, 1.5, 4), 3)
bp_gen <- function(n, bp_means, bp_vcov){
bp <- mvtnorm::rmvnorm(n, mean = bp_means,
sigma = bp_vcov)
data.frame(baseline = bp[, 1],
bp_cfb2 = bp[, 2] - bp[, 1],
bp_cfb4 = bp[, 3] - bp[, 1])
}
ep <- endpoint(
name = c('bp_cfb2', 'baseline', 'bp_cfb4'),
type = 'non-tte',
readout = c(baseline = 0, bp_cfb4 = 4, bp_cfb2 = 2),
generator = bp_gen,
bp_means = c(140, 125, 120), bp_vcov = vcov1)
trt <- arm(name = 'treatment 1')
trt$add_endpoints(ep)
> set.seed(1)
> trt
Blood pressure at baseline and its changes at weeks 2 and 4: three endpoints, one call.
One type, recycled to all three.
The week each value is observed, counted from randomization. Matched by name, so the order may differ from name.
readout · weeks from randomization to each value
baseline
bp_cfb2
bp_cfb4
0
1
2
3
4
5
weeks from
randomization
In calendar time each patient starts at randomization; a data lock sees only the values whose readout has passed.
randomized wk 0
randomized wk 3
NA
randomized wk 5
NA
NA
0
2
4
6
8
10
calendar weeks
data lock · week 6
A value appears at randomization + readout; at a lock, a value whose time has not come yet is NA.
A trivariate normal for weeks 0, 2 and 4, returned as the baseline and the changes from baseline (vignette: Define Longitudinal Endpoints).
Means 140, 125 − 140 = −15 and 120 − 140 = −20; sds √2, √2 and 2 follow from vcov1.
Endpoints and arms · custom generator, baseline covariate
A categorical baseline covariate
Arguments
endpoint()
name
Name(s) of the endpoint(s); one call can define several.
type
'tte', 'non-tte' (continuous, binary, categorical, repeated measures) or 'baseline' (non-tte, known at randomization).
readout
Named numeric vector: time from randomization to each non-tte value, e.g. c(orr = 2). NULL if all are tte; leave baseline endpoints out.
generator
Random number generator, first argument n. Returns n values, or a data frame of n rows: a column per name, plus <name>_event for each tte endpoint.
...
Arguments passed to generator.
arm()
name
Label of the arm in the generated data, e.g. in get_locked_data(); no '@' or ';'.
...
Inclusion criteria: dplyr::filter-style conditions on the endpoints. None: all generated patients are used.
arm$add_endpoints()
...
One or more objects returned by endpoint().
Viewer
Arm Name: treatment
Endpoints (1):region
No
Variable
Stats / Freqs
Graph
1
region
[categorical]
North America: 3020 (30.2%)
Asia: 2522 (25.2%)
Latin America: 1881 (18.8%)
Western Europe: 1221 (12.2%)
Oceania: 823 (8.2%)
1 others: 533 (5.3%)
Missing: 0 (0%)
Viewer
Arm Name: treatment
Endpoints (1):region
No
Variable
Stats / Freqs
Graph
1
region
[categorical]
Asia: 3582 (35.8%)
Latin America: 2768 (27.7%)
Western Europe: 1727 (17.3%)
Oceania: 1188 (11.9%)
Eastern Europe: 735 (7.3%)
Missing: 0 (0%)
region <- endpoint(
name = 'region',
type = 'baseline',
# same as type = 'non-tte', readout = c(region = 0)
generator = region_gen,
prob = c(.25, .12, .05, .30, .20, .08))
trt <- arm(name = 'treatment')
trt$add_endpoints(region)
region_gen <- function(n, prob){
sample(c('Asia', 'Western Europe', 'Eastern Europe',
'North America', 'Latin America', 'Oceania'),
size = n, replace = TRUE, prob = prob)
}
region <- endpoint(
name = 'region',
type = 'baseline',
# same as type = 'non-tte', readout = c(region = 0)
generator = region_gen,
prob = c(.25, .12, .05, .30, .20, .08))
trt <- arm(name = 'treatment')
trt$add_endpoints(region)
region <- endpoint(
name = 'region',
type = 'baseline',
# same as type = 'non-tte', readout = c(region = 0)
generator = region_gen,
prob = c(.25, .12, .05, .30, .20, .08))
trt <- arm(name = 'treatment', region != 'North America')
trt$add_endpoints(region)
> set.seed(1)
> trt
'baseline': observed at randomization, so readout 0 and no readout argument.
Six regions; character values are summarized as categories.
Levels are sorted by frequency, not by their order in the code; the rarest (Eastern Europe, 5%) is pooled as “1 others”.
An inclusion criterion through the ... of arm().
The enrolled population: no North America, shares rescaled (Asia 35.8% ≈ 0.25 / 0.70); five levels left, so Eastern Europe gets its own row.
Action functions · saving results
Save for the summary, or communicate across milestones
trial <- trial(..., global_data = list(alpha = 0.025))
interim_action <- function(trial){
d <- trial$get_locked_data('interim')
fit <- fitLogrank(Surv(pfs, pfs_event) ~ arm, placebo = 'placebo',
data = d, alternative = 'less')
trial$save(value = fit$p, name = 'p_interim')
trial$save_custom_data(value = 'hello, final', name = 'note')
}
final_action <- function(trial){
d <- trial$get_locked_data('final')
fit <- fitLogrank(Surv(pfs, pfs_event) ~ arm, placebo = 'placebo',
data = d, alternative = 'less')
note <- trial$get('note') # 'hello, final'
alpha <- trial$get_global_data('alpha') # 0.025
trial$save(value = fit$p, name = 'p_final')
trial$save(value = fit$p < alpha, name = 'reject')
}
custom data
trial$save(value, name)
A scalar or a one-row data frame becomes a column of the output, kept for the summary after the run. A later action can read it with trial$get_output().
trial$save_custom_data(value, name)
Any R object, here just a string. A later action of the same replicate reads it with trial$get(name), the short alias of trial$get_custom_data(name). Cleared before the next replicate.
global_data
Read-only and identical in every replicate; defined once in trial(), read with trial$get_global_data(name).
Action functions · saving results
controller$get_output(): one row per replicate
output
Filter
1
2
3
4
5
6
milestone_time_<interim>
13.07
12.66
12.97
12.85
13.24
12.60
n_events_<interim>_<pfs>
150
150
150
150
150
150
milestone_time_<final>
18.05
18.67
18.08
19.29
18.34
18.50
n_events_<final>_<pfs>
250
250
250
250
250
250
n_events_<final>_<patient_id>
400
400
400
400
400
400
p_interim
0.1010
0.4840
0.0158
0.0090
0.0001
0.3578
p_final
0.0795
0.2125
0.0130
0.0088
0.0000
0.0798
reject
FALSE
FALSE
TRUE
TRUE
TRUE
FALSE
Showing 1 to 6 of 1,000 entries, 14 total columns
> View(output[, cols])
Saved automatically at every milestone: the trigger time, the events of each endpoint, the enrolled patients and a per-arm table. Almost every summary needs them, without a line of code.
Saved by trial$save(): p_interim, p_final, reject. The power over 1,000 replicates is simply mean(output$reject) = 77.7%.
Not needed? controller$run(tidy = TRUE) skips the per-arm table, the costliest of them (1,000 replicates of this example: 21.4 s instead of 22.5 s); controller$get_output(tidy = TRUE) drops all standard columns from what it returns.
n_events_<final>_<arms>
one data frame per cell, row 1
arm
placebo
treatment
pfs
132
118
patient_id
200
200
vignette: action functions
Action functions · graphical testing
Three looks, three calls, one object
gt <- GraphicalTesting$new(alpha, transition,
alpha_spending, planned_max_info, hypotheses)
gt$test(stats1) # analysis 1: its p-values only
gt$test(stats2) # analysis 2
gt$test(stats3) # analysis 3
gt$get_current_decision()
Example 2 of ?GraphicalTesting; inputs omitted.
1
0.5
0.5
1
0.5
0.5
1
0.5
0.5
1
0.5
0.5
1
1
0.5
0.5
1
1
1
H1: OS sub
α = 0.01
rejected
H2: OS all
α = 0.01
α = 0.02
not rejected
H3: PFS sub
α = 0.004
rejected
H4: PFS all
α = 0
α = 0.004
not rejected
H5: ORR sub
α = 0.0005
rejected
H6: ORR all
α = 0.0005
α = 0.001
not rejected
> gt$test(stats1) # rows tested at this look
hypothesis obs_p_value max_allocated_alpha decision
H1: OS sub 0.03 0.01 accept
H2: OS all 0.2 0.01 accept
H3: PFS sub 0.2 0.004 accept
H6: ORR all 0.1 0.001 accept
H5: ORR sub 1e-05 0.0005 reject
> gt$test(stats2) # rows tested at this look
hypothesis obs_p_value max_allocated_alpha decision
H2: OS all 0.15 0.02 accept
H1: OS sub 1e-04 0.01 reject
H3: PFS sub 0.001 0.004 reject
H4: PFS all 0.2 0.004 accept
> gt$test(stats3) # rows tested at this look
hypothesis obs_p_value max_allocated_alpha decision
H2: OS all 0.1 0.02 accept
> gt$get_current_decision()
H1: OS sub H2: OS all H3: PFS sub
"reject" "accept" "reject"
H4: PFS all H5: ORR sub H6: ORR all
"accept" "reject" "accept"
H5 rejected at analysis 1; its α (0.0005) moves to H6.
H1 and H3 rejected; H2 now holds 0.02 and H4 0.004.
H2 at its final look: p = 0.1, not rejected; the graph stays.
Three calls, each with one analysis; the object did the bookkeeping.
Trial, listener, controller · signatures
One # switches the futility look off
trial <- trial(..., seed = 2026) # same patients twice
trial$add_arms(sample_ratio = c(1, 1), pbo, trt)
listener <- listener()
listener$add_milestones(
futility,
interim,
final
)
controller <- controller(trial, listener)
controller$run(n = 1) # plot_event = TRUE by default
trial <- trial(..., seed = 2026) # same patients twice
trial$add_arms(sample_ratio = c(1, 1), pbo, trt)
listener <- listener()
listener$add_milestones(
# futility,
interim,
final
)
controller <- controller(trial, listener)
controller$run(n = 1) # plot_event = TRUE by default
A milestone <futility> is registered.
A milestone <interim> is registered.
A milestone <final> is registered.
Data is locked at time = <10> for milestone <futility>.
Data is locked at time = <18.7781514986108> for milestone <interim>.
Data is locked at time = <44.1616864179882> for milestone <final>.
A milestone <interim> is registered.
A milestone <final> is registered.
Data is locked at time = <18.7781514986108> for milestone <interim>.
Data is locked at time = <44.1616864179882> for milestone <final>.
Dashed lines: data locks at 10 (futility), 18.8 (interim), 44.2 (final).
Dashed lines: 18.8 (interim) and 44.2 (final), the same times as before.
One replicate, three looks: run(n = 1) draws the event plot with a dashed line at each data lock.
To drop the futility look, comment out one line.
Two milestones registered; the interim and the final lock at the same times, because the seed and the patients are the same.
The futility milestone still exists but is never checked: no orr_diff, 17 output columns instead of 24. Delete the # and it is back.
Designs with and without a look differ by one character, so both can be simulated from the same script.
Chapter · From words to code
Complete examples, start to finish
Describe the design in plain words first; the script then grows one piece at a time.
endpoint()
arm()
trial()
add_endpoints()
add_arms()
function(trial){ … }
milestone()
listener()
action =
add_milestones()
controller()
$run()
The examples
1
Two-arm design
2
Seamless dose selection
3
Response-adaptive randomization
4
Dose ranging
5
Adaptive enrichment
From words to code · two-arm design
Describe the design. The code follows.
two_arm.R
Trial design chat
Describe your trial design…
locked_data
×
Filter
1
2
3
4
5
6
7
8
patient_id
1
2
3
4
5
6
7
8
arm
placebo
treatment
placebo
treatment
treatment
placebo
placebo
treatment
enroll_time
0.04
0.08
0.12
0.16
0.20
0.24
0.28
0.32
dropout_time
231.55
22.89
231.20
165.07
119.20
96.31
65.65
80.56
pfs
1.91
3.55
11.80
6.86
11.72
4.87
8.79
2.78
pfs_event
1
1
0
1
0
1
1
1
Showing 1 to 8 of 298 entries, 6 total columns
Browse[1]> View(locked_data)
From words to code · two-arm design
Describe the design. The code follows.
two_arm.R
interim_action.R
final_action.R
1
2
3
4
5
6
7
final_action <- function(trial){
locked_data <- trial$get_locked_data('final')
fit <- fitLogrank(Surv(pfs, pfs_event) ~ arm,
placebo = 'placebo', data = locked_data,
alternative = 'less')
trial$save(value = fit$p, name = 'p_final')
}
Trial design chat
Describe your trial design…
From words to code · seamless adaptive design
Seamless: select a dose, keep the trial
seamless.R
Trial design chat
Describe your trial design…
From words to code · response-adaptive randomization
Response-adaptive: shift patients to doses that work
response_adaptive.R
Trial design chat
Describe your trial design…
From words to code · dose-ranging study
Dose ranging: open more doses after a signal
dose_ranging.R
Trial design chat
Describe your trial design…
From words to code · adaptive enrichment
Enrichment: follow the biomarker, re-size the trial
enrichment.R
Trial design chat
Describe your trial design…
Chapter · Crossover
Three kinds of crossover, none replaces another
Planned, with wash-out
Who decides
The protocol: each sequence is fixed at randomization.
arm(name = 'ABCD')
endpoint(readout = ...)
Periods and wash-outs are readout times.
Vignette:
Crossover with wash-out periods
Dynamic treatment switching
Who decides
Each patient's own course: progression, non-response, deterioration.
regimen(what, when, how)
trial$add_regimen()
Applied as patients are generated (T = 0).
Vignette:
Dynamic treatment switching
Crossover at a milestone
Who decides
The trial: an interim result opens switching for patients still on study.
trial$crossover(what, how,
when, delay)
Opens at T = milestone time + delay.
Vignette:
Crossover at a milestone
The last two share one engine: what() → when() → how(), opened at time T.
Crossover · planned, with wash-out
A planned crossover is a longitudinal design
readouts <- c(baseline1 = 0, ep1 = 3,
baseline2 = 4, ep2 = 8,
baseline3 = 10, ep3 = 15,
baseline4 = 17.5, ep4 = 19.5)
eps <- endpoint(name = names(readouts),
type = rep('non-tte', 8),
readout = readouts,
generator = rng, means = rep(c(0, .5), 4))
arm1 <- arm(name = 'ABCD')
arm1$add_endpoints(eps)
## BDAC, CADB, DCBA: same code, other means
trial$add_arms(sample_ratio = c(1, 1, 1, 1),
arm1, arm2, arm3, arm4)
final <- milestone(name = 'final',
when = enrollment(n = 60, min_treatment_duration = 19.5),
action = action)
Balanced Latin square, 60 patients
ABCD
A
B
C
D
BDAC
B
D
A
C
CADB
C
A
D
B
DCBA
D
C
B
A
0
5
10
15
20
time from randomization; gaps are wash-outs
baseline1 = 0
baseline2 = 4
baseline3 = 10
baseline4 = 17.5
ep1 = 3
ep2 = 8
ep3 = 15
ep4 = 19.5
Each period starts with a baseline: baseline1 … baseline4, read out at 0, 4, 10 and 17.5.
Each period ends with an endpoint: ep1 … ep4, read out at 3, 8, 15 and 19.5. Eight non-tte endpoints, each with its readout time.
Each sequence is an arm; its generator can carry period and carry-over effects.
final: last patient at 19.5
One milestone: all 60 enrolled and treated for 19.5. No switching rule is needed: the sequence is the switch.
Crossover · what the trio receives
Each function sees only the patients it should
200
175
86
86
Trial data at the interim, T = 12
180 enrolled and 20 who enroll later; values as generated.
Eligible → passed to what()
The package drops 25 with nothing left to change (15 died, 10 dropped out) and keeps later enrollees. You add only the clinical rule: arm == 'control'.
Switchers → passed to when()
Exactly the 86 rows what() returned. One switch_time each, not before T (earliest_crossover_time_from_enrollment is there to help).
Switchers, timed → passed to how()
The same 86 rows, with new_treatment and switch_time added. Change post-switch outcomes only; dropout and data cuts are re-applied for you.
−25
Same machinery at enrollment (add_regimen, T = 0): 300 → 300 → 48 → 48. Everyone generated is eligible; what() does all the selecting.
Chapter · An agent skill
clinical-trial-simulation: an agent skill
A trial brief in plain words goes in; code, a simulation run and a QC-ready report come out. The agent brings the engineering; the skill brings TrialSimulator.
SKILL.md
A folder of instructions and references. The agent reads it when a task needs it.
install
Ask the agent in plain words: it fetches the folder and puts it where it looks for skills.
design
A thinking framework, not a script: the plan comes first, questions are asked in clinical terms, no step is silent, and the report is written for QC.
clinical-trial-simulation · scan to open the skill on GitHub
https://github.com/RConsortium/pharma-skills/tree/main/clinical-trial-simulation
R Consortium pharma-skills · version 0.4.2 · needs TrialSimulator ≥ 1.39.0 · MIT licence · pre-release, under active development
Then: what a skill is, how to install it, its design, a real run replayed, its report, and how to benchmark it.
Linus is now
vibe coding
“
The code, the test programs, the review behind the list above and the first draft of this text were done with an LLM coding assistant (Claude Code) under my direction. The measurements were run on my machine.”
— Linus Torvalds, commit message, 10 Oct 2026
Branch noref-filemap-read-with-llm, “mm: read from the page cache without folio references”. Eight threads reading one cached file: about 10 million → 30–33 million reads per second on his laptop.
Illustration adapted from 新智元 (WeChat); background replaced.
An agent skill · install
Install it by asking
Ask in plain words
> Install the clinical-trial-simulation skill from
https://github.com/RConsortium/pharma-skills/tree/main/
clinical-trial-simulation
Where it goes
The agent fetches the folder and puts it where it looks for skills: for Claude Code, ~/.claude/skills/ for every project, or .claude/skills/ inside one project.
What it needs
R ≥ 4.1; TrialSimulator ≥ 1.39.0 from GitHub; survival; rpact or gsDesign; markdown. Only for some designs: simdata, DoseFinding.
How to use it
Describe a trial: the agent loads the skill when the task matches its description, or ask for it by name.
At load it checks the installed TrialSimulator, without a network call, and says so first:
● clinical-trial-simulation v0.4.2 loaded — TrialSimulator 1.39.0, R 4.5.2
Older or missing: it offers remotes::install_github("zhangh12/TrialSimulator") and waits for a yes.
github.com/RConsortium/pharma-skills
clinical-trial-simulation
The skill on GitHub
R Consortium pharma-skills · v0.4.2 · MIT
Agentic skill · the run, replayed
Load the skill: a version check, then questions
claude — ~/pharma-skills
✻ Welcome to Claude Code!
/help for help, /status for your current setup
cwd: ~/pharma-skills
>
? for shortcuts
Agentic skill · the run, replayed
Paste the brief. The first answer is the plan.
claude — ~/pharma-skills
✻ Welcome to Claude Code!
/help for help, /status for your current setup
cwd: ~/pharma-skills
>
? for shortcuts
Agentic skill · the run, replayed
Paste the brief. The first answer is the plan.
claude — ~/pharma-skills
│ One-sided α │ 0.025 │ protocol (derived): two-sided 0.05 │
│ │ │ / 2 │
├─────────────────────────────┼───────────────────────────────────┼────────────────────────────────────┤
│ PFS final event count │ ≈ 335 for 90% power at HR 0.70 │ derived (pending), boundary script │
├─────────────────────────────┼───────────────────────────────────┼────────────────────────────────────┤
│ PFS interim event count │ ≈ 201 (60% of final) │ derived (pending) │
├─────────────────────────────┼───────────────────────────────────┼────────────────────────────────────┤
│ PFS efficacy boundaries (z) │ interim / final │ derived (pending): LD-OBF spending │
├─────────────────────────────┼───────────────────────────────────┼────────────────────────────────────┤
│ OS analysis │ at last patient randomized + 24 │ protocol │
│ │ mo, z vs 1.960, only if PFS │ │
│ │ rejected │ │
├─────────────────────────────┼───────────────────────────────────┼────────────────────────────────────┤
│ Scenarios │ alternative (0.70 / 0.80), global │ protocol │
│ │ null (1 / 1), 1000 replicates │ │
│ │ each │ │
>
? for shortcuts
Agentic skill · the run, replayed
Answer four questions, then it runs to the report
claude — ~/pharma-skills
✻ Welcome to Claude Code!
/help for help, /status for your current setup
cwd: ~/pharma-skills
>
? for shortcuts
Agentic skill · the run, replayed
Answer four questions, then it runs to the report
claude — ~/pharma-skills
│ │ censors both endpoints) │ │
├─────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
│ One-sided α │ 0.025 │ protocol (derived) │
├─────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
│ PFS interim / final │ 200 / 333 events (IF = 0.6006) │ derived (rpact) │
├─────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
│ PFS efficacy boundaries │ z ≥ 2.6671 at the interim, z ≥ │ derived (rpact, LD-OBF) │
│ │ 1.9811 at the final │ │
├─────────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
│ OS analysis │ last patient randomized + 24 │ protocol │
│ │ mo, z ≥ 1.9600, only if PFS was │ │
│ │ rejected │ │
└─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┘
Gate 3: what gets recorded at each analysis
>
? for shortcuts
Agentic skill · the run, replayed
Paste /cost: the report records what the run cost
claude — ~/pharma-skills
✻ Welcome to Claude Code!
/help for help, /status for your current setup
cwd: ~/pharma-skills
>
? for shortcuts
Thank you
Questions, ideas and bug reports are all welcome.
Open an issue
Found a bug, missing a feature, stuck on a design?
github.com/zhangh12/TrialSimulator/issues
Scan the code, or type the address.
Han Zhang
Innovative Statistical Science, Astellas
zhangh12.github.io/TrialSimulator