add_arms: Adding One or More Arms to a Trial
In TrialSimulator: Clinical Trial Simulator

add_arms

R Documentation

Adding One or More Arms to a Trial

Description

add one or more arms to a trial. This function can be used in two scenarios: (1) adding arms right after a trial is created (i.e., trial(...)). sample_ratio and arms added through ... must be of same length; (2) adding arms to an existing trial in action functions of milestones.

This is a user-friendly wrapper of the member function of trial, i.e., Trials$add_arms(), which is used in vignettes. Users who are not familiar with the concept of classes may consider using this wrapper directly.

The trial captures an independent deep copy of every arm it registers. Subsequent changes to the original arm object do not affect the trial, and adaptations within the trial (e.g., update_generator()) do not modify the original arm. Complete the configuration of an arm before registering it. The copy covers the arm and endpoint objects themselves; a mutable environment or R6 object captured by a generator function is shared by design of R closures and is not isolated.

Usage

add_arms(trial, sample_ratio, ...)

Arguments

`trial`	a trial object returned by `trial()`.
`sample_ratio`	integer vector. Sample ratio for permuted block randomization. It will be appended to existing sample ratio in the trial.
`...`	one or more objects returned from `arm()`. Randomization is carried out with updated sample ratio of newly added arm. Note that we can run `Trials$add_arm(sample_ratio1, arm1)` followed by `add_arms(trial, sample_ratio2, arm2)`. We would expected similar result with `add_arms(trial, c(sample_ratio1, sample_ratio2), arm1, arm2)`. Note that these two methods won't return exactly the same trial because randomization queue are generated twice in the first approach but only once in the second approach. But statistically, they are equivalent and of the same distribution.