BIGL (version 1.5.3)

fitMarginals: Fit two 4-parameter log-logistic functions for a synergy experiment

Description

This function uses dose-response data for two compounds and estimates coefficients for monotherapy models of both of these compounds such that they share a common baseline. Currently, these coefficients are estimated by default using a non-linear least squares approximation. Although entire dose-response data can be provided, estimation will subset the part of data where at least one of the compounds is dosed at zero, i.e. on-axis data.

Usage

fitMarginals(
  data,
  transforms = NULL,
  start = NULL,
  constraints = NULL,
  fixed = NULL,
  method = c("nlslm", "nls", "optim"),
  names = NULL,
  ...
)

Arguments

data

Dose-response dataframe. Marginal data will be extracted from it automatically.

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.

start

Starting parameter values. If not specified, they will be obtained from initialMarginal.

constraints

List of constraint matrix and vector which will be passed to constructFormula. If constraints = NULL, no constraints on parameter estimation will be imposed.

fixed

This arguments provides a user-friendly alternative to impose a fixed value for marginal parameters. It must be a named vector with names contained in c("h1", "h2", "b", "m1", "m2", "e1", "e2"). For example, fixed = c("m1" = 1, "h1" = 1) will automatically generate appropriate constraint matrix and vector to set the maximal response and the Hill coefficient of the first compound to 1. If both constraints and fixed arguments are passed, then only fixed will be used.

method

Which estimation method should be used to obtain the estimates. If method = "nls", simple non-linear least squares nls will be used. If method = "nlslm" Levenberg-Marquardt non-linear least squares nlsLM is used instead (default). If method = "optim", residual sum of squares will be minimized using general purpose optimization based on Nelder-Mean algorithm in optim. This method can be noticeably slower than the non-linear least squares methods.

names

Compound names to be used on the plot labels.

...

Further arguments that are passed to the optimizer function, such as lower or upper (for the "nlslm" method), or control.

Value

This function returns a MarginalFit object with monotherapy coefficient estimates and diverse information regarding monotherapy estimation. MarginalFit object is essentially a list with appropriately named elements.

Among these list elements, "coef" is a named vector with parameter estimates. h1 and h2 are Hill's slope coefficients for each of the compounds, m1 and m2 are their maximal response levels whereas b is the shared baseline. Lastly, e1 and e2 are log-transformed EC50 values.

"sigma" is standard deviation of residuals for the estimated monotherapy model and "df" is the degrees of freedom for the residuals. "vcov" is the variance-covariance matrix of the estimated parameters.

Return object also contains information regarding data, biological and power transformations used in this estimation as well as model construct and method of estimation.

Details

Model formula is specified as effect ~ fn(h1, h2, ...) where fn is a hard-coded function which fits two 4-parameter log-logistic functions simultaneously so that the baseline can be shared. If transformation functions are provided, fn is consequently adjusted to account for them.

Examples

# NOT RUN {
  data <- subset(directAntivirals, experiment == 1)
  ## Data must contain d1, d2 and effect columns
  transforms <- getTransformations(data)
  fitMarginals(data, transforms)
# }