An R6 base class for designs requiring Complete Path Enumeration
An R6 base class for designs requiring Complete Path Enumeration
TODO: Lots to be said here! The fundamental CPE concept has to be stated, and implementation strategy discussed as well. If it turns out this class ends up providing hooks for cacheing, this also needs to be detailed.
This state may in general decrease along a trial path, as for example with BOIN's dose elimination. (Designs which do not implement this safety feature may clarify this fact by overriding (TODO: or deleting?) this method.
Concrete subclasses must implement this abstract method.
If the parallel package were to incorporate the necessary
changes to mclapply, I could restore the following import!
This method might not work in case of non-constant cohort size.
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
path_matrix, path_table, path_array.
trace_paths, which must already have been invoked
if this method is to return a meaningful result.
trace_paths, which must already have been invoked
if this method is to return a result.
performanceA vector used for vetting performance
applied()report()trace_paths()root_doseThe starting dose for tree of paths
cohort_sizesInteger vector giving sizes of future cohorts, its length being the maximum number of cohorts to look ahead.
...Parameters passed ultimately to mclapply, presently
an unexported, specially adapted version of parallel::mclapply
that implements progress reporting.
progA function of a single integer, the current cumulative path count, to be used for progress reporting
unrollInteger; how deep to unroll path tree for parallelism
path_matrix()An integer matrix with the same column layout as the DTP tables of dtpcrm. That is, there is a D0 column followed by paired Tc, Dc columns giving the toxicity count for cohort c and the resulting dose recommendation yielded by cohort c -- which is generally the recommendation for cohort c+1.
path_array()condenseLogical value; if FALSE, the returned array has its
cohorts indexed trial-wise instead of dose-wise. This inflates the
array more than needed for the matrix computations it must support
(observe that in Norris2020c Eq. (4), the c index is eliminated
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.
path_probs()path_rx()decision_array()probs.DLTNumeric vector of DLT probabilities for the design's
prespecified doses; if provided, this is used to calculate path_probs
by which the returned array is weighted.
Sparse array indexing decisions by current tally
This very sparse array may be useful for investigating global properties
of dose-finding designs. The design's paths should already have been
completely enumerated by trace_paths before this method is invoked.
A 6-dimensional indicator array indexed by current-dose tally
numerator T and denominator N, current dose D, escalation decision
E with mapping c(des=1, sta=2, esc=3), current cohort number C,
and path index J. If probs.DLT is NULL (the default), the matrix
entries are drawn from 0, 1 or (for confluences of factors which did not
occur, and for which no decision was made) NA. When probs.DLT is
specified, these entries are weighted by their path probabilities.