fitSurface {BIGL}R Documentation

Fit response surface model and compute meanR and maxR statistics


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.


  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,
  cutoff = 0.95,
  parallel = FALSE,
  progressBar = TRUE,
  method = c("equal", "model", "unequal"),
  confInt = TRUE,
  bootRS = TRUE,
  trans = "identity",
  rescaleResids = FALSE,
  invtrans = switch(trans, identity = "identity", log = "exp"),
  newtonRaphson = FALSE,
  asymptotes = 2,
  bootmethod = method



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.


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?


a boolean, should bootstrapped response surfaces be used in the calculation of the confidence intervals?

trans, invtrans

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")


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.


## Not run: 
  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")

## End(Not run)

[Package BIGL version 1.6.6 Index]