Trial: Simulate a multi‑arm clinical trial

The Trial class coordinates one or more Population objects, a Timer, and a list of Condition objects to simulate a clinical trial.

At each unique time defined in the trial's Timer, the Trial:

• applies enrollment and dropout updates to each Population

• builds a snapshot of all currently enrolled subjects

• evaluates each Condition in self$conditions against the snapshot

• stores both the snapshot (locked_data) and the analysis outputs (results)

Use run() to execute the simulation. Trigger conditions are built with Condition$new() (or helpers trigger_by_calendar() / trigger_by_fraction()) and stored in trial$conditions.

See also

Population, Timer, Condition, prettify_results(), replicate_trial(), clone_trial().

Timer, Condition, prettify_results().

Public fields

name

character Unique trial identifier.

seed

numeric or NULL Random seed for reproducibility.

timer

Timer object with timepoints.

population

list of Population objects, one per arm.

conditions

list of Condition objects evaluated at each timepoint.

locked_data

list Snapshots at each timepoint.

results

list Analysis outputs per condition.

Methods

Public methods

• Trial$new()

• Trial$run()

• Trial$clone()

---

Method new()

Create a new Trial instance.

Usage

Trial$new(
  name,
  seed = NULL,
  timer = NULL,
  population = list(),
  locked_data = list(),
  conditions = list(),
  results = list()
)

Arguments

name

character Unique identifier for the trial.

seed

numeric or NULL Optional random seed for reproducibility.

timer

Timer object defining timepoints.

population

list of Population objects, one per arm.

locked_data

list Generated at each $run() call.

conditions

list of Condition objects to evaluate at each timepoint.

results

list Analysis outputs generated at each $run() call.

Returns

A new Trial instance.

Examples

t <- Timer$new(name="simple_timer")
pop <- Population$new(
  name = "simple_pop",
  data = vector_to_dataframe(rnorm(5))
)
pop$set_enrolled(5, 1)
Trial$new(name = "simple_trial", timer=t, population = list(pop))

---

Method run()

Execute a trial simulation.

At each unique time defined by the trial's Timer:

• Apply enrollment and dropout actions to each Population

• Build a combined snapshot of all currently enrolled subjects

• Attach a time column to the snapshot

• Evaluate each Condition in self$conditions against the snapshot

• Store snapshots and condition outputs under time‑indexed list keys

Usage

Trial$run()

Returns

Updates locked_data and results fields.

Examples

# Create two populations
popA <- Population$new("A", data = vector_to_dataframe(rnorm(10)))
popB <- Population$new("B", data = vector_to_dataframe(rnorm(12)))

# Create a timer and add timepoints
t <- Timer$new("Timer")
t$add_timepoint(time = 1, arm = "A", dropper = 0L, enroller = 4L)
t$add_timepoint(time = 1, arm = "B", dropper = 0L, enroller = 5L)
t$add_timepoint(time = 2, arm = "A", dropper = 1L, enroller = 2L)
t$add_timepoint(time = 2, arm = "B", dropper = 2L, enroller = 3L)

# Create a trial
trial <- Trial$new(
  name = "ExampleTrial",
  seed = 123,
  timer = t,
  population = list(popA, popB)
)

# Run the simulation
trial$run()

prettify_results(trial$results)

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Trial$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# Create two populations
popA <- Population$new("A", data = vector_to_dataframe(rnorm(10)))
popB <- Population$new("B", data = vector_to_dataframe(rnorm(12)))

# Create a timer and add timepoints
t <- Timer$new("Timer")
t$add_timepoint(time = 1, arm = "A", dropper = 0L, enroller = 4L)
t$add_timepoint(time = 1, arm = "B", dropper = 0L, enroller = 5L)
t$add_timepoint(time = 2, arm = "A", dropper = 1L, enroller = 2L)
t$add_timepoint(time = 2, arm = "B", dropper = 2L, enroller = 3L)

# Build a condition: fire at time 2 and count enrolled rows
cond <- Condition$new(
  where    = rlang::quos(.data$time %in% 2),
  analysis = function(df, current_time) nrow(df),
  name     = "final"
)

# Create a trial
trial <- Trial$new(
  name       = "ExampleTrial",
  seed       = 123,
  timer      = t,
  population = list(popA, popB),
  conditions = list(cond)
)

# Run the simulation
trial$run()

prettify_results(trial$results)
#>   time final
#> 1    2    14


## ------------------------------------------------
## Method `Trial$new`
## ------------------------------------------------

t <- Timer$new(name="simple_timer")
pop <- Population$new(
  name = "simple_pop",
  data = vector_to_dataframe(rnorm(5))
)
pop$set_enrolled(5, 1)
Trial$new(name = "simple_trial", timer=t, population = list(pop))
#> <Trial>
#>   Public:
#>     clone: function (deep = FALSE) 
#>     conditions: list
#>     initialize: function (name, seed = NULL, timer = NULL, population = list(), 
#>     locked_data: list
#>     name: simple_trial
#>     population: list
#>     results: list
#>     run: function () 
#>     seed: NULL
#>     timer: Timer, R6

## ------------------------------------------------
## Method `Trial$run`
## ------------------------------------------------

# Create two populations
popA <- Population$new("A", data = vector_to_dataframe(rnorm(10)))
popB <- Population$new("B", data = vector_to_dataframe(rnorm(12)))

# Create a timer and add timepoints
t <- Timer$new("Timer")
t$add_timepoint(time = 1, arm = "A", dropper = 0L, enroller = 4L)
t$add_timepoint(time = 1, arm = "B", dropper = 0L, enroller = 5L)
t$add_timepoint(time = 2, arm = "A", dropper = 1L, enroller = 2L)
t$add_timepoint(time = 2, arm = "B", dropper = 2L, enroller = 3L)

# Create a trial
trial <- Trial$new(
  name = "ExampleTrial",
  seed = 123,
  timer = t,
  population = list(popA, popB)
)

# Run the simulation
trial$run()

prettify_results(trial$results)
#> NULL