quickIsotone {cir} | R Documentation |
One-Stop-shop Forward point and interval estimation via CIR or IR
Description
One-Stop-shop Forward point and confidence-interval estimation of a monotone response (y) as a function of dose (x), using centered-isotonic-regression (CIR, default) or isotonic regression. Input format is rather flexible.
This function calls cirPAVA
, oldPAVA
, iterCIR
(speculatively), or a user-written function, for the point estimate, then isotInterval
for the confidence interval. Vector input is allowed, but the preferred input format is a doseResponse
object.
An analogous function for dose-finding (inverse estimation) is quickInverse
.
Usage
quickIsotone(
y,
x = NULL,
wt = NULL,
outx = NULL,
dec = FALSE,
estfun = cirPAVA,
intfun = morrisCI,
conf = 0.9,
adaptiveShrink = FALSE,
...
)
Arguments
y |
can be either of the following: y values (response rates), a 2-column matrix with positive/negative response counts by dose, a |
x |
dose levels (if not included in y). Note that the PAV algorithm doesn't really use them. |
wt |
weights (if not included in y). |
outx |
vector of x values for which predictions will be made. If |
dec |
logical, is the true function assumed to be monotone decreasing rather than increasing? Default |
estfun |
the function to be used for point estimation. Default |
intfun |
the function to be used for interval estimation. Default |
conf |
numeric, the interval's confidence level as a fraction in (0,1). Default 0.9. |
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. If |
... |
arguments passed on to other functions (constructor, point estimate and interval estimate). |
Value
A data frame with 4 variables:
-
x
either the input x values, oroutx
of specified; -
y
The point estimates of x -
lowerPPconf,upperPPconf
the interval-boundary estimates for a 'PP'=100*conf
confidence interval
Note
You can obtain interpolated point estimates for x values between the observed data by specifying them via outx
. However, for CIR, do NOT commit the error of generating estimates at observations, then interpolating using approx
. If you need to retain a set of estimates for plotting the entire fitted curve, or for future interpolation at unknown points, call cirPAVA
directly with full=TRUE
, then use the returned shrinkage
data frame for plotting and interpolation. See example code below.
If the data were obtained from an adaptive dose-finding design then away from the design's target the estimates are likely biased (Flournoy and Oron, 2020). Use adaptiveShrink=TRUE
to mitigate the bias.
Author(s)
Assaf P. Oron <assaf.oron.at.gmail.com>
References
Oron, A.P. and Flournoy, N., 2017. Centered Isotonic Regression: Point and Interval Estimation for Dose-Response Studies. Statistics in Biopharmaceutical Research 9, 258-267. (author's public version available on arxiv.org).
Flournoy, N. and Oron, A.P., 2020. Bias Induced by Adaptive Dose-Finding Designs. Journal of Applied Statistics 47, 2431-2442.
See Also
cirPAVA
,oldPAVA
,isotInterval
,quickInverse
,doseResponse
Examples
# Interesting run (#664) from a simulated up-and-down ensemble:
# (x will be auto-generated as dose levels 1:5)
dat=doseResponse(y=c(1/7,1/8,1/2,1/4,4/17),wt=c(7,24,20,12,17))
# CIR, using the default 'quick' function that also provides CIs (default 90%).
# The experiment's goal is to find the 30th percentile. We deploy the empirical bias correction.
quick1=quickIsotone(dat, adaptiveShrink = TRUE, adaptiveCurve = TRUE, target = 0.3)
quick1
# Use 'estfun' argument to operate the same function with old PAVA as the estimator
# Here we neglect the bias correction to sharpen the old:new contrast
quick0=quickIsotone(dat,estfun=oldPAVA)
quick0
### Showing the data and the fits
par(mar=c(3,3,1,1),mgp=c(2,.5,0),tcl=-0.25)
plot(dat, ylim=c(0.05,0.55), las=1) # uses plot.doseResponse()
# The IR fit: a straightforward interpolation
lines(quick0$y,lty=2)
# With CIR, 'quickIsotone' cannot show us the true underlying interpolation;
# it only provides the estimates at requested points. Interpolation should be done between
# shrinkage points, not the original design points. So we must call the full 'cirPAVA' function:
slow1 = cirPAVA(dat, full=TRUE, adaptiveShrink = TRUE, adaptiveCurve = TRUE, target = 0.3)
# Now, compare these 3 (the first one is wrong, b/c it interpolates from design points):
midpts = 1:4 + 0.5
approx(1:5,quick1$y, xout=midpts)$y
# instead, you can just call 'quickIsotone' and specify 'outx'
quickIsotone(dat,outx=midpts , adaptiveShrink = TRUE, adaptiveCurve = TRUE, target = 0.3)
approx(slow1$shrinkage$x,slow1$shrinkage$y,xout=midpts)$y # Or use 'cirPAVA'
# Ok... finally plotting the CIR curve
# Both flat intervals are shrunk, because neither are at y=0 or y=1
lines(slow1$shrinkage$x,slow1$shrinkage$y, lwd = 2)
# Last but not least, here's the true response function
lines(seq(1,5,0.1),pweibull(seq(1,5,0.1),shape=1.1615,scale=8.4839),col=2)
legend('topleft',pch=c(NA,'X',NA,NA),lty=c(1,NA,2,1),col=c(2,1,1,1),
legend=c('True Curve','Observations','IR','CIR'), bty='n')