R: BRAID Synergy Dose-Response Modeling

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. `act ~ conc1+conc2`) specifying which variables are to be fit
`data`	if `model` is an array, a vector of measurements of response to the concentrations of Drug 1 and Drug 2; if `model` is a formula, a data frame containing the columns specified in `formula`
`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 `startparv` and `fixed` is rather subtle, and is discussed below in the Details section.
`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 `NA`. If `NULL` (the default), `llims` is calculated from the starting values in `startparv` (or the values calculated for `startparv` if `startparv` is not specified).
`ulims`	a vector of upper limits on parameters being fit. Follows same behavior as `llims`.
`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 W, X, Y, and Z 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: (`\ldots`,8,9,10) or	Any	All three maximal effect parameters vary independently,
Raw: (`\ldots`,`NA`,`NA`,`NA`)		with `E_f` constrained to be a larger effect than `E_{f,A}` and
		`E_{f,B}`.
Index: (`\ldots`,8,9) or	`NULL`	`E_{f,A}` and `E_{f,B}` vary independently and `E_f` is
Raw: (`\ldots`,`NA`,`NA`,~)		constrained to vary with the larger effect of `E_{f,A}` and
		`E_{f,B}`.
Index: (`\ldots`,8,9) or	(`\ldots`, `X`, `X`, `X`) or	`E_{f,A}` and `E_{f,B}` vary independently and `E_f` is
Raw: (`\ldots`,`NA`,`NA`,~)	(`\ldots`, `X`, `Y`, `X`) or	constrained to vary with the larger effect of `E_{f,A}` and
	(`\ldots`, `Y`, `X`, `X`)	`E_{f,B}`.
Index: (`\ldots`,8,9) or	(`\ldots`, `X`, `X`, `Y`) or	`E_f` is fixed at the value `Y`, while `E_{f,A}` and `E_{f,B}` vary
Raw: (`\ldots`,`NA`,`NA`,~)	(`\ldots`, `X`, `Z`, `Y`)	independently and are constrained to be smaller effects
		than `Y`.
Index: (`\ldots`,10) or	`NULL`	All maximal parameters are constrained to vary as a
Raw: (`\ldots`,`X`,`X`,`NA`)		single parameter.
Raw: (`\ldots`,`X`,`Y`,`NA`)	`NULL`	If `X` is larger than `Y`, `E_f` and `E_{f,A}` are constrained to
		vary as a single parameter above `Y`, and `E_{f,B}` is fixed
		at `Y`. Otherwise, the roles of A and B are reversed.
Index: (`\ldots`,10) or	(`\ldots`, `X`, `X`, `X`)	All maximal parameters are constrained to vary as a
Raw: (`\ldots`,~,~,`NA`)		single parameter.
Index: (`\ldots`,10) or	(`\ldots`, `X`, `Y`, `X`)	`E_f` and `E_{f,A}` are constrained to vary as a single
Raw: (`\ldots`,~,~,`NA`)		parameter above `Y`, and `E_{f,B}` is fixed at `Y`.
Index: (`\ldots`,10) or	(`\ldots`, `Y`, `X`, `X`)	`E_f` and `E_{f,B}` are constrained to vary as a single
Raw: (`\ldots`,~,~,`NA`)		parameter above `Y`, and `E_{f,A}` is fixed at `Y`.
Index: (`\ldots`,10) or	(`\ldots`, `X`, `Y`, `Z`)	`E_f` is constrained to vary above the larger effect of `X`
Raw: (`\ldots`,~,~,`NA`)		and `Y`, `E_{f,A}` is fixed at `X`, and `E_{f,B}` is fixed at `Y`.
Index: (`\ldots`,8,10) or	`NULL` or	`E_{f,A}` varies freely, and `E_{f,B}` and `E_f` are constrained to
Raw: (`\ldots`,`NA`,~,`NA`)	(`\ldots`, ~, `X`, `X`)	vary as a single parameter with a larger effect than `E_{f,A}`.
Index: (`\ldots`,8,10) or	(`\ldots`, ~, `X`, `Y`)	`E_{f,A}` varies freely, `E_{f,B}` is fixed at `X` and `E_f` varies
Raw: (`\ldots`,`NA`,~,`NA`)		freely constrained to be a larger effect than `E_{f,A}` and
		`E_{f,B}`.
Index: (`\ldots`,9,10) or	`NULL` or	`E_{f,B}` varies freely, and `E_{f,A}` and `E_f` are constrained to
Raw: (`\ldots`,~,`NA`,`NA`)	(`\ldots`, `X`, ~, `X`)	vary as a single parameter with a larger effect than `E_{f,B}`.
Index: (`\ldots`,9,10) or	(`\ldots`, `X`, ~, `Y`)	`E_{f,B}` varies freely, `E_{f,A}` is fixed at `X` and `E_f` varies
Raw: (`\ldots`,~,`NA`,`NA`)		freely constrained to be a larger effect than `E_{f,A}` and
		`E_{f,B}`.
Index: (`\ldots`,8) or	`NULL`	`E_{f,A}` varies freely, `E_{f,B}` is fixed at `X` (or calculated
Raw: (`\ldots`,`NA`,`X`,`X`)		starting value), and `E_f` is constrained to vary with
		the larger effect of `E_{f,A}` and `E_{f,B}`.
Raw: (`\ldots`,`NA`,`X`,`Y`)	`NULL`	`E_{f,B}` is fixed at `X`, `E_f` is fixed at `Y`, and `E_{f,A}` varies
		freely constrained to be a smaller effect than `Y`.
Index: (`\ldots`,8) or	(`\ldots`, `X`, `X`, `X`) or	`E_{f,A}` varies freely, `E_{f,B}` is fixed at `X`, and `E_f` is
Raw: (`\ldots`,`NA`,~,~)	(`\ldots`, `Y`, `X`, `X`) or	constrained to vary with the larger effect of `E_{f,A}`
	(`\ldots`, `Y`, `X`, `Y`)	and `E_{f,B}`.
Index: (`\ldots`,8) or	(`\ldots`, `X`, `X`, `Y`) or	`E_{f,B}` is fixed at `X`, `E_f` is fixed at `Y`, and `E_{f,A}` varies
Raw: (`\ldots`,`NA`,~,~)	(`\ldots`, `Z`, `X`, `Y`)	freely constrained to be a smaller effect than `Y`.
Index: (`\ldots`,9) or	`NULL`	`E_{f,B}` varies freely, `E_{f,A}` is fixed at `X` (or calculated
Raw: (`\ldots`,`X`,`NA`,`X`)		starting value), and `E_f` is constrained to vary with
		the larger effect of `E_{f,A}` and `E_{f,B}`.
Raw: (`\ldots`,`X`,`NA`,`Y`)	`NULL`	`E_{f,A}` is fixed at `X`, `E_f` is fixed at `Y`, and `E_{f,B}` varies
		freely constrained to be a smaller effect than `Y`.
Index: (`\ldots`,9) or	(`\ldots`, `X`, `X`, `X`) or	`E_{f,B}` varies freely, `E_{f,A}` is fixed at `X`, and `E_f` is
Raw: (`\ldots`,~,`NA`,~)	(`\ldots`, `X`, `Y`, `X`) or	constrained to vary with the larger effect of `E_{f,A}`
	(`\ldots`, `X`, `Y`, `Y`)	and `E_{f,B}`.
Index: (`\ldots`,9) or	(`\ldots`, `X`, `X`, `Y`) or	`E_{f,A}` is fixed at `X`, `E_f` is fixed at `Y`, and `E_{f,B}` varies
Raw: (`\ldots`,~,`NA`,~)	(`\ldots`, `X`, `Z`, `Y`)	freely constrained to be a smaller effect than `Y`.
Index: (`\ldots`) or	Any	All three values are fixed, and do not vary.
Raw: (`\ldots`,~,~,~)

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 `optim`, indicates if optimization successfully converged
`message`	From `optim`, describes results of non-linear optimization
`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

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)

[Package braidrm version 0.71 Index]