Run and Report BRAID Analyses

Introduction

This vignette gives a basic rundown of the two centerpiece functions of the braidReports package, runBraidAnalysis() and makeBraidReport(). Of course, the term “centerpiece” here is a bit misleading, given that in a sense these are also the two most superfluous functions in the BRAID package suite. In reality, they’re nothing more than convenient wrappers for a large set of functionalities that users can, and in many cases should, delve into themselves, as doing so will allow them more freedom, more flexibility, and more control. But the tasks performed by these functions are so commonly required, and so convenient to package, that we felt that it was necessary to build them.

The first and simpler of these two functions is runBraidAnalysis(). Taking the same parameter set as findBestBraid() from braidrm, it uses that function to perform a BRAID fit (with model selection) of the given data. It also performs individual Hill dose-response fits of both included drugs by fitting the data points where the partner drug has a concnetration of zero. This results in a braidAnalysis object, containing a BRAID fit of class bradirm, and up to two Hill dose response fits describing the dose response behavior of each individual drug. (If either drug was not measured in isolation for any of the provided data points, the corresponding Hill fit will be omitted.) The braidAnalysis object can then be passed to makeBraidReport() to visualize the completed analysis.

surface <- synergisticExample
synergisticAnalysis <- runBraidAnalysis(measure ~ concA + concB,
                                        surface,
                                        defaults = c(0,2))

names(synergisticAnalysis)
#> [1] "concs"    "act"      "weights"  "braidFit" "hillFit1" "hillFit2" "call"

There may be cases in which the user would prefer not to use the results of findBestBraid() in their analysis, but still produce a report. It is therefore possible to pass any BRAID fit object of class bradirm to the makeBraidReport() function using the basicBraidAnalysis() function, which simply wraps its input into a braidAnalysis object.

otherSurface <- antagonisticExample
antagonisticFit <- braidrm(measure ~ concA + concB,
                           otherSurface, model="kappa2")
antagonisticAnalysis <- basicBraidAnalysis(antagonisticFit)

names(antagonisticAnalysis)
#> [1] "concs"    "act"      "weights"  "braidFit" "hillFit1" "hillFit2"

BRAID Report Pages

The makeBraidReport() function takes a fully analyzed combination surface (respresented by a braidAnalysis object) and produces a one page report with a range of plots and tables summarizing many aspects of the analysis. These reports are assembled into a single grid, designed for a standard 8.5 by 11 page, using the cowplot package. The report includes response surface plots of the raw and fitted data, tables summarizing the best-fit parameters and metrics, as well as other plots such as potentiation plots and additive comparison plots if desired. Here is the default appearance:

report <- makeBraidReport(synergisticAnalysis,c("A Drug","B Drug"),
                          c(0.5,0.9),c(5,5))
print(report)

The control parameter of the function allows the user to specify a long list of customizations that alter the appearance of the final report. This includes the abbreviations of drugs used in plots and charts, drug units, color scales, and more.

syncontrol <- 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(synergisticAnalysis,c("A Drug","B Drug"),
                          c(0.5,0.9),c(5,5),control=syncontrol)
print(nextReport)

The control parameter can also be used to change the overall layout of the report page (options are “simple”, “standard”, and “dense”), and add additional combination metrics to the included tables:

concs <- cbind(otherSurface$concA,otherSurface$concB)
act <- otherSurface$measure

otherSurface$bliss <- deviationSurface(concs,act,"Bliss",range=c(0,1))
otherSurface$zip <- deviationSurface(concs,act,"ZIP",range=c(0,1))
comboRows <- otherSurface$concA>0 & otherSurface$concB>0

ufit <- fitUrsaModel(measure ~ concA + concB, otherSurface)

metrics <- character()
metrics[["V[Bliss]"]] <- signif(mean(otherSurface$bliss[comboRows]),3)
metrics[["ZIP~delta"]] <- signif(mean(otherSurface$zip[comboRows]),3)
metrics[["URSA~alpha"]] <- signif(coef(ufit)[["alpha"]],3)

finalReport <- makeBraidReport(antagonisticAnalysis,
                               compounds=c("First Drug","Second Drug"),
                               levels = c(0.5,0.9), limits=c(8,8),
                               control=list(metrics=metrics,layout="simple"))
print(finalReport)

Note that the names of metrics are parsed into more formatted expressions using the base parse() function; this allows the use of subscripts and certain symbols, but necessitates using the tilde (~) to include spaces.

See the documentation of makeBraidReport() for a more complete listing of the possible customization options.