makeBraidReport: Render a BRAID Report

In braidReports: Visualize Combined Action Response Surfaces and Report BRAID Analyses

Render a BRAID Report

Description

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

Usage

makeBraidReport(analysis, compounds, levels, limits, control = list())

Arguments

analysis	An object of class braidAnalysis produced by the runBraidAnalysis() or basicBraidAnalysis() functions
compounds	A length-2 character vector containing the names of the two compounds tested in the combination
levels	Two levels at which the IAE should be evaluated
limits	Two values representing the maximal achievable concentrations for the compounds tested, used to esitmate the IAE
control	A named list of additional control parameters adjusting the appearance of the resulting report

Details

This function attempts, however foolhardily, to encompass many of the details, plots, and values that the user might wish to report for a complete BRAID analysis of a given drug combination. All reports are built for a single 8.5-by-11 inch page, either in landscape or potrait orientation, but reports can be customized to contain more or less information. Here is a full list of what can appear in the BRAID report:

• A raw and smoothed plot of the actual measured response data; the raw plot is built using geom_braid() or, for irregularly laid out data, geom_braid_glass(), while the smoothed data is built using geom_braid_smooth(). (Included in all layouts)

• A plot of residual errors and a smoothed surface plot of the predicted additive surface based on the dose response behavior of the individual compounds alone. In cases of pronounced interaction, this will differ significantly from the best-fit BRAID plots. (Included in the dense layout)

• A plot of residual errors and a smoothed surface plot of the best-fitting BRAID surface. (Included in the all layouts)

• A table of the best-fitting BRAID response surface parameters (Included in all layouts)

• A table of estimated IAE values at the specified effect levels (Included in all layouts)

• Two tables of the dose required of one drug to produce a desired effect level (the first value in levels) in the presence of several doses of the other drug; used to gauge the degree of potentiation. (Included in the standard and dense layouts)

• Two plots depicting the predicted dose response of one drug in the presence of various levels of the other, also used to gauge potentiation. (Included in the standard and dense layouts)

So the resulting report page can contain from six (simple layout) to twelve (dense layout) elements depicting different aspects of the BRAID analysis.

The precise appearance of the report page is controlled by various elements of the control parameter. Though the default value of the parameter is an empty list, several fields will be filled in if they are unspecified. The full set of possible control options is:

• abbs: A pair of character strings specifying the abbreviations of the tested compounds. By default, the abbreviations consist of the firs three characters of each compound's name, but for some compound names this is not an appropriate abbreviation Abbreviations are used in many axis labels and tables

• units: If included, a single string or pair of strings specifying the dose units for the two drugs tested, included in axis labels and tables. If left unspecified, units will not be included

• xscale: Either a character string specifying a named transformation object (e.g "log2", "log10", "sqrt") or a ggplot2 continuous x-position scale generated by ggplot2::scale_x_continuous() or related functions. This scale will be applied to the x-dimension of all surface plots and the x-dimension of the first potentiation plot. If a name is specified for the scale, this will be the x-axis label; otherwise other defaults will be used. Default value for this control parameter is "log10".

• yscale: Either a character string specifying a named transformation object (e.g "log2", "log10", "sqrt") or a ggplot2 continuous y-position scale generated by ggplot2::scale_y_continuous() or related functions. This scale will be applied to the y-dimension of all surface plots and the x-dimension of the second potentiation plot. If a name is specified for the scale, this will be the y-axis label; otherwise other defaults will be used. Default value for this control parameter is "log10".

• fillscale: If included, continuous fill scale object generated by one of several ggplot2 continuous fill scale functions. This fill scale will control the fill appearance for all effect surface plots; fill colors in residual error plots will use a different color palette. In addition, any names, labels, breaks, transformations, etc. included in this scale will also be applied to the y-axis of both potentiation plots, as those also represent the modeled effect. If unspecified, will be set to a brewer continuous color scale with palette "RdYlBu".

• colorscale: If included, a discrete color scale object generated by one of several ggplot2 discrete color scale functions. This color scale controls the colors chosen for the curves in the two potentiation plots. If left unspecified, will default to the output of ggplot2::scale_color_discrete()

• xname: A string specifying the desired x-axis labels in surface plots. Will be overridden if control parameter xscale is a scale object with a non-empty name attribute. If unspecified, defaults the abbreviation of the first compound followed by the units if included.

• yname: A string specifying the desired y-axis labels in surface plots. Will be overridden if control parameter yscale is a scale object with a non-empty name attribute. If unspecified, defaults the abbreviation of the second compound followed by the units if included.

• effectname: The name of the modeled effect variable. Could be "Growth" or "Survival" or "Activity". The default value is simply "Effect"

• title: A string containing the overall title of the report page. If left unspecified, will simply be the first compound "vs." the second

• contourcolor: Contours of the smoothed surfaces at the levels specified by the parameter levels are included in all smoothed plots. By default, they are black, but specifying this control parameter will change that color

• irregular: If TRUE, the data are not assumed to lie on a regular grid in the plotted, and will be visualized with geom_braid_glass() rather than geom_braid()

• swidth: A numeric value specifying how widely the smooth surfaces should be smoothed, passed as the width aesthetic to geom_braid_smooth()

• sheight: A numeric value specifying how far in the y-direction the smooth surfaces should be smoothed, passed as the height aesthetic to geom_braid_smooth()

• npoints: The density of points used in the smoothed plots. See geom_braid_smooth() for details

• leveltext: A pair of strings indicating how the two IAE levels should be displayed in tables. In some cases, the precise number at which the IAE is calculated does not reflect the level that the user wishes to express. So a user might want to refer to a relative survival value of 0.1 as IAE90 (for 90% killing); or a log2-fold growth inhibition as IAE50 (for 50% inhibition); passing "50" or "90" as the leveltext in such cases will produce the desired appearance. If left unspecified, labels will simply be the string representations of the paramter levels

• metrics: A named numeric or named character vector specifying additional metrics for the combination; they will be added to the table containing the calculated IAE values. Numeric values will be rounded to three significant figures; string values will be included as is. Names will be parsed by default, so the string "CI[90]" will be displayed with the "90" as a subscript

• surftheme: A ggplot2 theme object specifying any additional theme adjustments to add to all response surface plots

• curvetheme: A ggplot2 theme object specifying any additional theme adjustments to add to both potentiation curve plots

• layout: The specific layout to be used; determines which report elements are included. Can be "simple", "standard" (the default), or "dense"

• orientation: The expected orientantion of the rendered page; can be "portrait" (the default) or "landscape"

Value

A graphical object containing all plots and tables, arranged according to the desired format. The resulting object is optimized for a single page, either portrait or landscape as specified in control

Examples

surface <- synergisticExample
analysis <- runBraidAnalysis(measure~concA+concB, surface,
                             defaults=c(0,1), getCIs=FALSE)

report <- makeBraidReport(analysis,c("A Drug","B Drug"),
                          levels=c(0.5, 0.9),limits=c(5,5))
print(report)

control <- list(abbs=c("A","B"),units=c("\u00B5M"),leveltext=c("50","90"),
                xscale=scale_x_log10(breaks=c(0.1,0.5,2,10),
                labels=as.character),
                fillscale=scale_fill_viridis_c(option="A"),
                colorscale=scale_color_brewer(palette="Set1"),
                title="Example Analysis")
nextReport <- makeBraidReport(analysis,c("A Drug","B Drug"),
                              levels=c(0.5, 0.9),limits=c(5,5),
                              control=control)
print(nextReport)

braidReports documentation built on Sept. 30, 2024, 1:06 a.m.