braidReports: Visualize Combined Action Response Surfaces and Report BRAID Analyses

Description

Provides functions to visualize combined action data in 'ggplot2'. Also provides functions for producing full BRAID analysis reports with custom layouts and aesthetics, using the BRAID method originally described in Twarog et al. (2016) doi:10.1038/srep25523.

Author(s)

Maintainer: Nathaniel R. Twarog nathaniel.twarog@stjude.org

Authors:

• Anang Shelat anang.shelat@stjude.org

Base ggproto classes for braidReports

Description

Base ggproto classes for braidReports

Usage

StatBraid

StatBraidGlass

StatBraidSmooth

StatBraidContour

Format

An object of class StatBraid (inherits from Stat, ggproto, gg) of length 6.

An object of class StatBraidGlass (inherits from StatBraid, Stat, ggproto, gg) of length 3.

An object of class StatBraidSmooth (inherits from StatBraid, Stat, ggproto, gg) of length 2.

An object of class StatBraidContour (inherits from StatContour, Stat, ggproto, gg) of length 5.

See Also

ggproto()

Basic BRAID Analysis Conversion

Description

Basic BRAID Analysis Conversion

Usage

basicBraidAnalysis(bfit)

Arguments

Details

While we strongly recommend using the runBraidAnalysis() function for a more complete treatment of a combination; there may be circumstances in which is necessary or preferable to use an existing BRAID fit object (of class braidrm). Thsi function takes such a fit and wraps it in a minimal braidAnalysis object which can then be passed to makeBraidReport()

Value

A BRAID analysis object of class braidanalysis containin only the results from the given BRAID fit

Examples

surface <- antagonisticExample
fit <- braidrm(measure ~ concA + concB, surface, model="kappa2")

analysis <- basicBraidAnalysis(fit)

names(analysis)

BRAID Heatmaps

Description

Summarize and plot measurements of two inputs as a discrete raster or "stained-glass" plot

Usage

geom_braid(
  mapping = NULL,
  data = NULL,
  stat = "braid",
  position = "identity",
  ...,
  space = 1.5,
  trim = TRUE,
  shared = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_braid(
  mapping = NULL,
  data = NULL,
  geom = "tile",
  position = "identity",
  ...,
  space = 1.5,
  trim = TRUE,
  shared = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

geom_braid_glass(
  mapping = NULL,
  data = NULL,
  stat = "braid_glass",
  position = "identity",
  ...,
  space = 1.5,
  trim = TRUE,
  shared = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_braid_glass(
  mapping = NULL,
  data = NULL,
  geom = "polygon",
  position = "identity",
  ...,
  space = 1.5,
  trim = TRUE,
  shared = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

While the existing ggplot2 package includes several functions that are extremely effective and versatile for visualizing two-dimensional responses, including ggplot2::geom_raster(), ggplot2::geom_tile(), and ggplot2::geom_contour(), a number of considerations particular to combination data make these functions, as is, somewhat difficult to use. First, these functions are not designed for data in which pairs of x- and y-coordinates are duplicated; yet this is very common in experimental data. While such duplications can be handled prior to calling a visualization function, handling them automatically reduces the barrier to plotting.

A second, and much more challenging consideration, is that for many drug combination studies, drug concentrations are measured as a series of equal ratio dilutions; visualizing such doses is most intuitive on a logarithmic scale. But when inputs are scaled logarithmically, zeros become infinite and are automatically removed by nearly all ggplot2 functions. This makes it very difficult to plot measurements of drugs in isolation and in combination in the same plot. geom_braid addresses this by automatically offsetting any measurements whose transformed coordinates are infinite to margins within the plotted space, so that all values can be plotted together.

While geom_braid is suitable for most response surfaces, some surfaces feature measurements that are not arranged in a evenly spaced checkerboard. For such surfaces, geom_braid_glass produces a set of Voronoi polygons centered on the available transformed coordinates, creating what we call a "stained glass" plot. Marginal points are still represented by rectangles, but with width and height such that boundaries are equidistant between adjacent points.

stat_braid and stat_braid_glass are simply the corresponding stat_ functions for these two functions.

Examples

concentrations <- c(0,2^(-3:3))
surface <- data.frame(
	  concA = rep(rep(concentrations,each=length(concentrations)),each=3),
  concB = rep(rep(concentrations,times=length(concentrations)),each=3),
  replicate = rep(c(1,2,3),times=(length(concentrations)^2))
)
surface$actual <- evalBraidModel(
  surface$concA,
 surface$concB,
 c(1, 1, 3, 3, 2, 0, 100, 100, 100)
)
surface$measure <- surface$actual + rnorm(nrow(surface),sd=7)

ggplot(surface,aes(x=concA,y=concB))+
    geom_braid(aes(fill=measure))+
    scale_x_log10()+
    scale_y_log10()+
    scale_fill_distiller(palette="RdYlBu")+
    coord_equal()+
    labs(x="Drug A",y="Drug B",fill="Effect")

glassSurface <- surface
glassSurface$concA[glassSurface$replicate==2] <-
    glassSurface$concA[glassSurface$replicate==2]*1.25
glassSurface$concB[glassSurface$replicate==3] <-
    glassSurface$concB[glassSurface$replicate==3]*1.25
glassSurface$actual <- evalBraidModel(
    glassSurface$concA,
    glassSurface$concB,
    c(1, 1, 3, 3, -0.5, 0, 60, 100, 100)
)
glassSurface$measure <- glassSurface$actual+rnorm(nrow(glassSurface),sd=7)

ggplot(glassSurface,aes(x=concA,y=concB))+
    geom_braid_glass(aes(fill=measure))+
    scale_x_log10("Drug A")+
    scale_y_log10("Drug B")+
    scale_fill_distiller("Effect",palette="RdYlBu")+
    coord_equal()

glassSurface$tilewidth <- log10(2)*0.9
glassSurface$tilewidth[glassSurface$concA==0] <- log10(2)/2

glassSurface$tileheight <- log10(2)*0.9
glassSurface$tileheight[glassSurface$concB==0] <- log10(2)/2

ggplot(glassSurface,aes(x=concA,y=concB))+
    geom_braid_glass(aes(fill=measure,width=tilewidth,height=tileheight),space=2)+
    scale_x_log10("Drug A")+
    scale_y_log10("Drug B")+
    scale_fill_distiller("Effect",palette="RdYlBu")+
    coord_equal()

Smoothed BRAID Surface Contours

Description

Generate contours of a smoothed two-dimensional response surface

Usage

geom_braid_contour(
  mapping = NULL,
  data = NULL,
  stat = "braid_contour",
  position = "identity",
  ...,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  npoints = 50,
  tight = FALSE,
  trim = TRUE,
  shared = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_braid_contour(
  mapping = NULL,
  data = NULL,
  geom = "contour",
  position = "identity",
  ...,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  npoints = 50,
  tight = FALSE,
  trim = TRUE,
  shared = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

When evaluating a plotted response surface it is often more effective to plot the precise contours at which a set of levels is reached by the combination. Because ggplot2::stat_contour requires that data lie in an evenly space raster grid (and does not support duplicated values), it is difficult to apply to more discrete or irregularly sampled data. This function uses the same smoothing and interpolation utilities as geom_braid_smooth to preprocess and smooth data, which is then passed to the contour estimation code of ggplot2::stat_contour, producing contours which are smoothed and sufficiently regularly spaced.

Examples

surface <- antagonisticExample

ggplot(surface,aes(x=concA,y=concB))+
   geom_braid_smooth(aes(fill=measure))+
   geom_braid_contour(aes(z=measure),colour="black",breaks=((1:9)/10))+
    scale_x_log10("Drug A")+
    scale_y_log10("Drug B")+
    scale_fill_distiller("Effect",palette="RdYlBu")+
    coord_equal()

Smoothed BRAID Surfaces

Description

Summarize and plot measurements of two inputs as a smoothed response surface

Usage

geom_braid_smooth(
  mapping = NULL,
  data = NULL,
  stat = "braid_smooth",
  position = "identity",
  ...,
  space = 1.5,
  trim = TRUE,
  shared = FALSE,
  npoints = 50,
  tight = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_braid_smooth(
  mapping = NULL,
  data = NULL,
  geom = "tile",
  position = "identity",
  ...,
  space = 1.5,
  trim = TRUE,
  shared = FALSE,
  npoints = 50,
  tight = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Like geom_braid, this function involves several pre-processing steps to allow quick visualization of drug combination data. These steps include summarizing duplicated measurements and offsetting non-finite plotted coordinates. In addition to these steps, geom_braid_smooth generates a regular, densely sampled grid of coordinates and smoothly interpolates the given data to produces a smoothed raster heatmap. Smoothing in the x- and y- directions is governed by the width and height aesthetic respectively; if these aesthetics are not included, they are estimated from the minimum spacing of the data.

Examples

surface <- synergisticExample

ggplot(surface,aes(x=concA,y=concB))+
   geom_braid_smooth(aes(fill=measure))+
    scale_x_log10("Drug A")+
    scale_y_log10("Drug B")+
    scale_fill_distiller("Effect",palette="RdYlBu")+
    coord_equal()

BRAID kappa Transforms

Description

Functions to linearize the BRAID interaction parameter kappa, which ordinarily ranges from -2 to infinity. kappa_trans produces a scales transform object which can be used in ggplot2 continuous scale object. scale_x_kappa and scale_y_kappa are wrappers for scale_x_continuous and scale_y_continuous which set the trans or transform parameter to kappa_trans().

Usage

kappa_trans()

scale_x_kappa(...)

scale_y_kappa(...)

Arguments

Value

For kappa_trans a scales transform object. For ⁠scale_*_kappa⁠, a continuous position scale layer for a ggplot object.

Examples

transform <- kappa_trans()

transform$transform(c(-1.96, 100))
transform$inverse(c(-1, 1))

data <- merckValues_stable
ggplot(data,aes(x=kappa))+
    geom_density()+
    scale_x_kappa("BRAID kappa")

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

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)

Best-Fit Bayesian Stabilized Merck OPPS BRAID Values

Description

A table of BRAID kappa and IAE values resulting from running the version 1.0.0 BRAID fitting code on the Merck oncopolypharmacology screen (OPPS), with moderate Bayesian stabilization of kappa.

Usage

merckValues_stable

Format

A data frame with 5 columns:

cell_line

The cancer cell line which the combination was tested

drugA

The first drug in the combination tested

drugB

The second drug in the combination tested

kappa

The best-fit value of the BRAID interaction parameter kappa with moderate Bayesian stabilizatoin

IAE

The index of achievable efficacy (or IAE, a BRAID measure of combined potency) estimated for the best-fit BRAID surface

Best-Fit Unstabilized Merck OPPS BRAID Values

Description

A table of BRAID kappa and IAE values resulting from running the version 1.0.0 BRAID fitting code on the Merck oncopolypharmacology screen (OPPS), with no Bayesian stabilization of kappa.

Usage

merckValues_unstable

Format

A data frame with 5 columns:

cell_line

The cancer cell line which the combination was tested

drugA

The first drug in the combination tested

drugB

The second drug in the combination tested

kappa

The best-fit value of the BRAID interaction parameter kappa with no Bayesian stabilizatoin

IAE

The index of achievable efficacy (or IAE, a BRAID measure of combined potency) estimated for the best-fit BRAID surface

BRAID Surface Analysis

Description

Performs a convenient pre-built set of BRAID and dose-response analysis tasks

Usage

runBraidAnalysis(
  formula,
  data,
  defaults,
  weights = NULL,
  start = NULL,
  direction = 0,
  lower = NULL,
  upper = NULL,
  useBIC = TRUE,
  ...
)

## S3 method for class 'formula'
runBraidAnalysis(
  formula,
  data,
  defaults,
  weights = NULL,
  start = NULL,
  direction = 0,
  lower = NULL,
  upper = NULL,
  useBIC = TRUE,
  ...
)

## Default S3 method:
runBraidAnalysis(
  formula,
  data,
  defaults,
  weights = NULL,
  start = NULL,
  direction = 0,
  lower = NULL,
  upper = NULL,
  useBIC = TRUE,
  ...
)

Arguments

Value

An object of class braidAnalysis, containing the following values:

• concs: a width-two array containing the two tested doses for each measurement

• act: a numeric vector with as many values as concs has rows, containing the measured values for each measurement

• weights: a numeric vector of weights, the same length as act, specifying the weight given to each measurement in fitting. All weights are 1 by default

• braidFit: a fit object of class braidrm containing the best-fit BRAID surface according to the given constraints

• hillFit1: If the given data contains measurements of the first drug in isolation, those measurements are fit using basicdrm::findBestHillModel; the results of this analysis are stored as an object of class hillrm as hillFit1. If no such measurements are found, this will be NULL

• hillFit2: the corresponding fit for measurements of the second drug alone, if they are included; NULL otherwise

Examples

surface <- synergisticExample

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

names(analysis)