doseFind: 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

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.

dose levels (if not included in y).

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

Value

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

xout The said point estimate of x
input a doseResponse object summarizing the input data
cir a doseResponse object which is the alg output of the forward-estimation function

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.

References

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