BIGL (version 1.5.3)

maxR: Compute maxR statistic for each off-axis dose combination

Description

maxR computes maxR statistics for each off-axis dose combination given the data provided. It provides a summary with results indicating whether a given point is estimated to be synergetic or antagonistic. These can be based either on normal approximation or a fully bootstrapped distribution of the statistics.

Usage

maxR(
  data,
  fitResult,
  transforms = fitResult$transforms,
  null_model = c("loewe", "hsa", "bliss", "loewe2"),
  Ymean,
  CP,
  reps,
  nested_bootstrap = FALSE,
  B.B = NULL,
  B.CP = NULL,
  cutoff = 0.95,
  cl = NULL,
  method = c("equal", "model", "unequal"),
  ...
)

Arguments

data

Dose-response dataframe.

fitResult

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.

transforms

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.

null_model

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.

Ymean

Aggregate summary of off-axis predicted responses. In particular, it should contain "effect - predicted" column. If Ymean is missing, it will be calculated automatically from output of predictOffAxis function.

CP

Prediction covariance matrix. If not specified, it will be estimated by bootstrap using B.CP iterations.

reps

Numeric vector containing number of replicates for each off-axis dose combination. If missing, it will be calculated automatically from output of predictOffAxis function.

nested_bootstrap

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.

B.B

Number of iterations to use in bootstrapping null distribution for either meanR or maxR statistics.

B.CP

Number of bootstrap iterations to use for CP matrix estimation

cutoff

Cut-off to use in maxR procedure for declaring non-additivity (default is 0.95).

cl

If parallel computations are desired, cl should be a cluster object created by makeCluster. If parallel computing is active, progress reporting messages are not necessarily ordered as it should be expected.

method

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.

...

Further arguments that will be later passed to generateData function during bootstrapping

Value

This function returns a maxR object with estimates for the maxR statistical test. maxR object is essentially a list with appropriately named elements.

In particular, maxR object contains "Ymean" element which is a summary table of maxR test results for each dose combination. This table contains mean deviation from the predicted surface, normalized deviation ("absR") as well as a statistical call whether this deviation is significant. Distributional information on which these calls are made can be retrieved from the attributes of the "Ymean" dataframe.

Also, maxR object contains "Call" element which indicates the general direction of the deviation of the observed surface from the null. This call is based on the strongest local deviation in the "Ymean" table. 4 values are available here: "Syn", "Ant", "None", "Undefined". If one compound acts as an agonist while another one is an antagonist, then a deviation from the null is classified as "Undefined". If both compounds act in the same direction, then a stronger than individual effect is classified as synergy while a weaker effect would be classified as antagonism.

Examples

# NOT RUN {
  data <- subset(directAntivirals, experiment == 2)
  ## Data must contain d1, d2 and effect columns
  fitResult <- fitMarginals(data)
  CP <- CPBootstrap(data, fitResult, null_model = "loewe", B.CP = 5)
  maxR(data, fitResult, null_model = "loewe", CP = CP)
# }