R: Plot response surface

plotResponseSurface {BIGL}

R Documentation

Plot response surface

Description

Plot the 3-dimensional response surface predicted by one of the null models. This plot allows for a visual comparison between the null model prediction and observed points. This function is mainly used as the workhorse of plot.ResponseSurface method.

Usage

plotResponseSurface(
  data,
  fitResult = NULL,
  transforms = fitResult$transforms,
  predSurface = NULL,
  null_model = c("loewe", "hsa", "bliss", "loewe2"),
  colorPalette = c("blue", "grey70", "red"),
  colorBy = "none",
  colorPoints = c("black", "sandybrown", "brown", "white"),
  breaks = c(-Inf, 0, Inf),
  radius = NULL,
  logScale = TRUE,
  colorfun = median,
  zTransform = function(x) x,
  add = FALSE,
  main = "",
  legend = TRUE,
  xat = "actual",
  yat = "actual",
  plotfun = NULL,
  ...
)

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.
`predSurface`	Vector of all predicted responses based on `expand.grid(uniqueDoses)`. If not supplied, it will be computed with `predictOffAxis` function.
`null_model`	If `predSurface` is not supplied, it is computed using one of the available null models, i.e. `"loewe"`, `"hsa"`, `"bliss"` and `"loewe2"`. See also `fitSurface`.
`colorPalette`	Vector of color names for surface
`colorBy`	This parameter determines values on which coloring is based for the 3-dimensional surface. If matrix or a data frame with `d1` and d2 columns is supplied, dose combinations from `colorBy` will be matched automatically to the appropriate dose combinations in `data`. Unmatched dose combinations will be set to 0. This is especially useful for plotting results for off-axis estimates only, e.g. off-axis Z-scores or maxR test statistics. If `colorBy = "colors"`, surface will be colored using colors in `colorPalette` argument.
`colorPoints`	Colors for off-axis and on-axis points. Character vector of length four with colors for 1) off-axis points; 2) on-axis points of the first drug (i.e. second drug is dosed at zero); 3) on-axis points of the second drug; 4) on-axis points where both drugs are dosed at zero.
`breaks`	Numeric vector with numerical breaks. To be used in conjunction with `colorPalette` argument.
`radius`	Radius of spheres. If missing, an educated guess based on number of digits in average effect will be made.
`logScale`	Draw doses on log-scale (setting zeroes to be finite constant)
`colorfun`	If replicates in `colorBy` variable are present, these will be aggregated using `colorfun` function. This can also be a custom function returning a scalar.
`zTransform`	Optional transformation function for z-axis. By default, identity function is used.
`add`	Add the predicted response surface to an existing plot. Will not draw any points, just the surface. Must be called after another call to `plotResponseSurface`.
`main`	Fixed non-moving title for the 3D plot
`legend`	Whether legend should be added
`xat`	x-axis ticks: "pretty", "actual" or a numeric vector
`yat`	y-axis ticks: "pretty", "actual" or a numeric vector
`plotfun`	If replicates for dose combinations in `data` are available, points can be aggregated using `plotfun` function. Typically, it will be `mean`, `median`, `min` or `max` but a custom-defined function returning a scalar from a vector is also possible.
`...`	Further arguments to format axis labels

Details

Title for the plot and legend are drawn as bitmaps and do not rotate with the rest of the plot. Since they are bitmaps, they do not scale properly, hence resizing window will result in unappealing visuals. For them to look properly, it suffices to set the appropriate RGL window size and rerun the plotting command.

Value

Plot is shown on a rgl device.

Examples

## Not run: 
  data <- subset(directAntivirals, experiment == 1)
  ## Data must contain d1, d2 and effect columns
  fitResult <- fitMarginals(data)
  data_mean <- aggregate(effect ~ d1 + d2, data = data[, c("d1", "d2", "effect")],
                         FUN = mean)

  ## Construct the surface from marginal fit estimates based on HSA
  ## model and color it by mean effect level
  plotResponseSurface(data, fitResult, null_model = "hsa",
                      colorBy = data_mean, breaks = 10^(c(0, 3, 4, 6)),
                      colorPalette = c("grey", "blue", "green"))

  ## Response surface based on Loewe additivity model and colored with
  ## rainbow colors. Legend will not be displayed in any case.
  plotResponseSurface(data, fitResult, null_model = "loewe",
                      colorBy = "colors", colorPalette = rainbow(6))

## End(Not run)

[Package BIGL version 1.6.6 Index]