Create a class of milestone. A milestone means the time point to take an action, e.g., carrying out (futility, interim, final) analysis for adding/removing arms, or stopping a trial early. It can also be any more general time point where trial data is used in decision making or adaptation. For example, one can define a milestone for changing randomization scheme, sample size re-assessment, trial duration extension etc.
Public methods in this R6 class are used in developing
this package. Thus, we have to export the whole R6 class which exposures all
public methods. However, none of the public methods on this page is
useful to end users. Instead, refer to the
vignette
to learn how to define milestones when performing simulation using
TrialSimulator.
Value
an R6Class generator object; use milestone() to create a milestone.
Methods
Method new()
initialize milestone
Usage
Milestones$new(name, type = name, trigger_condition, action = doNothing, ...)Arguments
namecharacter. Name of milestone.
typecharacter vector. Milestone type(s) (futility, interim, final), a milestone can be of multiple types. This is for information purpose so can be any string.
trigger_conditionfunction to check if this milestone should trigger. See vignette
Condition System for Triggering Milestones in a Trial.actionfunction to execute when the milestone triggers.
...(optional) arguments of
action.
Method set_trigger_condition()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
replace the trigger condition of a not-yet-triggered milestone. This
is invoked by the listener when it applies an update requested through
Trials$update_milestone() within an action function. The
as-designed condition, frozen at construction, is restored by
reset() between simulation replicates.
Arguments
trigger_conditionan object of class
Condition. Seetrigger_conditionofmilestone().
Method set_action_function()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
replace the action function (and its fixed arguments) of a
not-yet-triggered milestone. This is invoked by the listener when it
applies an update requested through Trials$update_milestone()
within an action function. The action in effect at construction is
restored by reset() between simulation replicates.
Usage
Milestones$set_action_function(action, action_args = list())Arguments
actionfunction to execute when the milestone triggers. See
actionofmilestone().action_argsnamed list. Fixed arguments of
action, corresponding to...ofmilestone().
Method get_trigger_status()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return trigger status
Method reset()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
reset an milestone so that it can be triggered again. Usually, this is called
before the controller of a trial can run additional replicates
of simulation. If the trigger condition or the action was replaced
in-run through Trials$update_milestone(), the as-designed
version is restored so that every replicate starts from the original
design.
Method trigger_milestone()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
trigger an milestone (always TRUE) and execute action accordingly. It calls Trial$get_data_lock_time() to lock data based on conditions implemented in Milestones$trigger_condition. If time that meets the condition cannot be found, Trial$get_data_lock_time() will throw an error and stop the program. This means that user needs to adjust their trigger_condition (e.g., target number of events (target_n_events) is impossible to reach).
Method mute()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
mute all messages (not including warnings)