There are several ways to specify the space of possible BRAID models
that a braidrm fitting function will consider when fitting
to a given set of data. Briefly, there are two ways to constrain this
space: by fixing parameters to be equal to a constant value to each
other (thus reducing the dimensionality of the space of BRAID
parameters), and by bounding the range of parameter values being
considered, which keeps the same dimensionality but reduces the size of
the available space. BRAID fitting functions provide options for
both.
The simplest method for controlling the dimensionality of parameters
is with the three, named, pre-defined models. Setting the
model parameter of a BRAID fitting function to one of
"kappa1", "kappa2" (the default), or
"kappa3" will select a BRAID model in which potency, Hill
slope, and interaction parameters are all allowed to vary freely, as
well as the value of the minimal effect \(E_0\). The difference between the three
named models is the space of possible maximal effect parameters:
"kappa1" specifies a model in which all three maximal
effect parameters are constrained to be equal to one another;
"kappa2" allows the individual maximal effect parameters
\(E_{f,A}\) and \(E_{f,B}\) to vary independently but
constrains the overall maximal effect parameter \(E_f\) to be equal to the “larger” of the
two; and "kappa3" allows all three to vary separately, thus
allowing for an overall maximal effect greater than the individual
maximal effects. We can see this in action with the
synergisticExample dataset:
surface <- synergisticExample
coef(braidrm(measure ~ concA + concB, surface, model="kappa1", getCIs=FALSE))
#> IDMA IDMB na nb kappa E0
#> 1.03954262 1.04805325 2.94534132 2.46109206 2.16620128 -0.03002773
#> EfA EfB Ef
#> 1.00570420 1.00570420 1.00570420coef(braidrm(measure ~ concA + concB, surface, model="kappa2", getCIs=FALSE))
#> IDMA IDMB na nb kappa E0
#> 1.03979196 1.02589884 2.91156457 2.49903773 2.12580099 -0.03002222
#> EfA EfB Ef
#> 1.00804226 0.98482987 1.00804226coef(braidrm(measure ~ concA + concB, surface, model="kappa3", getCIs=FALSE))
#> IDMA IDMB na nb kappa E0 EfA
#> 1.0398157 1.0259278 2.9115964 2.4991254 2.1258819 -0.0300150 1.0080412
#> EfB Ef
#> 0.9848315 1.0080412Note that while the third model allows the maximal effect parameter \(E_f\) to differ, in this case (and in many cases) the best fitting surface is still one in which \(E_f\) is equal to one of the individual maximal effects.
In some cases, the user may wish to consider models beyond the basic
three. The model parameter can therefore pick out
explicitly which parameters should be varied freely while fitting. If
model is a numeric vector containing a subset of the
indices 1 through 9, all indices that are included will be allowed to
vary during fitting, and those that are not included will be fixed. For
example:
startingParameter <- c(2,2,2,2,0,0,1,1,1)
bfit <- braidrm(measure ~ concA + concB, surface,
model=c(1,3,5,6,7,8), start=startingParameter,
getCIs=FALSE)
coef(bfit)
#> IDMA IDMB na nb kappa E0 EfA
#> 1.15495135 2.00000000 2.89447474 2.00000000 3.68261342 0.03724723 1.00290174
#> EfB Ef
#> 1.02997920 1.02997920
bfit <- braidrm(measure ~ concA + concB, surface,
model=c(1,2,5,6,9), start=startingParameter,
getCIs=FALSE)
coef(bfit)
#> IDMA IDMB na nb kappa E0
#> 0.99413424 1.03117464 2.00000000 2.00000000 2.25103927 -0.07513876
#> EfA EfB Ef
#> 1.02845985 1.02845985 1.02845985In the first example, parameters 2 and 4 (\({ID}_{M,B}\) and \(n_b\)) are absent from the model vector, so they are fixed at the value of the starting parameter. (When leaving any of the first six parameters fixed, it is always best to provide an explicit starting vector to ensure that the fixed values are sensible. BRAID fitting functions will try to automatically generate a starting vector, but such values are not guaranteed to be near what the user wants.) In the second example, it is parameters 3 and 4 (the two Hill slopes) which have been omitted, so they are held constant at the given starting value. Note however, that while parameter 9 (\(E_f\)) is absent from the first example, and parameters 7 and 8 (\(E_{f,A}\) and \(E_{f,B}\)) are absent from the second, they are not set equal to the values of the starting parameter. That is because the maximal effect parameters are handled differently from the other six.
While the first six BRAID parameters can either vary freely or be
fixed at a constant, the maximal effect parameters \(E_{f,A}\), \(E_{f,B}\) and \(E_f\) behave a little differently. This is
because there are many cases where it is less useful to fix them at a
constant value than it is to fix them equal to each other. For
example, while it is possible that one might want to fit a BRAID surface
where the individual maximal effect parameters \(E_{f,A}\) and \(E_{f,B}\) are fixed a constant 50% efficacy
but the overall maximal effect \(E_f\)
could be anything (and BRAID fitting functions can support
that), it is much more likely that one would want to fit a surface where
all three maximal effect parameters are held equal to one another. Both
circumstances involve \(E_f\) varying
freely, and the individual maximal effects being constrained, so how do
we distinguish between the two? This is done with the links
parameter.
links picks out several scenarios in which BRAID
parameters are not varying freely, but are held equal to each other in
one way or another. It is a character string with one of the following
values:
"AB": Both individual maximal effect parameters \(E_{f,A}\) and \(E_{f,B}\) are held equal to the maximal
effect parameter \(E_f\). Thus index 9
must be present in the model vector, and indices 7 and 8 must be
absent."A": \(E_{f,A}\) must
be equal to the overall maximal effect \(E_f\). Index 9 must be present in the model
vector and index 7 must be absent; if index 8 (\(E_{f,B}\)) is absent, it will be held at a
constant starting value."B": \(E_{f,B}\) must
be equal to the overall maximal effect \(E_f\). Index 9 must be present in the model
vector and index 8 must be absent; if index 7 (\(E_{f,A}\)) is absent, it will be held at a
constant starting value."F": The overall maximal effect parameter \(E_f\) is constrained to be equal to the
larger of the two individual maximal effect parameters. Index 9 must be
absent from the model vector, and one or both of 7 and 8 must be
present."" (the empty sting): There are no links between
parameters. Any parameter indices which are absent result in the
corresponding parameter being held constant at the starting value.Note that none of these value is marked as a default. That is
because, when left unspecified, links is chosen by the
BRAID fitting function based on the parameters included in
model. Models containing all or none of the maximal effect
parameters assume a links value of ""; models
containing one or both of 7 and 8 (\(E_{f,A}\) and \(E_{f,B}\)) but not 9 (\(E_f\)) assume a links value of
"F"; and models containing parameter 9 but neither of 7 or
8 assume a links value of "AB". It has been
our experience that these defaults are desired in the vast majority of
cases.
Even in cases where a parameter should be fit and determined from the
data, it is often desirable to place certain boundaries on the value of
that parameter. The user may wish to ensure that predicted drug effects
never drop below 0, or that the dose of median effect of a drug is held
to a known range of values. This is accomplished using the
lower and upper parameters. If included, these
numeric parameters contain a vector of values specifying the lowest or
highest a given parameter may go. They can be full length-9, or the same
length as the relevant model vector, in which case they will be mapped
to the correct freely varying parameter in the model. For example:
bfit <- braidrm(measure ~ concA + concB, surface,
model=c(1:5,6,7,8), start=startingParameter,
upper = c(0.75,0.75,NA,NA,NA,NA,0.7,NA,NA),
getCIs=FALSE)
coef(bfit)
#> IDMA IDMB na nb kappa E0
#> 0.75000000 0.75000000 4.31656699 2.06846665 1.28667298 -0.07142398
#> EfA EfB Ef
#> 0.70000000 1.00565462 1.00565462
bfit <- braidrm(measure ~ concA + concB, surface,
model=c(1:5,6,9), start=startingParameter,
lower = c(NA,NA,3,3,NA,0,0),
getCIs=FALSE)
coef(bfit)
#> IDMA IDMB na nb kappa E0 EfA EfB
#> 1.0495307 1.0756685 3.0153978 3.0000000 2.1204270 0.0000000 0.9994638 0.9994638
#> Ef
#> 0.9994638In the first example, upper is a length 9 vector,
specifying that parameters 1 and 2 (\({ID}_{M,A}\) and \({ID}_{M,B}\)) cannot go higher than 0.75,
and that parameter 7 (\(E_{f,A}\))
cannot go higher than 0.7. In the second, lower is the same
length as model, so its values correspond to just those
indices. The third and fourth model parameters (which are 3 and 4, \(n_a\) and \(n_b\)) can go no lower than 3; whereas the
sixth and seventh model parameters (6 and 9, so \(E_0\) and \(E_f\)) can go no lower than 0. And indeed
the best fit vectors in both cases abide by these constraints.
The parameters that tend to be bounded most often are the minimal and
maximal effect parameters, as these are often real-world measurable
quantities with natural constraints on them. BRAID fitting functions
also offer one additional boundary to place on these parameters. The
direction parameter can specify that BRAID fitting
functions should only consider models that change in one particular
direction. Setting the parameter to \(1\) indicates that considered models should
always be increasing, so the maximal effect parameters must be
numerically greater than or equal to than the minimal effect parameter.
Setting direction to \(-1\) indicates the opposite, that the
maximal effect parameters considered must always be numerically less
than or equal to the minimal effect parameter. Setting
direction equal to 0 (the default) will consider surfaces
changing in either direction. This can be particularly important when
fitting a large number of related surfaces that you wish to compare, as
having surfaces that change effect in opposite directions can make
analysis much more complex.