R/DTAT-package.R

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

#' Simulated '3+3/PC' dose-titration study from bioRxiv paper no. 240846
#' 
#' This is a length-10 list
#' 
#' 
#' @name de.bioRxiv.240846
#' @docType data
#' @format The format is: List of 10 $ :'data.frame': 3 obs. of 4 variables:
#' ..$ id : int \[1:3\] 1 2 3 ..$ period: num \[1:3\] 1 1 1 ..$ dose : num \[1:3\] 1
#' 1 1 ..$ dlt : logi \[1:3\] FALSE FALSE FALSE $ :'data.frame': 9 obs. of 4
#' variables: ..$ id : int \[1:9\] 1 2 3 4 5 6 1 2 3 ..$ period: num \[1:9\] 1 1 1
#' 2 2 2 2 2 2 ..$ dose : num \[1:9\] 1 1 1 1 1 1 2 2 2 ..$ dlt : logi \[1:9\]
#' FALSE FALSE FALSE FALSE FALSE FALSE ...  $ :'data.frame': 18 obs. of 4
#' variables: ..$ id : int \[1:18\] 1 2 3 4 5 6 1 2 3 7 ...  ..$ period: num
#' \[1:18\] 1 1 1 2 2 2 2 2 2 3 ...  ..$ dose : num \[1:18\] 1 1 1 1 1 1 2 2 2 1
#' ...  ..$ dlt : logi \[1:18\] FALSE FALSE FALSE FALSE FALSE FALSE ...  $
#' :'data.frame': 30 obs. of 4 variables: ..$ id : int \[1:30\] 1 2 3 4 5 6 1 2 3
#' 7 ...  ..$ period: num \[1:30\] 1 1 1 2 2 2 2 2 2 3 ...  ..$ dose : num \[1:30\]
#' 1 1 1 1 1 1 2 2 2 1 ...  ..$ dlt : logi \[1:30\] FALSE FALSE FALSE FALSE FALSE
#' FALSE ...  $ :'data.frame': 45 obs. of 4 variables: ..$ id : int \[1:45\] 1 2
#' 3 4 5 6 1 2 3 7 ...  ..$ period: num \[1:45\] 1 1 1 2 2 2 2 2 2 3 ...  ..$
#' dose : num \[1:45\] 1 1 1 1 1 1 2 2 2 1 ...  ..$ dlt : logi \[1:45\] FALSE FALSE
#' FALSE FALSE FALSE FALSE ...  $ :'data.frame': 61 obs. of 4 variables: ..$ id
#' : int \[1:61\] 1 2 3 4 5 6 1 2 3 7 ...  ..$ period: num \[1:61\] 1 1 1 2 2 2 2 2
#' 2 3 ...  ..$ dose : num \[1:61\] 1 1 1 1 1 1 2 2 2 1 ...  ..$ dlt : logi
#' \[1:61\] FALSE FALSE FALSE FALSE FALSE FALSE ...  $ :'data.frame': 77 obs. of
#' 4 variables: ..$ id : int \[1:77\] 1 2 3 4 5 6 1 2 3 7 ...  ..$ period: num
#' \[1:77\] 1 1 1 2 2 2 2 2 2 3 ...  ..$ dose : num \[1:77\] 1 1 1 1 1 1 2 2 2 1
#' ...  ..$ dlt : logi \[1:77\] FALSE FALSE FALSE FALSE FALSE FALSE ...  $
#' :'data.frame': 89 obs. of 4 variables: ..$ id : int \[1:89\] 1 2 3 4 5 6 1 2 3
#' 7 ...  ..$ period: num \[1:89\] 1 1 1 2 2 2 2 2 2 3 ...  ..$ dose : num \[1:89\]
#' 1 1 1 1 1 1 2 2 2 1 ...  ..$ dlt : logi \[1:89\] FALSE FALSE FALSE FALSE FALSE
#' FALSE ...  ..- attr(*, "stop.esc")= num 7 $ :'data.frame': 99 obs. of 4
#' variables: ..$ id : int \[1:99\] 1 2 3 4 5 6 1 2 3 7 ...  ..$ period: num
#' \[1:99\] 1 1 1 2 2 2 2 2 2 3 ...  ..$ dose : num \[1:99\] 1 1 1 1 1 1 2 2 2 1
#' ...  ..$ dlt : logi \[1:99\] FALSE FALSE FALSE FALSE FALSE FALSE ...  ..-
#' attr(*, "stop.esc")= num 7 $ :'data.frame': 104 obs. of 4 variables: ..$ id
#' : int \[1:104\] 1 2 3 4 5 6 1 2 3 7 ...  ..$ period: num \[1:104\] 1 1 1 2 2 2 2
#' 2 2 3 ...  ..$ dose : num \[1:104\] 1 1 1 1 1 1 2 2 2 1 ...  ..$ dlt : logi
#' \[1:104\] FALSE FALSE FALSE FALSE FALSE FALSE ...  ..- attr(*, "stop.esc")=
#' num 7
#' @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 datasets
#' @examples
#' 
#' data(de.bioRxiv.240846)
#' ## maybe OXDSplot(last(de))
#' 
NULL





#' c("\\Sexpr[results=rd,stage=build]{tools:::Rd_package_title(\"DTAT\")}",
#' "DTAT")\Sexpr{tools:::Rd_package_title("DTAT")}
#' 
#' c("\\Sexpr[results=rd,stage=build]{tools:::Rd_package_description(\"DTAT\")}",
#' "DTAT")\Sexpr{tools:::Rd_package_description("DTAT")}
#' 
#' 
#' The DESCRIPTION file:
#' c("\\Sexpr[results=rd,stage=build]{tools:::Rd_package_DESCRIPTION(\"DTAT\")}",
#' "DTAT")\Sexpr{tools:::Rd_package_DESCRIPTION("DTAT")}
#' c("\\Sexpr[results=rd,stage=build]{tools:::Rd_package_indices(\"DTAT\")}",
#' "DTAT")\Sexpr{tools:::Rd_package_indices("DTAT")} ~~ An overview of how to
#' use the package, including the most important functions ~~
#' 
#' @name DTAT-package
#' @aliases DTAT-package DTAT
#' @docType package
#' @author
#' c("\\Sexpr[results=rd,stage=build]{tools:::Rd_package_author(\"DTAT\")}",
#' "DTAT")\Sexpr{tools:::Rd_package_author("DTAT")}
#' 
#' Maintainer:
#' c("\\Sexpr[results=rd,stage=build]{tools:::Rd_package_maintainer(\"DTAT\")}",
#' "DTAT")\Sexpr{tools:::Rd_package_maintainer("DTAT")}
#' @seealso \code{\link[pomp:pomp-package]{pomp}}
#' @references Norris DC. Dose Titration Algorithm Tuning (DTAT) should
#' supersede 'the' Maximum Tolerated Dose (MTD) in oncology dose-finding
#' trials. F1000Research. 2017;6:112. doi:10.12688/f1000research.10624.3.
#' \url{https://f1000research.com/articles/6-112/v3}
#' 
#' Norris DC. Costing 'the' MTD. bioRxiv. August 2017:150821.
#' doi:10.1101/150821.
#' \url{http://www.biorxiv.org/content/early/2017/08/22/150821}
#' 
#' 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}
#' @import lattice
#' @importFrom pomp pomp euler.sim rprior trajectory Csnippet
#' @import survival
#' @import methods
NULL





#' Precomputed neutrophil-guided chemotherapy dose titration for 1000 simulated
#' subjects.
#' 
#' This dataset is provided to support fast reproduction of a forthcoming
#' pharmacoeconomic paper that includes examination of the empirical
#' distribution of MTDi in N=1000 simulated subjects.
#' 
#' Running the examples interactively, you can verify the reproducibility of
#' this dataset. (That demo is included in a \code{donttest} block to spare the
#' CRAN servers.)
#' 
#' @name dtat1000
#' @docType data
#' @format A data frame showing end-of-cycle state of neutrophil-guided dose
#' titration for 1000 simulated subjects, across 10 cycles of chemotherapy.
#' \describe{ \item{cycle}{Cycle number 1..10}
#' \item{id}{Subject identifiers; an ordered factor with levels
#' \code{id1} < \dots{} < \code{id1000}} \item{Cc}{Central-compartment
#' drug concentration} \item{Cp}{Peripheral-compartment drug
#' concentration} \item{Prol}{Progenitor cells in proliferating
#' compartment of Friberg et al (2002) model} \item{Tx.1}{Transit
#' compartment 1} \item{Tx.2}{Transit compartment 1}
#' \item{Tx.3}{Transit compartment 1} \item{Circ}{Concentration
#' (cells/mm^3) of circulating neutrophils} \item{dose}{Dose of 1-hour
#' infusion administered this cycle} \item{CircMin}{Neutrophil nadir
#' (cells/mm^3)} \item{tNadir}{Time (days) of neutrophil nadir}
#' \item{scaled.dose}{Fourth root of dose} \item{time}{Time
#' (weeks) of dose administration} }
#' @references 1. Norris DC. Dose Titration Algorithm Tuning (DTAT) should
#' supersede 'the' Maximum Tolerated Dose (MTD) in oncology dose-finding
#' trials. F1000Research. 2017;6:112. doi:10.12688/f1000research.10624.3.
#' \url{https://f1000research.com/articles/6-112/v3}
#' 
#' 2. Norris DC. Costing 'the' MTD. bioRxiv. August 2017:150821.
#' doi:10.1101/150821.
#' \url{http://www.biorxiv.org/content/early/2017/08/22/150821}
#' @keywords datasets
#' @examples
#' 
#' data(dtat1000)
#' # 1. Extract the N final doses, assuming convergence by the tenth course
#' MTD_i <- with(dtat1000, dose[time==27])
#' MTD_i <- MTD_i[MTD_i < 5000] # Exclude few outliers
#' # 2. Do a kernel density plot
#' library(rms)
#' hist <- histogram(~MTD_i, breaks=c(0,100,200,300,400,600,900,1500,2500,4000,5000)
#'                   , xlab=expression(MTD[i]))
#' approx <- data.frame(mtd_i=seq(0, 5000, 10))
#' approx <- upData(approx,
#'                  gamma = dgamma(mtd_i, shape=1.75, scale=200))
#' dist <- xyplot(gamma ~ mtd_i, data=approx, type='l', col='black', lwd=2)
#' library(grid)
#' hist + dist
#' grid.text(expression(MTD[i] %~%
#'                      paste("Gamma(", alpha==1.75, ", ", beta==1/200,")"))
#'          , x=unit(0.5,"npc")
#'          , y=unit(0.75,"npc")
#'          )
#' \donttest{
#' # Demonstrate exact reproduction of this data set (the titration takes many minutes!)
#' set.seed(2016)
#' Onoue.Friberg(N=1000)
#' # This titration may take an hour to run ...
#' chemo <- titrate(doserange = 100,
#'                  dta=newton.raphson(dose1 = 100,
#'                                     omega = 0.75,
#'                                     slope1 = -2.0,
#'                                     slopeU = -0.2)
#' )
#' 
#' dtat1k <- upData(chemo$course
#'                 , time = 3*(cycle-1)
#'                 , labels = c(time="Time")
#'                 , units = c(time="weeks")
#'                 , print = FALSE)
#' 
#' stopifnot(identical(dtat1k, dtat1000))
#' } # end 'donttest'
#' 
NULL





#' Shiny bindings for oxds
#' 
#' Output and render functions for using oxds within Shiny applications and
#' interactive Rmd documents.
#' 
#' @name oxds-shiny
#' @aliases oxds-shiny oxdsOutput renderOxds
#' @param outputId output variable to read from
#' @param width,height Must be a valid CSS unit (like \code{'100\%'},
#' \code{'400px'}, \code{'auto'}) or a number, which will be coerced
#' to a string and have \code{'px'} appended.
#' @param expr An expression that generates an oxds
#' @param env The environment in which to evaluate \code{expr}.
#' @param quoted Is \code{expr} a quoted expression (with \code{quote()})? This
#' is useful if you want to save an expression in a variable.
NULL





#' Environment for simulation global variables.
#' 
#' To simplify the code of package:DTAT, as well as client tasks, this exported
#' environment contains a handful of global variables useful for the
#' simulations.
#' 
#' Global variables maintained within environment \code{sim} are: \enumerate{
#' \item \code{pkpd}: The population PK/PD model to be simulated.  \item
#' \code{pop}: A sample drawn from the population model.  \item \code{N}:
#' Restricts simulation to first \code{N} subjects in \code{pop}.  \item
#' \code{inits_fac}: An initializer factory taking an initial state as
#' argument.  \item \code{params.default}: Default parameters.  \item Regular
#' lines start with a non-whitespace character.  \item Records are separated by
#' one or more empty lines. }
#' 
#' @export
#' @name sim
#' @docType data
#' @keywords datasets
#' @examples
#' 
#' # Even when nrow(pop) is large, one may easily restrict
#' # time-consuming simulations to pop[1:N,], as follows:
#' sim$N <- 25
#' # Now perform simulation work
#' \dontrun{doChemo(...)}
#' 
NULL