braidrm {braidrm} | R Documentation |
BRAID Synergy Dose-Response Modeling
Description
Calculates the best fit BRAID response surface given the concentrations of two drugs and the response of a measured target to the combination of those drugs.
Usage
## Default S3 method:
braidrm(model,data,getCIs=TRUE,fixed="kappa2",startparv=NULL,llims=NULL,ulims=NULL,...)
## S3 method for class 'formula'
braidrm(model,data,...)
## S3 method for class 'braidrm'
print(x, ...)
## S3 method for class 'braidrm'
summary(object, ...)
Arguments
model |
a two-column array containing concentrations of Drug 1 and Drug 2 in each dose pair, or a symbolic formula (e.g.
|
data |
if |
getCIs |
determines if confidence intervals will be calculated for all response surface parameters being fit. Parameters are fit using a bootstrapping approach which resamples residuals and refits the new data. |
fixed |
parameter specifying which parameters of the full BRAID model will be fit. See Details for a full description of this highly critical parameter |
startparv |
an optional parameter specifying starting parameter values for the optimization. The relationship between
|
llims |
a vector of lower limits on parameters being fit. May have length 10, or length equal to the number of
free parameters being fit. Any parameters that do not require a limit can have a value of |
ulims |
a vector of upper limits on parameters being fit. Follows same behavior as |
x |
the object of class "braidrm" to be printed |
object |
the object of class "braidrm" to be summarized |
... |
Not used |
Details
This function is designed to give as much control as is reasonably possible over which parameters are optimized and how the optimization behaves. However, implementing this much control can be quite complicated, and despite our efforts to make the function intuitive and transparent, the interface is still quite unwieldy. A great deal can be accomplished with the function simply using the model nicknames "kappa1" and "kappa2" (which constrain the two maximal effects to be equal or allow them to vary independently, respectively); if these are sufficient for you, feel free to ignore the remainder of this section.
The parameter fixed
is used to control which parameters are fit by the optimization, and in the case of the three maximal
effect parameters, how the parameters are constrained with respect to one another. fixed
may be specified in one of three
forms: a raw vector, an index vector, or a model nickname. There are seven model nicknames; using them is equivalent to using
the corresponding index vector as specified in the following table:
kappa1 | 1,2,3,4,6,7,10 |
kappa2 (default) | 1,2,3,4,6,7,8,9 |
kappa3 | 1,2,3,4,6,7,8,9,10 |
delta1 | 1,2,3,4,5,7,10 |
delta2 | 1,2,3,4,5,7,8,9 |
delta3 | 1,2,3,4,5,7,8,9,10 |
ebraid | 1,2,3,4,5,6,7,8,9,10 |
An index vector specifies which parameters vary in the optimization by listing their indices in the full ten parameter vector; a
raw vector specifies which parameters vary by setting the corresponding values equal to NA
. The remaining values in a raw
vector specify the values at which the fixed parameters are fixed, unless these values are overridden by startparv
startparv
specifies the starting values for the optimization; one can input a vector in startparv
that specifies
only the values of varying parameters, but the remaining values must be specified in a raw vector in fixed
. If a full-length
ten-element vector is provided for starparv
, the values of fixed parameters are taken from that vector, regardless of the
type of input in fixed
.
For parameters one through seven, the presence or absence of each parameter in the optimization is quite simple: either the parameter
is fixed at the specified (or calculated) value, or it varies between the specified (or calculated) optimization limits. Parameters
eight through ten, however, which specify the maximal effect parameters, are more complicated. The complication is introduced by the
fact that the parameters can be fixed or constrained to be equal to one another, which introduce the same number of degrees of
freedom, but very different optimization behaviors. How the different possibilities for fixed
and startparv
influence
the optimization behavior (for as many possibilities as we could think of) is described by the following table. In the table ,
,
, and
represent arbitrary but distinct valid values while ~ represents any valid (non-
NA
) value; in
addition, all startparv
vectors are assumed to be complete ten-element vectors (incomplete vectors will simply be extended
with the corresponding values in fixed
).
fixed | startparv | Behavior |
Index: ( ,8,9,10) or | Any | All three maximal effect parameters vary independently, |
Raw: ( ,NA ,NA ,NA ) | with constrained to be a larger effect than and |
|
. |
||
Index: ( ,8,9) or | NULL | and vary independently and is |
Raw: ( ,NA ,NA ,~) | constrained to vary with the larger effect of and |
|
. |
||
Index: ( ,8,9) or | ( , , , ) or | and vary independently and is |
Raw: ( ,NA ,NA ,~) | ( , , , ) or | constrained to vary with the larger effect of and |
( , , , ) | . |
|
Index: ( ,8,9) or | ( , , , ) or | is fixed at the value , while and vary |
Raw: ( ,NA ,NA ,~) | ( , , , ) | independently and are constrained to be smaller effects |
than . |
||
Index: ( ,10) or | NULL | All maximal parameters are constrained to vary as a |
Raw: ( , , ,NA ) | single parameter. | |
Raw: ( , , ,NA ) | NULL | If is larger than , and are constrained to |
vary as a single parameter above , and is fixed |
||
at . Otherwise, the roles of A and B are reversed. |
||
Index: ( ,10) or | ( , , , ) | All maximal parameters are constrained to vary as a |
Raw: ( ,~,~,NA ) | single parameter. | |
Index: ( ,10) or | ( , , , ) | and are constrained to vary as a single |
Raw: ( ,~,~,NA ) | parameter above , and is fixed at . |
|
Index: ( ,10) or | ( , , , ) | and are constrained to vary as a single |
Raw: ( ,~,~,NA ) | parameter above , and is fixed at . |
|
Index: ( ,10) or | ( , , , ) | is constrained to vary above the larger effect of |
Raw: ( ,~,~,NA ) | and , is fixed at , and is fixed at . |
|
Index: ( ,8,10) or | NULL or | varies freely, and and are constrained to |
Raw: ( ,NA ,~,NA ) | ( , ~, , ) | vary as a single parameter with a larger effect than . |
Index: ( ,8,10) or | ( , ~, , ) | varies freely, is fixed at and varies |
Raw: ( ,NA ,~,NA ) | freely constrained to be a larger effect than and |
|
. |
||
Index: ( ,9,10) or | NULL or | varies freely, and and are constrained to |
Raw: ( ,~,NA ,NA ) | ( , , ~, ) | vary as a single parameter with a larger effect than . |
Index: ( ,9,10) or | ( , , ~, ) | varies freely, is fixed at and varies |
Raw: ( ,~,NA ,NA ) | freely constrained to be a larger effect than and |
|
. |
||
Index: ( ,8) or | NULL | varies freely, is fixed at (or calculated |
Raw: ( ,NA , , ) | starting value), and is constrained to vary with |
|
the larger effect of and . |
||
Raw: ( ,NA , , ) | NULL | is fixed at , is fixed at , and varies |
freely constrained to be a smaller effect than . |
||
Index: ( ,8) or | ( , , , ) or | varies freely, is fixed at , and is |
Raw: ( ,NA ,~,~) | ( , , , ) or | constrained to vary with the larger effect of |
( , , , ) | and . |
|
Index: ( ,8) or | ( , , , ) or | is fixed at , is fixed at , and varies |
Raw: ( ,NA ,~,~) | ( , , , ) | freely constrained to be a smaller effect than . |
Index: ( ,9) or | NULL | varies freely, is fixed at (or calculated |
Raw: ( , ,NA , ) | starting value), and is constrained to vary with |
|
the larger effect of and . |
||
Raw: ( , ,NA , ) | NULL | is fixed at , is fixed at , and varies |
freely constrained to be a smaller effect than . |
||
Index: ( ,9) or | ( , , , ) or | varies freely, is fixed at , and is |
Raw: ( ,~,NA ,~) | ( , , , ) or | constrained to vary with the larger effect of |
( , , , ) | and . |
|
Index: ( ,9) or | ( , , , ) or | is fixed at , is fixed at , and varies |
Raw: ( ,~,NA ,~) | ( , , , ) | freely constrained to be a smaller effect than . |
Index: ( ) or | Any | All three values are fixed, and do not vary. |
Raw: ( ,~,~,~) |
Value
An object of class 'braidrm', including the elements
conc1 |
Concentrations of drug 1 used in the fit |
conc2 |
Concentrations of drug 2 used in the fit |
act |
Reponse to drugs 1 and 2 used in the fit |
fitted.values |
Value of best-fit response surface at concentrations of drugs 1 and 2 used in the fit |
residuals |
Difference between actual measurements and fitted values |
ostart |
The full 10-parameter starting parameter vector used in the optimization |
fixed |
Vector describing which parameters were fit |
mlims |
Array containing upper and lower parameter bounds used in the optimization |
coefficients |
Estimates of fitted parameters |
fullpar |
Full parameter vector including best-fit parameters |
convergence |
From |
message |
From |
call |
Function call |
If getCIs
is TRUE, then the following elements are also included
ciPass |
TRUE if a sufficient proportion of bootstrapping trials successfully converged, FALSE otherwise |
ciLevs |
Two-element vector specifying the lower and upper percentiles of the desired confidence interval. Defaults to 0.025 and 0.975 for a 95% confidence interval. |
ciVec |
Assuming 'ciPass' is true, a vector containing the lower and upper bounds on the confidence intervals of all free parameters |
bCoefs |
A matrix containing the best-fit parameter values from all bootstrapping trials. Useful for calculating confidence intervals on other values, such as EC99 |
Author(s)
Nathaniel R. Twarog
See Also
getBRAIDbootstrap
, calcBRAIDconfint
, evalBRAIDrsm
Examples
data(es8olatmz)
summary(braidrm(act~conc1+conc2,es8olatmz,getCIs=FALSE))
## Not run:
summary(braidrm(cbind(es8olatmz$conc1,es8olatmz$conc2),es8olatmz$act))
summary(braidrm(act~conc1+conc2,es8olatmz,fixed="delta2"))
summary(braidrm(act~conc1+conc2,es8olatmz,fixed=c(1,2,3,4,6,8,9)))
summary(braidrm(act~conc1+conc2,es8olatmz,llims=c(NA,NA,NA,NA,NA,NA,NA,-4,-4,-4)))
## End(Not run)