Spelling

R/ccd.R

@@ -3,13 +3,13 @@
 #'
 #' @details
 #' TODO: Explain the hierarchy of model classes, including connections
-#'       with the executable specifications set forth in exec/prolog/ccd.pl.
+#'       with the executable specifications set forth in `exec/prolog/ccd.pl`.
 #' @references
 #' 1. Ivanova A, Flournoy N, Chung Y. Cumulative cohort design for dose-finding.
 #'    Journal of Statistical Planning and Inference. 2007;137(7):2316-2327.
-#'    doi:10.1016/j.jspi.2006.07.009
+#'    \doi{10.1016/j.jspi.2006.07.009}
 #' 2. Liu S, Yuan Y. Bayesian optimal interval designs for phase I clinical trials.
-#'    J R Stat Soc C. 2015;64(3):507-523. doi:10.1111/rssc.12089
+#'    J R Stat Soc C. 2015;64(3):507-523. \doi{10.1111/rssc.12089}
 #' @importFrom R6 R6Class
 #' @export
 Ccd <- R6Class("Ccd",
@@ -23,7 +23,7 @@ Ccd <- R6Class("Ccd",
                  #' @param eliminate Elimination boundary
                  #' @param cohort_max Upper bound on dose-wise enrollment
                  #' @param enroll_max Upper bound on total enrollment
-                 #' @return A Ccd object.
+                 #' @return A `Ccd` object.
                  #'
                  #' @examples
                  #' # TODO

R/cpe.R

@@ -86,7 +86,6 @@ Cpe <- R6Class("Cpe",
                  #' @seealso `path_matrix`, `path_table`, `path_array`.
                  #' @note If the `parallel` package were to incorporate the necessary
                  #' changes to `mclapply`, I could restore the following import!
-                 #' #@importFrom parallel mclapply
                  trace_paths = function(root_dose, cohort_sizes, ..., prog = NULL, unroll = 4){
                    stopifnot("Only constant cohorts_sizes are supported currently" =
                                length(unique(cohort_sizes))==1)
@@ -208,8 +207,8 @@ Cpe <- R6Class("Cpe",
                  #' already by summation), but enables the sequence of events along a path
                  #' to be read off directly if this is required e.g. for visualization or
                  #' debugging. Default is TRUE.
-                 #' @return For the `j`'th path, the C*D matrix `T[j,,]` gives
-                 #' the number of toxicities `T[j,c,d]` occurring in the `c`'th
+                 #' @return For the `j`th path, the C*D matrix `T[j,,]` gives
+                 #' the number of toxicities `T[j,c,d]` occurring in the `c`th
                  #' cohort for dose d. In case `condense=FALSE`, see above.
                  #'
                  #' @references
@@ -279,12 +278,12 @@ Cpe <- R6Class("Cpe",
                    T_
                  }, # </path_array>
                  #' @details
-                 #' Path probabilities for given dose-wise DLT probs
+                 #' Path probabilities for given dose-wise DLT probabilities
                  #'
                  #' The design's paths must already have been completely enumerated by
                  #' `trace_paths`.
                  #' @param probs.DLT Numeric vector of DLT probabilities for the design's
-                 #' pre-specified doses.
+                 #' prespecified doses.
                  #' @return A vector of probabilities for the enumerated paths
                  path_probs = function(probs.DLT) {
                    if (is.null(private$b) || is.null(private$U))

R/crm.R

@@ -30,7 +30,7 @@ Crm <- R6Class("Crm",
                  #' @param skeleton CRM skeleton
                  #' @param scale Sigma parameter of prior on beta parameter
                  #' @param target Target toxicity rate
-                 #' @return A Crm object.
+                 #' @return A `Crm` object.
                  #'
                  #' @examples
                  #' # An example verbatim from dfcrm::crm()
@@ -52,7 +52,7 @@ Crm <- R6Class("Crm",
                    private$x <- private$o <- integer(length(private$ln_skel))
                  },
                  #' @details
-                 #' Return number of pre-specified doses
+                 #' Return number of prespecified doses
                  #' @note This specializes the superclass set/get method, consistent
                  #' with the non-mutable number of doses of CRM with fixed skeleton.
                  #'
@@ -401,12 +401,12 @@ Crm <- R6Class("Crm",
 ## s: A (scalar) scale factor
 
 
-#' A package-local (as-yet, unexported) test harness adapted from dfcrm::crm().
+#' A package-local (as-yet, unexported) test harness adapted from `dfcrm::crm()`.
 #'
-#' for various performance tuning experiments. The 'impl' arg allows selection
+#' for various performance tuning experiments. The `impl` arg allows selection
 #' of various alternative implementations:
-#' - rusti substitutes integrands crmh, crmht, crmht2 written in Rust
-#' - dfcrm is the original as implemented in package `dfcrm`.
+#' - `'rusti'` substitutes integrands `crmh`, `crmht`, `crmht2` written in Rust
+#' - `'dfcrm'` is the original as implemented in package `dfcrm`.
 #' @param prior The CRM skeleton: dose-wise prior probabilities of toxicity
 #' @param target Target toxicity rate
 #' @param tox A patient-wise vector of toxicity counts
@@ -415,23 +415,24 @@ Crm <- R6Class("Crm",
 #' @param dosename Optional designators for the doses
 #' @param include Index of patients to include
 #' @param pid Vector of patient ID labels
-#' @param conf.level Used to assign upper and lower bounds on predicted ptox,
-#' which in turn may be referenced in (de)escalation and stopping decisions.
+#' @param conf.level Used to assign upper and lower bounds on predicted probability
+#' of toxicity, which in turn may be referenced in escalation, deescalation and
+#' stopping decisions.
 #' @param method Estimation method:
 #' @param model Presently, only the \sQuote{empiric} (or \sQuote{power}) model
 #' has a Rust likelihood implementation.
 #' @param intcpt Intercept for \sQuote{logistic} model
 #' @param scale  Sigma parameter of prior on beta parameter
-#' @param model.detail If FALSE, the model content of an ‘"mtd"’ object will not
+#' @param model.detail If FALSE, the model content of an `mtd` object will not
 #' be displayed.  Default is TRUE.
-#' @param patient.detail If FALSE, patient summary of an ‘"mtd"’ object will not
+#' @param patient.detail If FALSE, patient summary of an `mtd` object will not
 #' be displayed.  Default is TRUE.
 #' @param var.est If TRUE, variance of the estimate of the model parameter and
 #' probability/confidence interval for the dose-toxicity curve will be computed
 #' @param impl Switch between `'rusti'` and `'dfcrm'` implementations.
 #' Currently the `'rusti'` option is implemented only for the Bayes method
 #' of the empirical (\sQuote{power}) model. An experimental `'ruste'`
-#' implementaton is in the works.
+#' implementation is in the works.
 #' @importFrom stats integrate optimize qnorm
 #' @importFrom dfcrm crmhlgt crmhtlgt crmht2lgt
 #' @importFrom dfcrm lcrm lcrmlgt

R/dtp.R

@@ -1,6 +1,6 @@
-#' A supremely faster version of a function from 'dtpcrm' v0.1.1
+#' A supremely faster version of a function from `dtpcrm` v0.1.1
 #'
-#' Originally, the sampling in stats::rnorm() (see inline comments in code)
+#' Originally, the sampling in `stats::rnorm()` (see inline comments in code)
 #' consumed 53% of run-time in a 6-cohort VIOLA DTP. After this change, it
 #' doesn't even show up! More importantly, the consumption is now dominated
 #' by (at 75%) by the objective function 'f' in integrate().
@@ -12,7 +12,7 @@
 #' trial stop is recommended.
 #' @return
 #' The `mtd` object x, with stop decision annotated
-#' @author Adapted by David C. Norris from original dtpcrm::stop_for_excess_toxicity_empiric
+#' @author Adapted by David C. Norris from original `dtpcrm::stop_for_excess_toxicity_empiric`
 #' @importFrom stats pnorm
 #' @export
 stop_for_excess_toxicity_empiric <- function (x, tox_lim, prob_cert, dose = 1,

R/exact.R

@@ -3,16 +3,16 @@
 setOldClass(c("exact","three_plus_three_selector_factory","tox_selector_factory","selector_factory"))
 
 #' A wrapper function supporting exact simulation of dose-escalation trials.
-#' 
+#'
 #' Implemented currently only for the (most?) common variant of the 3+3 design,
 #' which requires that at least 6 patients be treated at a dose before it may be
 #' declared as \sQuote{the} MTD.
-#' 
+#'
 #' @param selector_factory An object of type
 #'  \code{\link[escalation:get_three_plus_three]{three_plus_three_selector_factory}},
 #'  with `allow_deescalation = TRUE`.
 #'
-#' @details 
+#' @details
 #' In any given realization of a 3+3 design, each of the \eqn{D} prespecified doses
 #' will enroll 0, 1 or 2 cohorts, each with 3 patients. Each cohort will result in
 #' a tally of 0--3 dose-limiting toxicities (DLTs), and these may be recorded in a
@@ -34,27 +34,27 @@ setOldClass(c("exact","three_plus_three_selector_factory","tox_selector_factory"
 #' (Indeed, as you may verify at the R prompt, the above matrix is the 262nd of 442
 #' such paths enumerated comprehensively in the \eqn{2 \times 4 \times 442}{2 x 4 x 442}
 #' array `precautionary:::T[[4]]`.)
-#' 
+#'
 #' As detailed in Norris 2020c (below), these matrices may be used to construct simple
 #' matrix computations that altogether eliminate the need for discrete-event simulation
 #' of the 3+3 design. For each \eqn{D = 2,...,8}, the `precautionary` package has
 #' pretabulated a \eqn{J \times 2D}{J x 2D} matrix `precautionary:::U[[D]]` and
-#' \eqn{J}-vector `precautionary:::b[[D]]` such that the eqn{J}-vector \eqn{\pi}
+#' \eqn{J}-vector `precautionary:::b[[D]]` such that the \eqn{J}-vector \eqn{\pi}
 #' of path probabilities is given by:
 #' \deqn{
 #' log(\pi) = b + U [log(p), log(q)]',
 #' }
 #' where \eqn{p} is the \eqn{D}-vector of DLT probabilities at the prespecified
 #' doses, and \eqn{q \equiv 1-p}{q := 1-p} is its complement. See Eq. (4) of
 #' Norris (2020c).
-#' 
+#'
 #' For details on the enumeration itself, please see the Prolog code in directory
 #' `exec/` of the installed package.
-#' @references 
+#' @references
 #' Norris DC. What Were They Thinking? Pharmacologic priors implicit in a choice
 #' of 3+3 dose-escalation design. arXiv:2012.05301 \[stat.ME\]. December 2020.
 #' <https://arxiv.org/abs/2012.05301>
-#' @examples 
+#' @examples
 #' # Run an exact version of the simulation from FDA-proactive vignette
 #' design <- get_three_plus_three(
 #'   num_doses = 6
@@ -150,33 +150,33 @@ prob_administer.exact <- function(x, ...) {
 #'
 #' @importFrom escalation num_patients num_tox trial_duration
 print.exact <- function(x, ...) {
-  
+
   cat('Number of iterations:', length(x$fits), '\n')
   cat('\n')
-  
+
   cat('Number of doses:', length(x$dose_levels), '\n')
   cat('\n')
-  
+
   cat('True probability of toxicity:\n')
   print(x$true_prob_tox, digits = 3)
   cat('\n')
-  
+
   cat('Probability of recommendation:\n')
   print(prob_recommend(x), digits = 3)
   cat('\n')
-  
+
   cat('Probability of administration:\n')
   print(prob_administer(x), digits = 3)
   cat('\n')
-  
+
   cat('Sample size:\n')
   print(summary(num_patients(x)))
   cat('\n')
-  
+
   cat('Total toxicities:\n')
   print(summary(num_tox(x)))
   cat('\n')
-  
+
   cat('Trial duration:\n')
   print(summary(trial_duration(x)))
   cat('\n')
@@ -191,33 +191,33 @@ print.exact <- function(x, ...) {
 #'
 #' @importFrom escalation num_patients num_tox trial_duration
 print.hyper <- function(x, ...) {
-  
+
   cat('Number of iterations:', length(x$fits), '\n')
   cat('\n')
-  
+
   cat('Number of doses:', length(x$dose_levels), '\n')
   cat('\n')
-  
+
   cat('Average probability of toxicity:\n')
   print(x$avg_prob_tox, digits = 3)
   cat('\n')
-  
+
   cat('Probability of recommendation:\n')
   print(prob_recommend(x), digits = 3)
   cat('\n')
-  
+
   cat('Probability of administration:\n')
   print(prob_administer(x), digits = 3)
   cat('\n')
-  
+
   cat('Sample size:\n')
   print(summary(num_patients(x)))
   cat('\n')
-  
+
   cat('Total toxicities:\n')
   print(summary(num_tox(x)))
   cat('\n')
-  
+
   cat('Trial duration:\n')
   print(summary(trial_duration(x)))
   cat('\n')
@@ -268,12 +268,12 @@ as.data.table.exact <- function(x, keep.rownames = FALSE
 }
 
 #' Summarize an exact treatment of a dose-escalation design
-#' 
+#'
 #' Algorithmic (or 'rule-based') dose-escalation designs admit exact computation
 #' of their outcomes. This method summarizes such an exact treatment in a manner
 #' roughly parallel to that of `summary.precautionary`.
-#' 
-#' @param object An object of class 'exact' 
+#'
+#' @param object An object of class 'exact'
 #'
 #' @param ordinalizer An ordinalizer function
 #' @param ... Additional parameters passed to the ordinalizer

R/hyperprior.R

@@ -13,7 +13,8 @@
 #' the opportunity arises for a more encapsulated treatment of MTDi scenario
 #' generators ('hyperpriors') and their sampling. Specifically, individual
 #' sampled scenarios need only yield two functions:
-#' * A CDF taking a dose vector X = (X1,...,Xd) to probabilities p = (p1,...,pd)
+#' * A CDF taking a dose vector \deqn{X = (X_1,...,X_d)} to probabilities
+#'   \deqn{p = (p_1,...,p_d)}
 #' * A function F(X,kappa) yielding a fractionation matrix $F = \[0 G; H 0\]$.
 #' Crucially, this class actually represents an APPROXIMATION to the hyperprior,
 #' via a finite set of samples from it. The use of reference classes enables us
@@ -79,7 +80,7 @@ HyperMTDi_lognormal <- R6Class(
       invisible(self)
     },
     #' @details
-    #' Set or query the vector of pre-specified dose levels
+    #' Set or query the vector of prespecified dose levels
     #'
     #' @param x A vector of dose levels
     #' @return Self (invisibly), unless `x` is missing,
@@ -94,7 +95,7 @@ HyperMTDi_lognormal <- R6Class(
     #' @details
     #' Set or query a 'skeleton' probability vector
     #'
-    #' @param p A vector of probabilities, one for each pre-specified dose
+    #' @param p A vector of probabilities, one for each prespecified dose
     #' @return Self (invisibly), unless `p` is missing, in which case the
     #' skeleton probabilities are returned (after being calculated from the
     #' sample if not already set explicitly).
@@ -126,7 +127,7 @@ HyperMTDi_lognormal <- R6Class(
     },
     #' @details
     #' Get average toxicity probabilities over the sample
-    #' @return Toxicity probabilites at fixed doses, averaged over sample
+    #' @return Toxicity probabilities at fixed doses, averaged over sample
     avg_tox_probs = function() {
       self$apply(function(CV, median)
         function() {
@@ -137,7 +138,7 @@ HyperMTDi_lognormal <- R6Class(
     #' @details
     #' Return expected counts of ordinal toxicities
     #'
-    #' @param cpe An obect of class `Cpe`
+    #' @param cpe An object of class `Cpe`
     #' @param kappa A log-therapeutic index as in Eq (5) of Norris2020c
     #' @return An `nsamples`-by-6 matrix, each row being the expected counts
     #' for toxicity grades 0 through 5, at one sampled scenario.

R/precautionary-package.R

@@ -23,7 +23,7 @@
 #'    <https://www.biorxiv.org/content/10.1101/240846v1>
 #'
 #' 4. Norris DC. One-size-fits-all dosing in oncology wastes money, innovation
-#'    and lives. *Drug Discov Today*. 2018;23(1):4-6.
+#'    and lives. *Drug Discovery Today*. 2018;23(1):4-6.
 #'    \doi{10.1016/j.drudis.2017.11.008}.
 #'    <https://www.sciencedirect.com/science/article/pii/S1359644617303586>
 #'
@@ -85,7 +85,7 @@ NULL
 #'
 #' @section Version 0.2.8:
 #' * BOIN recs via isotonic regression
-#' * Testthat CPE matches BOIN::get.oc() sim
+#' * Test-that CPE matches `BOIN::get.oc()` sim
 #' * Implement CRM logistic model
 #'
 #' @section Version 0.2.9:
@@ -104,23 +104,23 @@ NULL
 #' * Native Rust CPE
 #'
 #' @section Dependencies:
-#' * Eliminate dependence on/adherence to dtpcrm layout
-#'   - Package dtpcrm makes many design decisions unsuited to
+#' * Eliminate dependence on/adherence to `dtpcrm` layout
+#'   - Package `dtpcrm` makes many design decisions unsuited to
 #'     comprehensive enumeration of whole trials.
-#'   - Allowing the Crm class to evolve along now-'natural' lines
+#'   - Allowing the `Crm` class to evolve along now-'natural' lines
 #'     probably makes a suitable 'plan' for now.
 #'   - Expunging superseded code/dependencies ASAP will facilitate
 #'     this evolution.
 #'   - Even the term 'DTP' seems not quite right anymore for a complete
 #'     path enumeration (CPE?), and should be abandoned.
-#' * Eliminate dependence on 'escalation' and 'dfcrm'
+#' * Eliminate dependence on `escalation` and `dfcrm`
 #'   - With the special emphasis on *speed* created by CPE,
 #'     I now must implement all underlying trial designs in Rust.
 #' * What may be retained in each case are 'Suggests:'-type relations,
-#'   wherever regression tests are helpful -- esp. wrt dfcrm.
+#'   wherever regression tests are helpful -- esp. wrt `dfcrm`.
 #'
 #' @section Fast CRM:
-#' * Benchmark; try mul_add()'s
+#' * Benchmark; try `mul_add()`s
 #'
 #' @section Document:
 #' * Add examples to the documented Rust functions
@@ -146,7 +146,7 @@ NULL
 #' * Index `sims$fits` to exact outcomes in `A[[D]]` where appropriate
 #'   - See the `haystack` function in `exact.R`
 #'
-#' @section Robustify:
+#' @section Robustness:
 #' * Tests comparing results from multiple CRAN packages
 #'
 #' @name plan