HyperMTDi-class: An R6 base class for hyperpriors over MTDi distributions

In precautionary: Safety Diagnostics for Dose-Escalation Trial Designs

Description

An R6 base class for hyperpriors over MTDi distributions

An R6 base class for hyperpriors over MTDi distributions

Details

With CPE liberating precautionary from the need for nested simulations, 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 = (X_1,...,X_d)

  to probabilities

  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 to improve this approximation efficiently by in-place updating.

Methods

Public methods

• HyperMTDi_lognormal$new()

• HyperMTDi_lognormal$resample()

• HyperMTDi_lognormal$nsamples()

• HyperMTDi_lognormal$extend()

• HyperMTDi_lognormal$doses()

• HyperMTDi_lognormal$skeleton()

• HyperMTDi_lognormal$apply()

• HyperMTDi_lognormal$avg_tox_probs()

• HyperMTDi_lognormal$fractionate()

• HyperMTDi_lognormal$plot()

• HyperMTDi_lognormal$clone()

---

Method new()

Usage

HyperMTDi_lognormal$new(CV, median_mtd, median_sdlog, units, n = 100)

Arguments

CV

Coefficient of variation of median MTDi

median_mtd

Median MTDi in the population

median_sdlog

Uncertainty in median MTDi, on log scale

units

A short string specifying dose units

n

Number of samples to draw

Details

Create a new HyperMTDi object.

Returns

A HyperMTDi object.

---

Method resample()

Usage

HyperMTDi_lognormal$resample(n)

Arguments

n

Number of samples to draw

Details

Draw fresh samples

Returns

Self, invisibly

---

Method nsamples()

Usage

HyperMTDi_lognormal$nsamples()

Details

Get number of samples TODO: Consider a higher-level interface to progress-bar info

Returns

Number of samples drawn so far

---

Method extend()

Usage

HyperMTDi_lognormal$extend(n = 1)

Arguments

n

Number of additional MTDi scenarios to sample

Details

Extend the samples, typically improving the approximation TODO: Investigate how much variance reduction QRNG yields.

Returns

Self, invisibly

---

Method doses()

Usage

HyperMTDi_lognormal$doses(x)

Arguments

x

A vector of dose levels

Details

Set or query the vector of prespecified dose levels

Returns

Self (invisibly), unless x is missing, in which case the dose vector is returned.

---

Method skeleton()

Usage

HyperMTDi_lognormal$skeleton(p)

Arguments

p

A vector of probabilities, one for each prespecified dose

Details

Set or query a 'skeleton' probability vector

Returns

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).

---

Method apply()

Usage

HyperMTDi_lognormal$apply(f, ...)

Arguments

f

A closure that realizes a distribution-type function (such as a quantile function or CDF) when evaluated in the environment defined by any row of the sampled parameters.

...

Arguments upon which to evaluate the enclosed function

Details

Apply a distribution-type function over the sampled realizations TODO: Consider taking this method private.

Returns

A list of values of f

---

Method avg_tox_probs()

Usage

HyperMTDi_lognormal$avg_tox_probs()

Details

Get average toxicity probabilities over the sample

Returns

Toxicity probabilities at fixed doses, averaged over sample

---

Method fractionate()

Usage

HyperMTDi_lognormal$fractionate(cpe, kappa)

Arguments

cpe

An object of class Cpe

kappa

A log-therapeutic index as in Eq (5) of Norris2020c

Details

Return expected counts of ordinal toxicities

Returns

An nsamples-by-6 matrix, each row being the expected counts for toxicity grades 0 through 5, at one sampled scenario.

---

Method plot()

Usage

HyperMTDi_lognormal$plot(col = "gray", xlim = NULL, ...)

Arguments

col

Color of lines used to depict samples

xlim

May be used to override the default dose-axis limits, which span the 1% to 99% quantiles of all samples.

...

Additional arguments passed onward to plot

Details

Visualize the samples of a HyperMTDi object

Examples

if (interactive()) {
mtdi_gen <- HyperMTDi_lognormal$new(CV = 1
                                   ,median_mtd = 5
                                   ,median_sdlog = 0.5
                                   ,units="mg/kg")
mtdi_gen$plot()
}

---

Method clone()

The objects of this class are cloneable with this method.

Usage

HyperMTDi_lognormal$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Note

This class implements a finite approximation to the infinite set of MTDi scenarios which it describes—an approximation which may be improved dynamically by expanding the samples.

See Also

Documentation for Cpe-class

Examples

## ------------------------------------------------
## Method `HyperMTDi_lognormal$plot`
## ------------------------------------------------

if (interactive()) {
mtdi_gen <- HyperMTDi_lognormal$new(CV = 1
                                   ,median_mtd = 5
                                   ,median_sdlog = 0.5
                                   ,units="mg/kg")
mtdi_gen$plot()
}

precautionary documentation built on Aug. 9, 2021, 9:14 a.m.