Regimens: Class of Regimens
In TrialSimulator: Clinical Trial Simulator
Regimens R Documentation
Class of Regimens
Description
Create a class of regimen. A regimen defines the rules to select treatments for
patients switch, to determine the time of switching, and to update patients'
endpoint data.
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, use regimen() to create a regimen and
register it with a trial through trial$add_regimen() or
trial$crossover().
Value
an R6Class generator object; use regimen() to create a regimen.
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
Method new()
initialize regimen
Usage
Regimens$new(what, when, how, ..., earliest_crossover_calendar_time = 0)
Arguments
whata function determining whether patients' data would be
updated due to switching treatment. It takes patient_data,
a data frame as argument, and returns a data frame of two columns
patient_id and new_treatment, with one row per switching
patient. The number of rows in the returned data frame may be smaller
than the number of patients in the input data frame; patients that are
left out are simply not switched. Values of new_treatment must
not contain '@' or ';', which are reserved for encoding
regimen_trajectory.
Note that the returned object will be passed into function 'how()', which
is also provide by users. This argument can also be a
list of functions that will be executed sequentially. No default value.
whena function determining the time at which a patient switches
to another treatment regimen, measured from the time of enrollment.
It takes patient_data, a data frame as
argument, and returns a data frame of two columns patient_id and
switch_time (from enroll_time). The number of rows in the
returned data frame must equal the number of rows in patient_data,
i.e., a switching time must be specified for every patient (missing
values are not allowed).
Note that the returned object will be passed into function 'how()', which
is also provided by users. This argument can also be a
list of functions that will be executed sequentially. No default value.
howa function updating patients' data after treatment switching.
Only modified columns and patient_id are returned. For a cell that
should not change, return its original value. Only post-switch
outcomes may be changed:
returning a value that differs from the original for an endpoint whose
readout/event is at or before switch_time raises an error. This
argument can also be a list of functions that will be executed
sequentially. No default value.
...(optional) named arguments routed to one or more of
what, when, and how.
earliest_crossover_calendar_timenumeric. The earliest calendar
time at which the triplet(s) may take effect. 0 (default) is the
classic enrollment-time regimen, applied from the first enrollment. A
positive value marks the triplet(s) as a milestone-triggered crossover
(eligibility filtering, switch-time validation and the post-switch data
mask). This is set internally by trial$crossover(); it is not a
user argument of regimen().
Method get_number_treatment_allocator()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return number of treatment allocators for regimen
Usage
Regimens$get_number_treatment_allocator()
Method get_treatment_allocator()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return user-defined new treatment for a patient
Usage
Regimens$get_treatment_allocator(index = NULL)
Arguments
indexinteger. Index of allocator. Return all allocators if NULL.
Method get_time_selector()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return user-defined time selector
Usage
Regimens$get_time_selector(index = NULL)
Arguments
indexinteger. Index of selector. Return all selectors if NULL.
Method get_data_modifier()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return user-defined endpoint data modifier
Usage
Regimens$get_data_modifier(index = NULL)
Arguments
indexinteger. Index of selector. Return all modifiers if NULL.
Method get_treatment_allocator_args()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return pre-bound arguments for the i-th treatment allocator
Usage
Regimens$get_treatment_allocator_args(index)
Arguments
indexinteger.
Method get_time_selector_args()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return pre-bound arguments for the i-th time selector
Usage
Regimens$get_time_selector_args(index)
Arguments
indexinteger.
Method get_data_modifier_args()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return pre-bound arguments for the i-th data modifier
Usage
Regimens$get_data_modifier_args(index)
Arguments
indexinteger.
Method get_earliest_crossover_calendar_time()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return the earliest crossover calendar time of triplet(s)
Usage
Regimens$get_earliest_crossover_calendar_time(index = NULL)
Arguments
indexinteger. Index of triplet. Return all if NULL.
Method append_triplet()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
append one more triplet to the regimen. Used by milestone-triggered
crossover to stack a new what/when/how (with its own
earliest_crossover_calendar_time) onto an existing regimen without
overwriting earlier triplets. Triplets are executed in append order.
Usage
Regimens$append_triplet(
what,
when,
how,
...,
earliest_crossover_calendar_time = 0
)
Arguments
what, when, howsee regimen().
...(optional) named arguments routed to what, when,
and/or how.
earliest_crossover_calendar_timenumeric. Earliest calendar time
for the appended triplet. A positive value marks it as a crossover.
Method clone()
The objects of this class are cloneable with this method.
Usage
Regimens$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
TrialSimulator documentation built on Sept. 4, 2026, 5:08 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Regimens | R Documentation |
Class of Regimens
Description
Create a class of regimen. A regimen defines the rules to select treatments for patients switch, to determine the time of switching, and to update patients' endpoint data.
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, use regimen() to create a regimen and
register it with a trial through trial$add_regimen() or
trial$crossover().
Value
an R6Class generator object; use regimen() to create a regimen.
Methods
Public methods
Method new()
initialize regimen
Usage
Regimens$new(what, when, how, ..., earliest_crossover_calendar_time = 0)
Arguments
whata function determining whether patients' data would be updated due to switching treatment. It takes
patient_data, a data frame as argument, and returns a data frame of two columnspatient_idandnew_treatment, with one row per switching patient. The number of rows in the returned data frame may be smaller than the number of patients in the input data frame; patients that are left out are simply not switched. Values ofnew_treatmentmust not contain'@'or';', which are reserved for encodingregimen_trajectory. Note that the returned object will be passed into function 'how()', which is also provide by users. This argument can also be a list of functions that will be executed sequentially. No default value.whena function determining the time at which a patient switches to another treatment regimen, measured from the time of enrollment. It takes
patient_data, a data frame as argument, and returns a data frame of two columnspatient_idandswitch_time(fromenroll_time). The number of rows in the returned data frame must equal the number of rows inpatient_data, i.e., a switching time must be specified for every patient (missing values are not allowed). Note that the returned object will be passed into function 'how()', which is also provided by users. This argument can also be a list of functions that will be executed sequentially. No default value.howa function updating patients' data after treatment switching. Only modified columns and
patient_idare returned. For a cell that should not change, return its original value. Only post-switch outcomes may be changed: returning a value that differs from the original for an endpoint whose readout/event is at or beforeswitch_timeraises an error. This argument can also be a list of functions that will be executed sequentially. No default value....(optional) named arguments routed to one or more of
what,when, andhow.earliest_crossover_calendar_timenumeric. The earliest calendar time at which the triplet(s) may take effect.
0(default) is the classic enrollment-time regimen, applied from the first enrollment. A positive value marks the triplet(s) as a milestone-triggered crossover (eligibility filtering, switch-time validation and the post-switch data mask). This is set internally bytrial$crossover(); it is not a user argument ofregimen().
Method get_number_treatment_allocator()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return number of treatment allocators for regimen
Usage
Regimens$get_number_treatment_allocator()
Method get_treatment_allocator()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return user-defined new treatment for a patient
Usage
Regimens$get_treatment_allocator(index = NULL)
Arguments
indexinteger. Index of allocator. Return all allocators if
NULL.
Method get_time_selector()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return user-defined time selector
Usage
Regimens$get_time_selector(index = NULL)
Arguments
indexinteger. Index of selector. Return all selectors if
NULL.
Method get_data_modifier()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return user-defined endpoint data modifier
Usage
Regimens$get_data_modifier(index = NULL)
Arguments
indexinteger. Index of selector. Return all modifiers if
NULL.
Method get_treatment_allocator_args()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return pre-bound arguments for the i-th treatment allocator
Usage
Regimens$get_treatment_allocator_args(index)
Arguments
indexinteger.
Method get_time_selector_args()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return pre-bound arguments for the i-th time selector
Usage
Regimens$get_time_selector_args(index)
Arguments
indexinteger.
Method get_data_modifier_args()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return pre-bound arguments for the i-th data modifier
Usage
Regimens$get_data_modifier_args(index)
Arguments
indexinteger.
Method get_earliest_crossover_calendar_time()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
return the earliest crossover calendar time of triplet(s)
Usage
Regimens$get_earliest_crossover_calendar_time(index = NULL)
Arguments
indexinteger. Index of triplet. Return all if
NULL.
Method append_triplet()
INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.
append one more triplet to the regimen. Used by milestone-triggered
crossover to stack a new what/when/how (with its own
earliest_crossover_calendar_time) onto an existing regimen without
overwriting earlier triplets. Triplets are executed in append order.
Usage
Regimens$append_triplet( what, when, how, ..., earliest_crossover_calendar_time = 0 )
Arguments
what, when, howsee
regimen()....(optional) named arguments routed to
what,when, and/orhow.earliest_crossover_calendar_timenumeric. Earliest calendar time for the appended triplet. A positive value marks it as a crossover.
Method clone()
The objects of this class are cloneable with this method.
Usage
Regimens$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.