potentiationPlot {braidReports}

Plot Potentiation in a BRAID Fitted Combination

Description

Generates a ggplot2 plot object depicting the potentiaton or curve-shift of one compound by the presence of another, based on BRAID surface fit generated by the 'braidrm' package.

Usage

potentiationPlot(bfit, levs, dnum = 1, concs = NULL, control = list())

Arguments

bfit

an object of class 'braidrm' representing a BRAID surface fit

levs

a vector of levels of the "potentiating" drug to be plotted

dnum

index of the drug to be plotted on the x-axis (the "potentiated" drug). Default value 1

concs

an optional parameter specifying the concentrations of the "potentiated" drug to be plotted. If NULL (the default), a length-100 vector of evenly spaced concentrations will be plotted covering the range of concentrations in all combinations in which both drugs are non-zero.

control

A list of optional control parameters adjusting the appearance of the plot. See Details for a full description

Details

This function is less basic than the response mapping function responseMap, and is intended as a convenience for those who wish to visualize potentiation in a BRAID-fit surface. Many details of the plot are adjusted by the control parameter, which may contain any or all of the following elements:

xlog

a boolean variable reflecting whether the concentration plotted on the x-axis (the "potentiated" drug) should be plotted on a logarithmic scale. Default value is TRUE

ylog

a boolean variable reflecting whether the concentration plotted on the x-axis (the modelled effect) should be plotted on a logarithmic scale. Default value is FALSE

addscales

a boolean that controls whether logarithmic scales will be explicitly added to the resulting plot. ggplot2 prefers that only one scale be added to a given aesthetic, and throws a warning otherwise, so those who wish to plot the x- or y-variables logarithmically, but wish to add their own ggplot2 scales (to control axis limits, labels, etc.) should set this parameter to FALSE. Default value is TRUE

xtrans

an optional function mapping the concentration of the potentiated drug to the transformed value that the user wishes to plot. A simple example would be one in which the fit was performed on concentrations expressed in molar, but the user wishes to plot the concentrations in micromolar, in which case the value of 'xtrans' might be function(x) x*10^6.

ytrans

an optional function mapping the modelled effect to the transformed value that the user wishes to plot. An example might be a case in which the modelled effect variable is a logarithmic transform of a real-world measurement, and the user wishes to plot the measured value, in which case the value of 'ytrans' might be function(y) 10^y.

thresh

an optional value (or vector of values) of the modeled effect that will be plotted as a dotted horizontal line. Used to visualize where the shifted dose-response curves cross a desired threshold or thresholds. Note that if ytrans is specified, the values in thresh should be desired thresholds prior to transformation.

ciplot

a boolean variable reflecting whether 95% confidence intervals will be plotted around the potentiated DR curves. If the 'braidrm' object bfit does not possess valid confidence intervals, then this parameter automatically is set to FALSE; if it has been explicitly set to TRUE, a warning will be printed indicating that confidence intervals cannot be plotted. Default value is TRUE

cialpha

a boolean variable controlling how the confidence intervals are plotted. By default, confidence intervals are plotted as filled ribbons (using geom_ribbon) with an alpha (opacity) value of 0.3. This allows the confidence ranges to overlap, and use the same color scale as the plotted curves while remaining visually distinguishable. Unfortunately, some graphics outputs (including EPS) do not support transparency. Setting this parameter to FALSE will plot the confidence intervals with full opacity; the user may distinguish them from the DR curves by using a different color scale for the 'colour' and 'fill' aesthetics. Default value is TRUE

pts

a boolean variable determining whether points are plotted along the potentiated DR curves. If true, each DR curve will have points plotted at all unique concentrations of the potentiated drug (in the plotted range) which appeared in any combination in the fitted data in which both drugs had non-zero concentrations. Note, however, that this does not plot actual measured effect, as there no guarantee that the levels of the potentating drug which are plotted were tested in the original experiment. Plotting these points simply offers a way to visualize which concentrations of the potentiated drug were actually measured experimentally. Default value is FALSE

ptsize

an optional size parameter passed to geom_point to control the size of plotted points. If pts is omitted or set to FALSE this parameter is ignored.

pconcs

if desired, the user may set this control parameter to explicitly determine which concentrations of the potentiated drug will be plotted as points. This is used in makeBRAIDreport when concentration corrections have altered the concentrations fed into the BRAID fitting model.

lnsize

an optional size parameter passed to geom_line and, if thresh is included, geom_hline to control the size of plotted lines.

Though this function is intended to much of the heavy lifting in plotting potentiation (especially as applied to confidence intervals), many choices are left to the user. Axis labels are not applied, and scales are not applied to the 'colour' or 'fill' aesthetics. Users may also, of use any ggplot2 theme functions to further adjust the appearance of the plot.

Value

A ggplot2 plot object, depicting the dose-response curves of the potentiated drug in the presence of various levels of the potentiating drug.

Author(s)

Nathaniel R. Twarog

References

Twarog, N.R., Stewart, E., Vowell Hamill, C., and Shelat, A. BRAID: A Unifying Paradigm for the Analysis of Combined Drug Action. Scientific Reports In Press (2016).

See Also

makeBRAIDreport

Examples

data(es8analysis)
bfit <- es8analysis$braidFit
pcont <- list(xtrans=function(x) x*10^6,ytrans=function(y) 10^y,ylog=TRUE,thresh=-1)
potentiationPlot(bfit,c(0,10^-6,10^-5,10^-4),control=pcont)