sensitivity_plot: Make graphs of sensitivity analysis results

In shirewoman2/Consultancy: Standardized tools for using R within the Simcyp Consultancy Team

Make graphs of sensitivity analysis results

Description

sensitivity_plot will read a sensitivity-analysis Excel file and create a graph of the dependent variable of your choice as long as it was included in your results. If you ran a sensitivity analysis with more than 1 independent variable – e.g., you wanted to see how adjusting both the kp scalar and the fa affected Cmax – the best way we have come up with so far to show you how both of those variables affect your dependent variable is to break up the graphs into small multiples or facets (like on a gemstone). (Side note: We considered a 3D graph, but they're honestly hard to do well in a programmatic fashion like this.)

Coding notes: This function does not detect units, so please check your graph labels. We plan to add options for axis breaks as well as color schemes. We are in the process of adding more options for labeling the sensitivity parameter in the graphs. This funciton does not do 3D graphs and we have no plans to add option for 3D graphs because A) they're just not easy to interpret and B) there aren't great R packages out there for 3D graphs.

Usage

sensitivity_plot(
  SA_file,
  dependent_variable,
  ind_var_label = NA,
  target_DV = NA,
  color_by_which_indvar = "1st",
  linear_or_log = "linear",
  y_axis_limits_lin = NA,
  y_axis_limits_log = NA,
  x_axis_limits_lin = NA,
  x_axis_limits_log = NA,
  time_range = NA,
  rounding = "significant 3",
  color_set = "blues",
  graph_title = NA,
  save_graph = NA,
  fig_height = 4,
  fig_width = 5,
  return_data = FALSE
)

Arguments

SA_file	sensitivity analysis Excel file
dependent_variable	dependent variable to plot. Options are: "AUC", "AUC over dose", "AUC over dose with interaction", "AUC ratio", "CL", "CLpo", "CLpo with interaction", "Cmax", "Cmax with interaction", "Cmax ratio", "dose over AUC", "dose over AUC with interaction", "fa", "Fg", "Fg with interaction", "Fh", "Fh with interaction", "Vss", "tmax", "tmax with interaction", or "plasma concentration" (just "plasma" will also work). Other than "plasma concentration", which is always included in sensitivity analysis output, that parameter must be one of the ones you requested when you ran the sensitivity analysis. Not case sensitive.
ind_var_label	optionally specify what text use for labeling the independent variable (the x axis). If left as NA, R will find the value listed next to "Run Number" on the "ASA Summary" tab, which may be something not terribly pretty like "Fugut Value (Sub) (No Units)", and attempt to prettify it. If we haven't set things up to prettify that value, which is likely as we haven't used this function with very many sensitivity-analysis scenarios yet, the value will be unchanged. (If you have an independent variable you'd like to add to our list, please email Laura Shireman.)
target_DV	optionally specify a target value for the dependent variable, which will add a horizontal red dotted line to the graph where the target lies.
color_by_which_indvar	If you have more than one independent variable, you can specify which one you want to adjust the colors by. Options are "1", "1st", or "first" (all will work, default) to adjust the colors in the graph based on the first independent variable listed in the Excel SA file or "2", "2nd", or "second" to adjust colors based on the second. If you only have one independent variable, this will be ignored.
linear_or_log	make the y axis "linear" (default) or "log" for plasma concentration-time plots. If you're graphing some other dependent variable, you can also opt for "log x" to log-transform the x axis, "log y" to log-transform the y axis (same as a traditional semi-log plot), or "both log", which will log transform both the x and y axes.
y_axis_limits_lin	optionally set the Y axis limits for the linear plot, e.g., c(10, 1000). If left as the default NA, the Y axis limits for the linear plot will be automatically selected.
y_axis_limits_log	optionally set the Y axis limits for the semi-log plot, e.g., c(10, 1000). Values will be rounded down and up, respectively, to a round number. If left as the default NA, the Y axis limits for the semi-log plot will be automatically selected.
x_axis_limits_lin	optionally set the X axis limits for the linear plot, e.g., c(10, 1000). If left as the default NA, the X axis limits for the linear plot will be automatically selected. This does not apply when the dependent variable requested is plasma concentrations.
x_axis_limits_log	optionally set the X axis limits for the log plot, e.g., c(10, 1000). Values will be rounded down and up, respectively, to a round number. If left as the default NA, the X axis limits for the semi-log plot will be automatically selected. This does not apply when the dependent variable requested is plasma concentrations.
time_range	time range to show relative to the start of the simulation for any concentration-time plots. This does not apply when the plot is of some other dependent variable than plasma. Options: NA (default) entire time range of data a start time and end time in hours only data in that time range, e.g. c(24, 48). Note that there are no quotes around numeric data.
rounding	option for what rounding to perform, if any. Options are: "significant X" where "X" is a number (default: "significant 3") Output will be rounded to X significant figures. "signif X" also works fine. "none" No rounding will be performed. "round X" where "X" is a number Output will be rounded to X digits
color_set	the set of colors to use. Options: "blues" (default) a set of blues fading from sky to navy. Like "blue-green", this palette can be especially useful if you are comparing a systematic change in some continuous variable. "greens" a set of greens fading from chartreuse to forest. Like "blue-green", this palette can be especially useful if you are comparing a systematic change in some continuous variable. "purples" a set of purples fading from lavender to aubergine. Like "blue-green", this palette can be especially useful if you are comparing a systematic change in some continuous variable. "blue-green" a set of blues fading into greens. This palette can be especially useful if you are comparing a systematic change in some continuous variable – for example, increasing dose or predicting how a change in intrinsic solubility will affect concentration-time profiles – because the direction of the trend will be clear. "Brewer set 1" colors selected from the Brewer palette "set 1". The first three colors are red, blue, and green. "ggplot2 default" the default set of colors used in ggplot2 graphs (ggplot2 is an R package for graphing.) "rainbow" colors selected from a rainbow palette. The default palette is limited to something like 6 colors, so if you have more than that, that's when this palette is most useful. It's not very useful when you only need a couple of colors. "Tableau" uses the standard Tableau palette; requires the "ggthemes" package "viridis" from the eponymous package by Simon Garnier and ranges colors from purple to blue to green to yellow in a manner that is "printer-friendly, perceptually uniform and easy to read by those with colorblindness", according to the package author a character vector of colors If you'd prefer to set all the colors yourself to exactly the colors you want, you can specify those colors here. An example of how the syntax should look: color_set = c("dodgerblue3", "purple", "#D8212D") or, if you want to specify exactly which item in colorBy_column gets which color, you can supply a named vector. For example, if you're coloring the lines by the compound ID, you could do this: color_set = c("substrate" = "dodgerblue3", "inhibitor 1" = "purple", "primary metabolite 1" = "#D8212D"). If you'd like help creating a specific gradation of colors, please talk to a member of the R Working Group about how to do that using colorRampPalette.
graph_title	(optional) a title to include on your graph in quotes
save_graph	optionally save the output graph by supplying a file name in quotes here, e.g., "My conc time graph.png" or "My conc time graph.docx". If you leave off ".png" or ".docx" from the file name, it will be saved as a png file, but if you specify a different graphical file extension, it will be saved as that file format. Acceptable graphical file extensions are "eps", "ps", "jpeg", "jpg", "tiff", "png", "bmp", or "svg". Do not include any slashes, dollar signs, or periods in the file name. Leaving this as NA means the file will not be saved to disk.
fig_height	figure height in inches; default is 4
fig_width	figure width in inches; default is 5
return_data	TRUE or FALSE (default) on whether to return the data used to make the graph

Value

a ggplot2 graph

Examples

sensitivity_plot(SA_file = "SA example.xlsx",
                 dependent_variable = "Cmax",
                 graph_title = "My pretty sensitivity-analysis graph that's not pink",
                 save_graph = "SA graph")

shirewoman2/Consultancy documentation built on Feb. 18, 2025, 10 p.m.