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.
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 runTrials$add_arm(sample_ratio1, arm1)followed byadd_arms(trial, sample_ratio2, arm2). We would expected similar result withadd_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.