R/regimen.R

In TrialSimulator: Clinical Trial Simulator

#' Define a Regimen
#'
#' @description
#' Define a regimen of a trial. This is a user-friendly wrapper for
#' the class constructor \code{Regimens$new()}. Users who are not familiar with
#' the concept of classes may consider using this wrapper directly.
#'
#' A regimen defines the rules to select patients who
#' switch treatments, to determine the time of switching, and to update patients'
#' endpoint data.
#'
#' @param what a function determining whether patients' data would be
#' updated due to switching treatment. It takes \code{patient_data},
#' a data frame as argument, and returns a data frame of two columns
#' \code{patient_id} and \code{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 \code{new_treatment} must not contain
#' \code{'@'} or \code{';'}, which are reserved for encoding
#' \code{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.
#' @param when a function determining the time at which a patient switches
#' to another treatment regimen, measured from the time of enrollment.
#' It takes \code{patient_data}, a data frame as
#' argument, and returns a data frame of two columns \code{patient_id} and
#' \code{switch_time} (from \code{enroll_time}). The number of rows in the
#' returned data frame must equal the number of rows in \code{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.
#' @param how a function updating patients' data after treatment switching.
#' Only modified columns and \code{patient_id} are returned. For a cell that
#' should not change, return its original value. Only \emph{post-switch}
#' outcomes may be changed: returning a value that differs from the original
#' for an endpoint whose readout/event is at or before \code{switch_time} (a
#' pre-switch or already-observed outcome) raises an error, so leave such cells
#' at their original value (e.g. \code{ifelse(os > switch_time, new_os, os)}).
#' This argument can also be a list of functions that will be executed
#' sequentially. No default value.
#' @param ... (optional) named arguments to be passed to one or more of
#' \code{what}, \code{when}, and \code{how}. Each argument is routed to every
#' function whose formal parameter list contains that name. All arguments must
#' be named, and every name must match at least one parameter of at least one
#' function in \code{what}, \code{when}, or \code{how}.
#'
#' @return an object of R6 class \code{Regimens}, representing a treatment regimen.
#'
#' @export
#'
regimen <- function(what, when, how, ...){

  if('earliest_crossover_calendar_time' %in% names(list(...))){
    stop('`earliest_crossover_calendar_time` is not a user argument of regimen(); ',
         'it is set internally by trial$crossover(). ')
  }

  Regimens$new(
    what = what,
    when = when,
    how = how,
    ...
  )

}