R: Inverse (dose-finding) estimate of a target x value (e.g., a...

doseFind {cir}

R Documentation

Inverse (dose-finding) estimate of a target x value (e.g., a percentile)

Description

Inverse ("dose-finding") point estimation of a dose (x) for a specified target y value (e.g., a response rate), using a user-specified forward-estimation algorithm (default is CIR).

Usage

doseFind(
  y,
  x = NULL,
  wt = NULL,
  estfun = cirPAVA,
  target = NULL,
  full = FALSE,
  dec = FALSE,
  extrapolate = FALSE,
  errOnFlat = FALSE,
  adaptiveShrink = FALSE,
  starget = target[1],
  ...
)

Arguments

`y`	can be either of the following: y values (response rates), a 2-column matrix with positive/negative response counts by dose, a `DRtrace` object or a `doseResponse` object.
`x`	dose levels (if not included in y).
`wt`	weights (if not included in y).
`estfun`	the name of the dose-response estimation function. Default `cirPAVA`.
`target`	A vector of target response rate(s), for which the percentile dose estimate is needed. See Note.
`full`	logical, is a more complete output desired (relevant only for doseFind)? if `FALSE` (default), only a point estimate of the dose (x) for the provided target rate is returned.
`dec`	(relevant only for doseFind) logical, is the true function is assumed to be monotone decreasing? Default `FALSE`.
`extrapolate`	logical: should extrapolation beyond the range of estimated y values be allowed? Default `FALSE`.
`errOnFlat`	logical: in case the forward estimate is completely flat making dose-finding infeasible, should an error be returned? Under default (`FALSE`), `NA`s are returned for the target estimate.
`adaptiveShrink`	logical, should the y-values be pre-shrunk towards an experiment's target? Recommended if data were obtained via an adaptive dose-finding design. See `DRshrink` and the Note.
`starget`	The shrinkage target. Defaults to `target[1]`.
`...`	Other arguments passed on to `doseResponse` and `estfun`.

Details

The function works by calling estfun for forward estimation of the x-y relationship, then using approx with the x and y roles reversed for inverse estimation. The extrapolate option sets the rule argumet for this second call:

extrapolate=TRUE translates to rule=2, which actually means that the x value on the edge of the estimated y range will be assigned.
extrapolate=FALSE (default) translates to rule=1, which means an NA will be returned for any target y value lying outside the estimated y range.

Note also that the function is set up to work with a vector of targets.

If the data were obtained from an adaptive dose-finding design and you seek to estimate a dose other than the experiment's target, note that away from the target the estimates are likely biased (Flournoy and Oron, 2019). Use adaptiveShrink=TRUE to mitigate the bias. In addition, either provide the true target as starget, or a vector of values to target, with the first value being the true target.

Value

under default, returns point estimate(s) of the dose (x) for the provided target rate(s). With full=TRUE, returns a list with

targest The said point estimate of x
input a doseResponse object summarizing the input data
output a doseResponse object with the forward estimate at design points
shrinkage a doseResponse object which is the alg output of the forward-estimation function

Author(s)

Assaf P. Oron <assaf.oron.at.gmail.com>

References

Flournoy N and Oron AP, 2020. Bias Induced by Adaptive Dose-Finding Designs. Journal of Applied Statistics 47, 2431-2442.