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

View source: R/invCIR.r

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

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.

See Also

oldPAVA,cirPAVA. If you'd like point and interval estimates together, use quickInverse.


cir documentation built on April 27, 2023, 9:05 a.m.