Cpe-class: An R6 base class for designs requiring Complete Path...
In precautionary: Safety Diagnostics for Dose-Escalation Trial Designs
Description
Details
Public fields
Methods
Note
References
See Also
Description
An R6 base class for designs requiring Complete Path Enumeration
An R6 base class for designs requiring Complete Path Enumeration
Details
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.
Public fields
performanceA vector used for vetting performance
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
Method max_dose()
Usage
Cpe$max_dose(D)
Arguments
DA positive integer, the highest permissible dose.
Details
Set or query upper limit on further dosing
Returns
Self (invisibly), unless D is missing,
in which case the top dose, an integer, is returned.
Method bU()
Usage
Cpe$bU()
Details
Get the b vector and U matrix
Returns
Named list with components b and U
Method J()
Usage
Cpe$J()
Details
Get the number J of paths
Returns
Integer number of paths
Method applied()
Usage
Cpe$applied(x, o, last_dose, max_dose)
Arguments
xA dose-wise vector of toxicity counts
oA dose-wise vector of non-toxicity counts
last_doseThe most recently given dose, as required to implement
cumulative-cohort-based escalation decisions.
max_doseAn upper limit on future dose levels
Details
Return dose recommendation for given tox/no-tox tallies.
Returns
An object with components:
-
$stop - logical value indicating whether stop is indicated
-
$mtd - integer value, the recommended dose
-
$max_dose - integer value, a dose not to be exceeded henceforth.
Method report()
Usage
Cpe$report(...)
Arguments
...Optional columns to add to report
Details
Hook for concrete subclasses to implement for performance reporting
from method Cpe$trace_paths
Returns
NULL
Method trace_paths()
Usage
Cpe$trace_paths(root_dose, cohort_sizes, ..., prog = NULL, unroll = 4)
Arguments
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
Details
Compute trial paths forward from current tally
The computed paths are saved in a private field, from which variously
formatted results may be obtained by accessor functions.
Returns
Self, invisibly
Method path_matrix()
Usage
Cpe$path_matrix()
Details
Return computed trial paths in matrix form
Returns
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.
Method path_array()
Usage
Cpe$path_array(condense = TRUE)
Arguments
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.
Details
Return computed trial paths in a 3D array
Returns
For the jth path, the C*D matrix T[j,,] gives
the number of toxicities T[j,c,d] occurring in the cth
cohort for dose d. In case condense=FALSE, see above.
Method path_probs()
Usage
Cpe$path_probs(probs.DLT)
Arguments
probs.DLTNumeric vector of DLT probabilities for the design's
prespecified doses.
Details
Path probabilities for given dose-wise DLT probabilities
The design's paths must already have been completely enumerated by
trace_paths.
Returns
A vector of probabilities for the enumerated paths
Method path_rx()
Usage
Cpe$path_rx()
Details
Vector of path-wise final dose recommendations
The design's paths must already have been completely enumerated by
trace_paths. This method is a temporizing measure, bridging
to a new format for the return value of path_matrix, possibly
a data.table where the dose recs would be a column.
Returns
Integer vector of final dose recs on the enumerated paths
Method clone()
The objects of this class are cloneable with this method.
Usage
Cpe$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Note
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!
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
See Also
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.
precautionary documentation built on Aug. 9, 2021, 9:14 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Details Public fields Methods Note References See Also
Description
An R6 base class for designs requiring Complete Path Enumeration
An R6 base class for designs requiring Complete Path Enumeration
Details
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.
Public fields
performanceA vector used for vetting performance
Methods
Public methods
Method max_dose()
Usage
Cpe$max_dose(D)
Arguments
DA positive integer, the highest permissible dose.
Details
Set or query upper limit on further dosing
Returns
Self (invisibly), unless D is missing,
in which case the top dose, an integer, is returned.
Method bU()
Usage
Cpe$bU()
Details
Get the b vector and U matrix
Returns
Named list with components b and U
Method J()
Usage
Cpe$J()
Details
Get the number J of paths
Returns
Integer number of paths
Method applied()
Usage
Cpe$applied(x, o, last_dose, max_dose)
Arguments
xA dose-wise vector of toxicity counts
oA dose-wise vector of non-toxicity counts
last_doseThe most recently given dose, as required to implement cumulative-cohort-based escalation decisions.
max_doseAn upper limit on future dose levels
Details
Return dose recommendation for given tox/no-tox tallies.
Returns
An object with components:
-
$stop- logical value indicating whether stop is indicated -
$mtd- integer value, the recommended dose -
$max_dose- integer value, a dose not to be exceeded henceforth.
Method report()
Usage
Cpe$report(...)
Arguments
...Optional columns to add to report
Details
Hook for concrete subclasses to implement for performance reporting
from method Cpe$trace_paths
Returns
NULL
Method trace_paths()
Usage
Cpe$trace_paths(root_dose, cohort_sizes, ..., prog = NULL, unroll = 4)
Arguments
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 ofparallel::mclapplythat 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
Details
Compute trial paths forward from current tally
The computed paths are saved in a private field, from which variously formatted results may be obtained by accessor functions.
Returns
Self, invisibly
Method path_matrix()
Usage
Cpe$path_matrix()
Details
Return computed trial paths in matrix form
Returns
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.
Method path_array()
Usage
Cpe$path_array(condense = TRUE)
Arguments
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
cindex 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.
Details
Return computed trial paths in a 3D array
Returns
For the jth path, the C*D matrix T[j,,] gives
the number of toxicities T[j,c,d] occurring in the cth
cohort for dose d. In case condense=FALSE, see above.
Method path_probs()
Usage
Cpe$path_probs(probs.DLT)
Arguments
probs.DLTNumeric vector of DLT probabilities for the design's prespecified doses.
Details
Path probabilities for given dose-wise DLT probabilities
The design's paths must already have been completely enumerated by
trace_paths.
Returns
A vector of probabilities for the enumerated paths
Method path_rx()
Usage
Cpe$path_rx()
Details
Vector of path-wise final dose recommendations
The design's paths must already have been completely enumerated by
trace_paths. This method is a temporizing measure, bridging
to a new format for the return value of path_matrix, possibly
a data.table where the dose recs would be a column.
Returns
Integer vector of final dose recs on the enumerated paths
Method clone()
The objects of this class are cloneable with this method.
Usage
Cpe$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Note
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!
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
See Also
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.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.