braidrm {braidrm}R Documentation

BRAID Response Surface Fitting

Description

Fits a BRAID response surface model to data.

Usage

braidrm(
  formula,
  data,
  model = "kappa2",
  links = NULL,
  weights = NULL,
  start = NULL,
  direction = 0,
  lower = NULL,
  upper = NULL,
  prior = "moderate",
  getCIs = TRUE
)

## S3 method for class 'braidrm'
summary(object, ...)

## S3 method for class 'summary.braidrm'
print(x, ...)

## S3 method for class 'braidrm'
print(x, ...)

## S3 method for class 'formula'
braidrm(
  formula,
  data,
  model = "kappa2",
  links = NULL,
  weights = NULL,
  start = NULL,
  direction = 0,
  lower = NULL,
  upper = NULL,
  prior = "moderate",
  getCIs = TRUE
)

## Default S3 method:
braidrm(
  formula,
  data,
  model = "kappa2",
  links = NULL,
  weights = NULL,
  start = NULL,
  direction = 0,
  lower = NULL,
  upper = NULL,
  prior = "moderate",
  getCIs = TRUE
)

Arguments

formula

Either an object of class formula such as would be provided to a modeling function like stats::lm(), or a width-2 numeric array vector of concentration pairs (including 0 or Inf). A formula should specify a single output as a function of two inputs, eg. activity ~ conc1 + conc2.

data

If forumula is a symbolic formula, a data frame containing the specified values. If formula is a numeric array of concentrations, a numeric vector of response values, the same length as the number of rows of formula.

model, links

Parameters model and links are used to specify which variant of the BRAID model is fit to data. Model may be one of the following character strings: "kappa1", "kappa2", or "kappa3" (see Details), or a subset of the numbers 1 through 9 specifying which of the nine BRAID response surface parameters is allowed to vary when fitting. links allows the user to further specify constraints on the three BRAID maximal effect parameters (see Details for more). If model is one of the supported character strings, the parameter links will be ignored.

weights

A vector of weights (between 0 and 1) the same length as the data which determines the weight with which each measurement will impact the the sum of squared errors. Weights will be multiplied by errors before squaring. If NULL (the default) all weights will be set to 1. Can be a numeric vector, or the name of a column in data if formula is a symbolic formula

start

A BRAID parameter vector specifying the first guess where the non-linear optimization should begin. May be a length 7, 8, or 9 vector, though a full length vector is always preferable. If NULL (the default), it will be estimated from the data.

direction

Determines the possible directionality of the BRAID model. If 0 (the default) no additional constraints are placed on the parameters. If greater than 0, the fitting will require that the maximal effects are all greater than or equal to the minimal effect. If less than 0, the fitting will require that all maximal effect is less than or equal to the minimal effect.

lower

A numeric vector of lower bounds on the fitted parameter values. May be the same length as the number of fitted parameters, or a full, length-9 vector. Missing or unspecified lower bounds may be included as NA or Inf; if unspecified, lower bounds on the first five parameters (IDMA, IDMB, na, nb, and kappa) will be automatically estimated from the data. Bounds on the minimal and maximal effect parameters however (E0, EfA, EfB, and Ef) will be assumed to be infinite unless specified. A value of NULL, the default, will be treated as all lower parameter bounds being unspecified.

upper

A numeric vector of upper bounds on the fitted parameter values. Used in the same way as lower.

prior

A character string specifying the desired Bayesian prior term for kappa, or an object of class kappaPrior genererated by the function kappaPrior(). Allowed strings are "mild", "moderate" (the default), "high", or "none". If a string is given, the kappa prior object will be estimated from the data using an initial ten-parameter fit to approximate measurement noise.

getCIs

Should bootstrapped confidence intervals be estimated and added to the BRAID fit object. Default value is TRUE.

object

An object of class braidrm to be summarized

...

Further arguments passed to or from other methods.

x

An object of class braidrm or summary.braidrm to be printed

Details

One of the hairiest and most confusing aspects of fitting a combined response surface model is handling the relationships between maximal effects. Unlike a simple dose response model such as those fit in basicdrm in which all parameters can be treated as fairly independent, response surface models are often considered with constraints that cannot be expressed as simply one parameter being fixed a particular value. Many response surface models assume that the two drugs in combination (and the overall combination) share a single common maximal effect; others might assume that the maximal effects of the two drugs should differ but that the overall maximal effect must be equal to one of these; still others may wish to fit with no constraints on maximal effect at all beyond guaranteeing that they lie above a fixed minimal effect. All these approaches are valid, and creating a functional interface to support them all is a challenge. The parameters given here represent our best effort to balance ease-of-use with flexibility.

The primary interface for model selection and customization is the paired paramters model and links. For the first six parameters of the BRAID surface, model is the only relevant control, and operates much as it would in any fitting function. If a given parameter (say IDMB) is included in model (as index 2) then it will vary freely within the provided bounds to best fit the data. If it is not, the value will be fixed at the value given in start (or if start is NULL, estimated from the data), and will remain fixed at that value in the best fit surface.

Parameters EfA, EfB, and Ef (the maximal effect parameters) require slightly more care. Relationships between these values is represented by the links parameter, which can take on one of the following five values:

For example, if the maximal effects should be fit, but should be constrained to be all equal, then it is the parameter Ef that varies freely in the fitting; the fact that EfA and EfB are always equal to this value is represented by setting the links parameter to "AB". Contrast this with the (admittedly much less common) scenario in which the links parameter is set to the empty string "", representing no link between maximal effects. In this case the parameter Ef will indeed vary freely in the fitting, but EfA and EfB will instead always be held at the constant initial values in the starting parameter vector. On the other hand, if we were to assume that the two individual maximum effect parameters can vary independently, but that the overall maximal effect should be equal to the larger of the two, then indices 7 and 8 (representing EfA and EfB) would be included in model; index 9 (representing Ef) would be excluded, and the links parameter would be set to "F" indicating that Ef is tied to the larger of the two.

Note also that the default value for links is not the empty string, but instead NULL. By default the value of links will be guessed from the model vector, based on the scenarios that we have encountered most often. If model inclues Ef (index 9) but not EfA or EfB (indices 7 and 8), links is assumed to be "F"; if EfA and EfB are present but not Ef, links is set to "AB". In the vast majority of cases, you will not need to specify this parameter yourself. This is especially true when model is specified with one of the model strings, in which any provided value for links will be discarded and replaced witht the following preset models:

Value

An object of class braidrm containing the following elements:

Fit objects with bootstrapped confidence intervals include several additional elements derived from that; see calcBraidBootstrap() for details.

Examples

bfit1 <- braidrm(measure ~ concA + concB, additiveExample)
summary(bfit1)

bfit2 <- braidrm(measure ~ concA + concB, synergisticExample,
                 model = c(1,2,3,4,5,6,9),
                 lower = c(NA,NA,NA,NA,NA,0,0),
                 prior = "none",
                 getCIs = FALSE)
summary(bfit2)

[Package braidrm version 1.0.3 Index]