R/crossover.R

In TrialSimulator: Clinical Trial Simulator

#' Crossover at a Milestone
#'
#' @description
#'
#' Apply a milestone-triggered crossover to patients who are still in the trial.
#'
#' Unlike a regimen registered via \code{add_regimen()} (which is applied once,
#' at enrollment), \code{crossover()} is meant to be called \emph{inside} a
#' milestone's action function. At the earliest crossover (calendar) time
#' \code{T = trial$get_current_time() + delay}, eligible patients may switch to a
#' new treatment, and only their \emph{post-switch} endpoint values are altered;
#' already-observed data is left intact. The crossover triplet is stacked onto
#' the trial's regimen, so it is also re-applied to patients enrolled later.
#'
#' Eligibility (the pool passed to \code{what()}) consists of patients with at
#' least one endpoint still "open" (unobserved, dropout-/duration-aware) at
#' \code{T}; fully-observed patients are excluded. \code{when()} must return a
#' switch time with \code{enroll_time + switch_time >= T} (a crossover cannot
#' predate its opening) or an error is raised. \code{how()} may only change
#' post-switch outcomes; returning a changed value for a pre-switch/locked cell
#' raises an error.
#'
#' Two helper columns are injected into \code{patient_data} for the triplet
#' functions: \code{earliest_crossover_calendar_time} (\code{= T}) and
#' \code{earliest_crossover_time_from_enrollment} (\code{= max(T - enroll_time, 0)}),
#' so \code{when()} can write e.g.
#' \code{switch_time = pmax(pfs, earliest_crossover_time_from_enrollment)}.
#'
#' Note that this function should only be called within action functions of
#' milestones. It is users' responsibility to ensure that and
#' \code{TrialSimulator} has no way to track it.
#'
#' This is a user-friendly wrapper of the member function of trial, i.e.,
#' \code{Trials$crossover()}. Users who are not familiar with the concept of
#' classes may consider using this wrapper directly.
#'
#' @param trial a trial object returned by \code{trial()}.
#' @param what a function selecting which eligible patients crossover, returning
#' one row per crossing-over patient with their \code{new_treatment}. Values of
#' \code{new_treatment} must not contain \code{'@'} or \code{';'}, which are
#' reserved for encoding \code{regimen_trajectory}. See \code{regimen()}.
#' @param how a function returning the modified post-switch endpoint values for
#' crossing-over patients. See \code{regimen()}.
#' @param when (optional) a function returning \code{switch_time} from
#' enrollment. If \code{NULL} (default), patients switch at \code{T}, i.e.
#' \code{switch_time = earliest_crossover_time_from_enrollment}.
#' @param delay numeric. Time after the milestone before the crossover opens, so
#' \code{T = trial$get_current_time() + delay}. Default \code{0} (opens at the
#' milestone).
#' @param ... (optional) named arguments routed to \code{what}, \code{when},
#' and/or \code{how}.
#'
#' @return no return value, called for its side effect of updating \code{trial}.
#'
#' @export
#'
crossover <- function(trial, what, how, when = NULL, delay = 0, ...){

  trial$crossover(what = what, how = how, when = when, delay = delay, ...)

}