This function computes predictions for off-axis dose combinations according
to the BIGL or HSA null model and, if required, computes appropriate meanR
and maxR statistics. Function requires as input dose-response dataframe and
output of fitMarginals containing estimates for the monotherapy
model. If transformation functions were used in monotherapy estimation, these
should also be provided.
fitSurface(
data,
fitResult,
transforms = fitResult$transforms,
null_model = c("loewe", "hsa", "bliss", "loewe2"),
effect = "effect",
d1 = "d1",
d2 = "d2",
statistic = c("none", "meanR", "maxR", "both"),
CP = NULL,
B.CP = 50,
B.B = NULL,
nested_bootstrap = FALSE,
error = 4,
sampling_errors = NULL,
wild_bootstrap = FALSE,
wild_bootType = "normal",
control = "FWER",
cutoff = 0.95,
parallel = FALSE,
progressBar = TRUE,
method = c("equal", "model", "unequal"),
confInt = TRUE,
digits = 9,
bootRS = TRUE,
trans = "identity",
rescaleResids = FALSE,
invtrans = switch(trans, identity = "identity", log = "exp"),
newtonRaphson = FALSE,
asymptotes = 2,
bootmethod = method
)This function returns a ResponseSurface object with estimates
of the predicted surface. ResponseSurface object is essentially a
list with appropriately named elements.
Elements of the list include input data, monotherapy model coefficients and transformation functions, null model used to construct the surface as well as estimated CP matrix, occupancy level at each dose combination according to the generalized Loewe model and
"offAxisTable" element which contains observed and predicted effects
as well as estimated z-scores for each dose combination.
If statistical testing was done, returned object contains "meanR"
and "maxR" elements with output from meanR and
maxR respectively.
Dose-response dataframe.
Monotherapy (on-axis) model fit, e.g. produced by
fitMarginals. It has to be a "MarginalFit" object or a
list containing df, sigma, coef,
shared_asymptote and method elements for, respectively,
marginal model degrees of freedom, residual standard deviation, named
vector of coefficient estimates, logical value of whether shared asymptote
is imposed and method for estimating marginal models during bootstrapping
(see fitMarginals). If biological and power transformations
were used in marginal model estimation, fitResult should contain
transforms elements with these transformations. Alternatively, these
can also be specified via transforms argument.
Transformation functions. If non-null, transforms is
a list containing 5 elements, namely biological and power transformations
along with their inverse functions and compositeArgs which is a list
with argument values shared across the 4 functions. See vignette for more
information.
Specified null model for the expected response surface.
Currently, allowed options are "loewe" for generalized Loewe model,
"hsa" for Highest Single Agent model, "bliss" for Bliss additivity,
and "loewe2" for the alternative Loewe generalization.
Name of the response column in the data ("effect")
Name of the column with doses of the first compound ("d1")
Name of the column with doses of the second compound ("d2")
Which statistics should be computed. This argument can take
one of the values from c("none", "meanR", "maxR", "both").
Prediction covariance matrix. If not specified, it will be estimated
by bootstrap using B.CP iterations.
Number of bootstrap iterations to use for CP matrix estimation
Number of iterations to use in bootstrapping null distribution for either meanR or maxR statistics.
When statistics are calculated, if
nested_bootstrap = TRUE, CP matrix is recalculated at each
bootstrap iteration of B.B using B.CP iterations. Using such
nested bootstrap may however significantly increase computational time. If
nested_bootstrap = FALSE, CP bootstrapped data reuses
CP matrix calculated from the original data.
Type of error for resampling in the bootstrapping procedure.
This argument will be passed to generateData. If error
= 4 (default), the error terms for generating distribution of the null
will be resampled from the vector specified in sampling_errors. If
error = 1, normal errors are added. If error = 2, errors are
sampled from a mixture of two normal distributions. If error = 3,
errors are generated from a rescaled chi-square distribution.
Sampling vector to resample errors from. Used only if
error is 4 and is passed as argument to generateData.
If sampling_errors = NULL (default), mean residuals at off-axis
points between observed and predicted response are taken.
Whether special bootstrap to correct for
heteroskedasticity should be used. If wild_bootstrap = TRUE, errors
are generated from sampling_errors multiplied by a random variable
following Rademacher distribution. Argument is used only if error = 4.
Type of distribution to be used for wild bootstrap. If wild_bootstrap = TRUE,
errors are generated from "rademacher", "gamma", "normal" or "two-point" distribution.
If control = "FCR" then algorithm controls false coverage rate, if control = "dFCR" then
algorithm controls directional false coverage rate, if control = "FWER" then
algorithm controls family wise error rate
Cut-off to use in maxR procedure for declaring non-additivity (default is 0.95).
Whether parallel computing should be used for bootstrap. This
parameter can take either integer value to specify the number of threads to
be used or logical TRUE/FALSE. If parallel = TRUE, then
max(1, detectCores()-1) is set to be the number of threads. If
parallel = FALSE, then a single thread is used and cluster object
is not created.
A boolean, should progress of bootstraps be shown?
What assumption should be used for the variance of on- and
off-axis points. This argument can take one of the values from
c("equal", "model", "unequal"). With the value "equal" as the
default. "equal" assumes that both on- and off-axis points have the
same variance, "unequal" estimates a different parameter for on- and
off-axis points and "model" predicts variance based on the average
effect of an off-axis point. If no transformations are used the
"model" method is recommended. If transformations are used, only the
"equal" method can be chosen.
a boolean, should confidence intervals be returned?
Numeric value indicating the number of digits used for numeric values in confidence intervals
a boolean, should bootstrapped response surfaces be used in the calculation of the confidence intervals?
the transformation function for the variance and its inverse, possibly as strings
a boolean indicating whether to rescale residuals, or else normality of the residuals is assumed.
A boolean, should Newton-Raphson be used to find Loewe response surfaces? May be faster but also less stable to switch on
Number of asymptotes. It can be either 1
as in standard Loewe model or 2 as in generalized Loewe model.
The resampling method to be used in the bootstraps. Defaults to the same as method
Please see the example vignette vignette("analysis", package = "BIGL")
and the report "Lack of fit test for detecting synergy" included in the
papers folder for further details on the test statistics used:
system.file("papers", "newStatistics.pdf", package = "BIGL")
if (FALSE) {
data <- subset(directAntivirals, experiment == 4)
## Data should contain d1, d2 and effect columns
transforms <- list("PowerT" = function(x, args) with(args, log(x)),
"InvPowerT" = function(y, args) with(args, exp(y)),
"BiolT" = function(x, args) with(args, N0 * exp(x * time.hours)),
"InvBiolT" = function(y, args) with(args, 1/time.hours * log(y/N0)),
"compositeArgs" = list(N0 = 1, time.hours = 72))
fitResult <- fitMarginals(data, transforms)
surf <- fitSurface(data, fitResult, statistic = "meanR")
summary(surf)
}
Run the code above in your browser using DataLab