makeBRAIDreport {braidReports}

Make a BRAID Report Page

Description

Produces a one page report depicting the results of a full BRAID analysis for a single combination.

Usage

makeBRAIDreport(brdAnalysis, compounds, iaelevs, macs, control = list())

Arguments

brdAnalysis

a list representing the results of a full BRAID analysis, produced by the braidrm function runBRAIDanalysis

compounds

A two element character vector containing the names of the two compounds tested. Should be the same string repeated if combinaion is self-vs.-self

iaelevs

one or two effect levels at which the IAE and potentiation will be estimated

macs

the maximum achievable concentrations for the two compounds tested for the calculation of the IAE. If one concentration is provided, it will be used for both compounds. If combination is self-vs.-self the two concentrations must be equal.

control

A list of optional control parameters adjusting the appearance of the report see Details for a full description

Details

This is, by design, a rather massive function that attempts, however foolhardily, to consolidate all the pieces necessary to produce a comprehensive visualization and report on the results of a BRAID analysis. By default, it produces a one page report containing four rows of three panels. The first row contains a plot of the measured data passed to the BRAID fit, plotted without interpolation; a table of the best fit BRAID parameters, with confidence intervals; and tables of one or more IAE values (with confidence intervals), as determined by the given maximum achievable concentrations and either a purely additive surface or the best fit BRAID surface. The second row contains the measured data plotted with interpolation to convey the shape of the measured response surface; a plot of the predicted response surface assuming the measured dose-response behavior and BRAID additivity; and a plot of the best fit BRAID response surface. The third row contains a uninterpolated plot of the error resulting from simple smoothing (to provide a reasonable upper bound on quality of fit); a plot of the error resulting from a predicted additive surface (with R-squared value); and a plot of the error resulting from the best fit BRAID surface (with R-squared value). The fourth and final row shows potentiation in the best fit surface, containing tables of EC values for a specified threshold for each drug in the presence of various levels of the other; a potentiation plot of the first drug potentiated by the second; and the corresponding plot with the two drugs reversed. The theme settings and sizes are intended for use on a portrait-oriented 8.5 by 11 inch page.

Many details of the plots and report are adjusted by the control parameter, which may contain any or all of the following elements:

plot

a boolean determining whether the function arranges the constructed plots and tables and prints them to the existing graphics device. Doing so requires the package gridExtra (version 2.0.0 or greater); if this package is not included, a warning will be printed and this parameter will be reset to FALSE. Default value is TRUE

return

a boolean determining whether the pieces generated for the report are returned as a result of the function. This option can be used if the user wishes to arrange the plot him or herself, rather than using the default layout approach. If TRUE, the function returns a list of fourteen objects; the nine ggplot plots described above, followed by the five tables assembled for the report. Note that the tables are returned as standard R arrays, not grid or graphics objects. Using this option with plot set to FALSE does not require the presence of gridExtra. Default value is FALSE

actlabel

a string or R expression to be used as the label of the modeled effect in all plots. Default value is "Effect"

abbs

in axis labels and tables, the two drugs being combined are represented by abbreviations. By default these abbreviations consist of the first three characters of each compound name, with non alphanumeric characters removed. However, the user may wish to use custom abbreviations (e.g. "TMZ" for "temozolomide"); they may do so by specifying two abbreviations as two strings in this optional parameter.

levtext

an optional character vector the same length as iaelevs, determining how the corresponding levels will be displayed in tables. For example, if the modelled effect were proportional cell survival, the user might want to specify a label of "90" for a modelled effect of 0.1.

irreg

a boolean variable, passed to responseMap, reflecting whether the dose pairs being plotted lie on a regularly spaced grid. Default value is FALSE

clog

a boolean variable, reflecting whether the concentration variables are plotted on a logarithmic scale. This affects both the x- and y-axes in the seven surface plots, and the x-axis in the TWO potentiation plots. Default value is TRUE

zlog

a boolean variable, reflecting whether the modeled effect is plotted on a logarithmic scale. This affects only the y-axis in the two potentiaton plots. Default value is FALSE

xtrans

an optional function mapping the concentration of the first 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 concentration of the second drug to the transformed value that the user wishes to plot

xunit

a string or R expression (e.g. expression(mu*M)) specifying how the units of the first drug should be displayed in axis labels and tables. If not specified, units will be omitted.

yunit

a string or R expression (e.g. expression(mu*M)) specifying how the units of the second drug should be displayed in axis labels and tables. If not specified, units will be omitted.

ztrans

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 'ztrans' might be function(z) 10^z.

palette

a vector of two or more strings representing R colors, which will be passed to the ggplot2 function scale_fill_gradientn to specify the colormap for the plotted response surfaces. If left unspecified, a modified version of the classic "jet" colorscale (with dark green substituted for dark blue) will be used. Alternatively, if the user sets this parameter to the string "gjet" or "revgjet", the plots will use the modified "jet" colormap or its reverse.

ptsize

an optional size parameter passed to geom_point to control the size of plotted points

lnsize

an optional size parameter passed to geom_line to control the size of plotted lines.

Value

If the control parameter return is set TRUE, a list of ggplot2 plots and tables as described in the Description section above. If return is set to FALSE or omitted, the function returns NULL.

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

runBRAIDanalysis, responseMap, potentiationPlot

Examples

data(es8analysis)
pcont<-list(xtrans=function(x) x*10^6,ytrans=function(y) y*10^6,ztrans=function(z) 10^z,
			xunit=expression(mu*M),yunit=expression(mu*M),zlog=TRUE,abbs=c("Ola","TMZ"),
			levtext=c("90","99"),palette="revgjet",plot=FALSE,return=TRUE)
brep <- makeBRAIDreport(es8analysis,c("Olaparib","Temozolomide"),
			c(-1,-2),c(10^-6,5*10^-5),pcont)
brep[[1]]
brep[[10]]