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).
doseFind(
y,
x = NULL,
wt = NULL,
estfun = cirPAVA,
target = NULL,
full = FALSE,
dec = FALSE,
extrapolate = FALSE,
errOnFlat = FALSE,
adaptiveShrink = FALSE,
starget = target[1],
tiemeth = "ordered",
...
)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
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).
the name of the dose-response estimation function. Default cirPAVA.
A vector of target response rate(s), for which the percentile dose estimate is needed. See Note.
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.
(relevant only for doseFind) logical, is the true function is assumed to be monotone decreasing? Default FALSE.
logical: should extrapolation beyond the range of estimated y values be allowed? Default FALSE.
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.
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.
The shrinkage target. Defaults to target[1].
The method to resolve ties. Default "decide", meaning the function chooses based on context. See Details.
Other arguments passed on to doseResponse and estfun.
Assaf P. Oron <assaf.oron.at.gmail.com>
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. It is expected that most users will not interact with this function directly, but rather indirectly via the convenience wrapper quickInverse.
The extrapolate option sets the rule argument 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.
Tie-breaking - the tiemeth argument passed on as the ties argument for approx() - provides yet another complication: as of 2.5.0, the default is "decide", which means "ordered" - unless target falls on the boundary of y estimates, in which case the most interior x value is chosen. A user-chosen value for tiemeth will override all of that; see ?approx for options.
Flournoy N and Oron AP, 2020. Bias Induced by Adaptive Dose-Finding Designs. Journal of Applied Statistics 47, 2431-2442.
oldPAVA,cirPAVA. If you'd like point and interval estimates together, use quickInverse.