so_graph: Graph of simulated vs. observed PK

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

Graph of simulated vs. observed PK

Description

so_graph makes a graph of simulated vs. observed PK, including indicating where the predicted parameters fell within X fold of the observed.

Usage

so_graph(
  PKtable,
  PKparameters = NA,
  PKorder = "default",
  boundary_indicator = "lines",
  boundaries = c(1, 1.5, 2),
  boundaries_Guest = c(1, 2),
  boundary_color_set = "red black",
  boundary_color_set_Guest = "red black",
  boundary_line_types = "default",
  boundary_line_types_Guest = "default",
  boundary_line_width = 0.3,
  error_bars = "none",
  variability_type = "90% CI",
  point_color_column,
  point_color_set = "default",
  legend_label_point_color = NA,
  point_shape_column,
  point_shape = NA,
  point_size = NA,
  point_transparency = 1,
  legend_label_point_shape = NA,
  legend_position = "none",
  axis_title_x = "Observed",
  axis_title_y = "Simulated",
  include_dose_num = NA,
  facet_title_size = NA,
  title_adjustments = c(),
  all_intervals_together = FALSE,
  all_AUCs_together = FALSE,
  grid_color = NA,
  ncol = NULL,
  nrow = NULL,
  save_graph = NA,
  fig_width = 8,
  fig_height = 6,
  return_list_of_graphs = FALSE,
  axis_titles = NA
)

Arguments

PKtable	a table in the same format as output from the function pk_table. This should include a column titled "Statistic" and columns for each of the PK parameters you want to graph. The column statistic should have values of "Simulated" and "Observed" for the simulated and observed PK, respectively; anything else will be ignored. The columns for each PK parameter should be named like the values in the data.frame PKParameterDefinitions, in the column "PKparameter". To see that, please enter view(PKParameterDefinitions) into the console.
PKparameters	any of the AUC, Cmax, tmax, CL, or half-life PK parameters included in the output from pk_table; if left as NA, this will make graphs for each parameter included in PKtable. To see the full set of possible parameters, enter view(PKParameterDefinitions) into the console.
PKorder	optionally specify the order of the graphs. Leaving this as "default" puts the graphs in the same order as the columns in the Simcyp Consultancy Team template for PK tables (plus some guesses at a good order for PK parameters that are not listed in said template table). Setting this to "user specified" will make the order of the graphs match the order you specified with the argument PKparameters. Graphs are plotted left to right and then top to bottom. If you would like a blank space inserted between some parameters – for example, to keep all your Cmax values in the same column or something like that – include "BLANK" in the values you list for PKparameters wherever you want that to happen, e.g., PKparameters = c("Cmax_dose1", "BLANK", "AUCinf_dose1", "BLANK", "tmax_dose1")
boundary_indicator	how to indicate the boundaries for simulated / observed. Options are "lines" (default), "fill" to get a shaded area, or "none" to remove any indicators of those boundaries. NOTE: There is a known bug within RStudio that causes filled semi-transparent areas like you get with the "fill" option to NOT get graphed for certain versions of RStudio. To get around this, within RStudio, go to Tools –> Global Options –> General –> Graphics –> And then set "Graphics device: backend" to "AGG". Honestly, this is a better option for higher-quality graphics anyway!
boundaries	Numerical boundaries to show on the graph. Defaults to the 1.5- and 2-fold boundaries. Indicate boundaries you want like this: boundaries = c(1.25, 1.5, 2)
boundaries_Guest	Numerical boundaries to show on the graph when the PK parameter is a mean ratio of the parameter in the presence of a perpetrator / the parameter in the absence of the perpetrator. Please see [BoundariesGuest Galetin 2011 Drug Metab Dispos](https://pubmed.ncbi.nlm.nih.gov/21036951/) for a reference for this type of graph. If you'd rather show straight lines for these parameters instead of BoundariesGuest curves, set this to NA. The default boundaries for BoundariesGuest curves are 1 (straight line at unity; even if you don't include 1, we'll add it back in) and 2. For all numbers > 1, you'll get a BoundariesGuest curve that approaches that value at higher DDI ratios, and, for the highest number you list, you'll additionally get straight line boundaries. This matches what is described in the BoundariesGuest Galetin 2011 paper. We recommend using only 1 and 2 as BoundariesGuest boundaries for clarity of the graph.
boundary_color_set	set of colors to use for indicating the X-fold boundaries of the simulated / observed ratio. The default is "red black", which, for the default boundaries, results in a black line at the 1.5-fold boundary and a red one at the 2-fold boundary. Other options are "red green", "muted red green" (a lighter, more muted red and green that work well for indicating boundaries when you're using shading instead of lines), and "black", which will result in only black lines or shading. You also can set this to any set of colors you'd like, e.g., boundary_color_set = c("yellow", "blue"). The number of colors should equal the number of boundaries that you've indicated or the graph won't be easily interpretable.
boundary_color_set_Guest	set of colors to use for indicating the X-fold boundaries of the simulated / observed ratio for DDI ratio graphs. The default is "red black", which, for the default BoundariesGuest boundaries, results in a black curved line and a red straight line at the 2-fold boundary. Other options are "red green", "muted red green" (a lighter, more muted red and green that work well for indicating boundaries when you're using shading instead of lines), and "black", which will result in only black lines or shading. You also can set this to any set of colors you'd like, e.g., boundary_color_set_Guest = c("yellow", "blue"). The number of colors should equal the number of BoundariesGuest boundaries that you've indicated or the graph won't be easily interpretable.
boundary_line_types	optionally specify the line types to use for the boundaries (only applicable when boundary_indicator = "lines"). Leaving this as "default" results in a dashed line at unity and solid lines for all others, but you can specify this with any R-acceptable line types, e.g., boundary_line_types = c("dotted", "dashed", "solid"). To see the possibilities, type ggpubr::show_line_types() into the console.
boundary_line_types_Guest	optionally specify the line types to use for the DDI ratio graph boundaries (only applicable when boundary_indicator = "lines"). Leaving this as "default" results in a dashed line at unity and solid lines for all others, but you can specify this with any R-acceptable line types, e.g., boundary_line_types_Guest = c("dotted", "dashed", "solid"). To see the possibilities, type ggpubr::show_line_types() into the console.
boundary_line_width	line width; default is 0.7. This only applies when boundary_indicator is set to "lines", the default.
error_bars	Which error bars should be shown on the graph? Options are "none" (default), "simulated" to show vertical error bars ("vertical" also works in case that's easier to remember), "observed" ("horizontal" also works), or "both".
variability_type	If you're including error bars, what kind of variability would you like to have those error bars display? Options are "90 ("SD" will also work fine), or "range". If error_bars is set to "none", this will be ignored.
point_color_column	(optional) the column in PKtable that should be used for determining which color the points will be. This should be unquoted. For example, if you have a column named "Study" in the data.frame you're using for PKtable and you want to color the points by which study they came from, you would use: point_color_column = Study.
point_color_set	the set of colors to use for the points. Options: "default" black if nothing is specified for point_color_column and, otherwise, a set of colors from Cynthia Brewer et al. from Penn State that are friendly to those with red-green colorblindness. The first three colors are green, orange, and purple. This can also be referred to as "Brewer set 2". If there are only two unique values in the point_color_column, then Brewer set 1 will be used since red and blue are still easily distinguishable but also more aesthetically pleasing than green and orange. "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. "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. "blues" a set of blues fading light blue to dark blue. Like "blue-green", this palette can be especially useful if you are comparing a systematic change in some continuous variable. Other similar continuous color sets to try out: "purples", "greens", or "reds". "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 point_color_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.
legend_label_point_color	optionally indicate on the legend something explanatory about what the colors represent. For example, if point_color_column = Study and legend_label_point_color = "Studies included", that will make the label above the items in the legend "Studies included" rather than the default, which is to use whatever the column name is for point_color_column. If you don't want a label for this legend item, set this to "none".
point_shape_column	(optional) the column in PKtable that should be used for determining which shape the points will be. This should be unquoted. For example, if you have a column named "DosingFrequency" in the data.frame you're using for PKtable and you want to change the shape of the points by which dosing frequency was used, you would use: point_color_column = DosingFrequency.
point_shape	optionally specify what shapes are used for the points. Input should look like this, for example: c(1, 2) to get an open circle and an open triangle. If you only specify one value, it will be used for all points. If you don't specify anything for point_shape_column, then only the first value listed will be used. To see all the possible shapes and what number corresponds to which shape, type ggpubr::show_point_shapes() into the console. If left as NA, all points will be filled circles.
point_size	optionally specify the size of the points to use for the observed data. If left as NA, the size will be 2.
point_transparency	optionally specify how transparent to make the points. The default of 1 will make completely opaque points, and 0 would be completely transparent (invisible).
legend_label_point_shape	optionally indicate on the legend something explanatory about what the colors represent. For example, if point_color_column = Study and legend_label_point_color = "Studies included", that will make the label above the items in the legend "Studies included" rather than the default, which is to use whatever the column name is for point_color_column. If you don't want a label for this legend item, set this to "none".
legend_position	Specify where you want the legend to be. Options are "left", "right" (default in most scenarios), "bottom", "top", or "none" if you don't want one at all.
axis_title_x	title for the x axis; default is "Observed"
axis_title_y	title for the y axis; default is "Simulated"
include_dose_num	Should the dose number be included? If set to TRUE, then the dose number part of the graph title, e.g., the "Dose 1" or "Last dose" part of "Dose 1 AUCinf" or "Last dose Cmax", will be included. If set to FALSE, those would be come "AUCinf" and "Cmax" only with no reference to which dose it was. If left as the default NA, then the dose number will be omitted if all the data are all for dose 1 or all for the last dose, and it will be included if you have a mix of dosing intervals.
facet_title_size	optionally specify what font size to use for the facet titles. If left as NA, a reasonable guess will be used.
title_adjustments	a character vector or list of text adjustments for the graph titles. Possible options: "sub steady-state for last" Instead of the default PK parameters for the last dose being labeled as, e.g., "Last dose Cmax", this will use "steady-state" instead, e.g., "Steady-state Cmax" "use my expressions" If you'd like to use your own specific R expressions rather than the defaults included in the package, you can do that. You will need to supply a list here, and all of your PK parameters must be included or things will not work well. Here is an example of how to use this: title_adjustments = list("AUCtau_last" = expression(AUC[t]), "Cmax_last" = expression(C[max]), "Cmin_last" = expression(C[trough])) sub 0 to inf for inf NOT SET UP YET. This is a placeholder for other substitutions people might want. Instead of the using AUCinf, graph titles will use AUC0 to inf
all_intervals_together	TRUE or FALSE (default) for whether to combine all of a single type of PK parameter into a single graph. For example, setting this to TRUE would put all the Cmax PK – regardless of whether it was for the 1st dose, the last dose, or a custom interval – into a single graph. The default, FALSE, means that anything that was its own column in the PK summary table would also be its own graph here. NOTE: If you do set this to TRUE, the shape of the points will be mapped to which interval it is, which means that you can't also specify something for the argument point_shape_column. If you do, it will be ignored. Try this out if you're uncertain what we mean.
all_AUCs_together	TRUE or FALSE (default) for whether to combine, e.g., AUCinf and AUCt for dose 1 into a single graph. Be careful with this because if you have points for both AUCinf and AUCt for a simulation, then BOTH of those points will show up on the graph.
grid_color	optionally specify the color of the major and minor grid lines on your graph. Default is "grey92", which is the standard grey for theme_bw() in ggplot2. Set this to "none" if you want no grid lines under your graph.
ncol	number of columns of graphs to show. If left as NULL (default), R will make a reasonable guess for the number.
nrow	number of rows of graphs to show. If left as NULL (default), R will make a reasonable guess for the number.
save_graph	optionally save the output graph by supplying a file name in quotes here, e.g., "My conc time graph.png"
fig_width	figure width in inches; default is 6
fig_height	figure height in inches; default is 8
return_list_of_graphs	TRUE or FALSE (default) for whether to return a list of each individual graph as its own separate ggplot2 object.
axis_titles	SOON TO BE DEPRECATED in favor of axis_title_x and axis_title_x. Optionally specify what you'd like for the x and y axis titles with a named character vector. The default is axis_titles = c("x" = "Observed", "y" = "Simulated")

Value

a set of arranged ggplot2 graphs

Examples

# Assuming you have run pk_table on a few files with observed data
# to generate an object called MyPKOutput, then:
so_graph(PKtable = SOdata)
so_graph(PKtable = SOdata, boundary_indicator = "fill")
so_graph(PKtable = SOdata,
         axis_titles = c("y" = "Predicted", "x" = "Observed"))
so_graph(PKtable = SOdata, ncol = 1)
so_graph(PKtable = SOdata, point_shape_column = Study,
         legend_position = "bottom")
so_graph(PKtable = SOdata,
         point_shape_column = Study,
         legend_label_point_shape = "Studies involving\nDrug X",
         point_color_column = File,
         legend_label_point_color = "Simulation file",
         legend_position = "right")

shirewoman2/Consultancy documentation built on June 1, 2025, 6:05 p.m.