R/OXDSplot.R

In dcnorris/DTAT: Dose Titration Algorithm Tuning: a framework for dose individualization

#' Transparent visualization of a 3+3/PC dose-titration study
#' 
#' Visualize a 3+3/PC dose-titration study
#' 
#' Figure 1 of the reference below was generated by this function. Please see
#' the extended caption of that figure for details on interpretation of this
#' complex plot.
#' 
#' @param de A data frame describing a dose-titration study
#' @param tox.pending Set TRUE to show last-period DLT assessment pending
#' @param periods Number of periods of \code{de} to show
#' @param top.dose Highest dose level to show on the plot
#' @param ox.width Fraction of plot width occupied by the 'OX plot'
#' @return A \code{lattice} plot
#' @author David C. Norris
#' @seealso \code{\link{OXplot}}, \code{\link{xyplot.survfit}}
#' @references Norris DC. Precautionary Coherence Unravels Dose Escalation
#' Designs. bioRxiv. December 2017:240846. doi:10.1101/240846.
#' \url{https://www.biorxiv.org/content/early/2017/12/29/240846}
#' @keywords hplot survival
#' @export
OXDSplot <- function(de, tox.pending=FALSE, periods=max(de$period),
                     top.dose=max(de$dose), ox.width=0.7){
  ylim <- range(de$dose) + c(-0.5, 0.5) # xyplot.survfit default is insufficient
  ox <- OXplot(de, tox.pending=tox.pending, periods=periods, top.dose=top.dose)
  if(tox.pending){
    de <- de[de$period < max(de$period),]
  }
  if(top.dose < max(de$dose)){
    top.dose <- max(de$dose)
    warning(paste("Increasing top.dose to", top.dose, "to avoid lopping top off OXDSplot."))
  }
  fit <- dose.survfit(de)
  ds <- xyplot(fit, ylim=0.5+c(0, top.dose))
  print(ox, position=c(0, 0, ox.width+0.02, 1), more=TRUE)
  print(ds, position=c(ox.width-0.02, 0, 1, 1), more=FALSE)
}