braidrm {braidrm} | R Documentation |
BRAID Response Surface Fitting
Description
Fits a BRAID response surface model to data.
Usage
braidrm(
formula,
data,
model = "kappa2",
links = NULL,
weights = NULL,
start = NULL,
direction = 0,
lower = NULL,
upper = NULL,
prior = "moderate",
getCIs = TRUE
)
## S3 method for class 'braidrm'
summary(object, ...)
## S3 method for class 'summary.braidrm'
print(x, ...)
## S3 method for class 'braidrm'
print(x, ...)
## S3 method for class 'formula'
braidrm(
formula,
data,
model = "kappa2",
links = NULL,
weights = NULL,
start = NULL,
direction = 0,
lower = NULL,
upper = NULL,
prior = "moderate",
getCIs = TRUE
)
## Default S3 method:
braidrm(
formula,
data,
model = "kappa2",
links = NULL,
weights = NULL,
start = NULL,
direction = 0,
lower = NULL,
upper = NULL,
prior = "moderate",
getCIs = TRUE
)
Arguments
formula |
Either an object of class |
data |
If |
model , links |
Parameters |
weights |
A vector of weights (between 0 and 1) the same length as
the data which determines the weight with which each measurement
will impact the the sum of squared errors. Weights will be multiplied by
errors before squaring. If |
start |
A BRAID parameter vector specifying the first guess where the
non-linear optimization should begin. May be a length 7, 8, or 9 vector,
though a full length vector is always preferable. If |
direction |
Determines the possible directionality of the BRAID model. If 0 (the default) no additional constraints are placed on the parameters. If greater than 0, the fitting will require that the maximal effects are all greater than or equal to the minimal effect. If less than 0, the fitting will require that all maximal effect is less than or equal to the minimal effect. |
lower |
A numeric vector of lower bounds on the fitted parameter values.
May be the same length as the number of fitted parameters, or a full,
length-9 vector. Missing or unspecified lower bounds may be included as |
upper |
A numeric vector of upper bounds on the fitted parameter values.
Used in the same way as |
prior |
A character string specifying the desired Bayesian prior term
for kappa, or an object of class |
getCIs |
Should bootstrapped confidence intervals be estimated and
added to the BRAID fit object. Default value is |
object |
An object of class |
... |
Further arguments passed to or from other methods. |
x |
An object of class |
Details
One of the hairiest and most confusing aspects of fitting a combined
response surface model is handling the relationships between maximal effects.
Unlike a simple dose response model such as those fit in basicdrm
in which
all parameters can be treated as fairly independent, response surface models
are often considered with constraints that cannot be expressed as simply one
parameter being fixed a particular value. Many response surface models
assume that the two drugs in combination (and the overall combination) share
a single common maximal effect; others might assume that the maximal effects
of the two drugs should differ but that the overall maximal effect must be
equal to one of these; still others may wish to fit with no constraints on
maximal effect at all beyond guaranteeing that they lie above a fixed
minimal effect. All these approaches are valid, and creating a functional
interface to support them all is a challenge. The parameters given here
represent our best effort to balance ease-of-use with flexibility.
The primary interface for model selection and customization is the paired
paramters model
and links
. For the first six parameters of the BRAID
surface, model
is the only relevant control, and operates much as it would
in any fitting function. If a given parameter (say IDMB) is included in
model
(as index 2) then it will vary freely within the provided bounds to
best fit the data. If it is not, the value will be fixed at the value given
in start
(or if start
is NULL
, estimated from the data), and will
remain fixed at that value in the best fit surface.
Parameters EfA, EfB, and Ef (the maximal effect parameters) require slightly
more care. Relationships between these values is represented by the links
parameter, which can take on one of the following five values:
"AB": Indicating that the overall Ef parameter is the driver, both EfA and EfB are constrained to be equal to Ef, whatever its value. Can be used when indices 7 and 8 (EfA and EfB) are absent from
model
, but index 9 (Ef) is present"F": Indicating instead that the individual parameters EfA and EfB are the drivers, and EfA is constrained to be equal to larger magnitude of the two. Can be used when indices 7 and 8 are present
model
, but index 9 is absent"A": Specifies that the overall maximal effect is equal to that of the first trug (and consequentially that the effect of drug A must be of greater or equal magnitude to that of drug B). Can be used when index 7 is absent in
model
and index 9 is present; index 8 may be present or absent"B": Specifies that the overall maximal effect is equal to that of the second drug. Can be used when index 8 is absent in
model
and index 9 is present; index 7 may be present or absent"" (the empty string): Indicates no equality between maximal effects. Parameters that are present in
model
vary freely in fitting, those that are absent are fixed at constant values.
For example, if the maximal effects should be fit, but should be
constrained to be all equal, then it is the parameter Ef that varies freely
in the fitting; the fact that EfA and EfB are always equal to this value is
represented by setting the links
parameter to "AB". Contrast this with the
(admittedly much less common) scenario in which the links
parameter is set
to the empty string "", representing no link between maximal effects. In this
case the parameter Ef will indeed vary freely in the fitting, but EfA and
EfB will instead always be held at the constant initial values in the
starting parameter vector. On the other hand, if we were to assume that the
two individual maximum effect parameters can vary independently, but that
the overall maximal effect should be equal to the larger of the two, then
indices 7 and 8 (representing EfA and EfB) would be included in model
;
index 9 (representing Ef) would be excluded, and the links
parameter would
be set to "F" indicating that Ef is tied to the larger of the two.
Note also that the default value for links
is not the empty string, but
instead NULL
. By default the value of links
will be guessed from the
model vector, based on the scenarios that we have encountered most often.
If model
inclues Ef (index 9) but not EfA or EfB (indices 7 and 8), links
is assumed to be "F"; if EfA and EfB are present but not Ef, links
is set
to "AB". In the vast majority of cases, you will not need to specify this
parameter yourself. This is especially true when model
is specified with
one of the model strings, in which any provided value for links
will be
discarded and replaced witht the following preset models:
kappa1: Model vector includes (1, 2, 3, 4, 5, 6, 9) and
links
is set to "AB"kappa2: Model vector includes (1, 2, 3, 4, 5, 6, 7, 8) and
links
is set to "F"kappa3: Model vector includes (1, 2, 3, 4, 5, 6, 7, 8, 9) and
links
is set to the empty string
Value
An object of class braidrm
containing the following elements:
-
concs
: A width-two array of the concentration pairs fit by the model -
act
: A vector of responses fit by the model -
weights
: The vector of weights (the same length asact
) specifying the relative weight of each measurement -
coefficients
: A full length-9 named BRAID parameter vector representing the best fit BRAID surface for the data -
fitted.values
: A vector of responses (the same length ofact
) given by the best fit response surface as a function of the concentrations inconcs
-
residuals
: The fitting errors of the best fit model, equal to thefitted.values
subtracted fromact
scenario
: A character string specifying one of 32 distinct fitting scenarios determined from the parametersmodel
,links
, andstart
. Used in bootstrapping confidence intervals -
model
: The model vector (a subset of values between 1 and 9) specifying which BRAID parameters were varying freely in the fit -
start
: The length-9 starting BRAID parameter vector used in non-linear optimization -
direction
: Like the input parameter, a value of -1, 0, or 1 specifying the constraint on the directionality of the fitted surface -
pbounds
: A 2-by-k array of values specifying the lower and upper bounds of all varying parameters (where k is the number of free parameters). -
kweight
: A numeric value summarizing the relative Bayesian influence of the BRAID parameter kappa on optimized objective function.
Fit objects with bootstrapped confidence intervals include several additional
elements derived from that; see calcBraidBootstrap()
for details.
Examples
bfit1 <- braidrm(measure ~ concA + concB, additiveExample)
summary(bfit1)
bfit2 <- braidrm(measure ~ concA + concB, synergisticExample,
model = c(1,2,3,4,5,6,9),
lower = c(NA,NA,NA,NA,NA,0,0),
prior = "none",
getCIs = FALSE)
summary(bfit2)