trial_means_plot: Make graphs comparing the center statistic and variability in...

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

Make graphs comparing the center statistic and variability in PK across trials and, optionally, against observed PK

Description

trial_means_plot creates a graph comparing variability across simulated trials and, when supplied, across observed trials as well for a given PK parameter. The central statistic is shown as a dot and the variability statistic is shown as error bars for each of the trials, and you can choose which statistics you want for each, e.g., geometric means for the central statistic and the geometric 90% confidence interval for the variability statistic. UNDER CONSTRUCTION.

IMPORTANT: If the summary statistics used for your observed data don't match the summary statistics you choose for mean_type and variability_type, you will get a misleading graph, so be careful!

Usage

trial_means_plot(
  sim_data_file,
  PKparameter = "Cmax_dose1",
  compoundToExtract = "substrate",
  tissue = "plasma",
  sheet = NA,
  mean_type = "geometric",
  variability_type = "percentiles",
  observed_PK = NA,
  lines_for_population_stats = "gray80 solid dotted",
  color_set = "default",
  color_option = "by study",
  point_shape = NA,
  point_size = NA,
  bar_width = NA,
  y_axis_limits_lin = NA,
  legend_position = "right",
  include_dose_num = FALSE,
  graph_title = NA,
  graph_title_size = 14,
  existing_exp_details = NA,
  return_caption = FALSE,
  prettify_compound_names = TRUE,
  clin_study_label_option = "observed or study number",
  save_graph = NA,
  fig_height = NA,
  fig_width = NA
)

Arguments

sim_data_file	name of the Excel file containing the simulator output, in quotes
PKparameter	PK parameter you want to extract from the simulator output file. To see the full set of possible parameters to extract, enter view(PKParameterDefinitions) into the console. Not case sensitive.
compoundToExtract	For which compound do you want to extract PK data? Options are: "substrate" (default), "primary metabolite 1", "primary metabolite 2", "secondary metabolite", "inhibitor 1" – this can be an inducer, inhibitor, activator, or suppresesor, but it's labeled as "Inhibitor 1" in the simulator, "inhibitor 2" for the 2nd inhibitor listed in the simulation, "inhibitor 1 metabolite" for the primary metabolite of inhibitor 1
tissue	For which tissue would you like the PK parameters to be pulled? Options are "plasma" (default), "unbound plasma", "blood", "unbound blood", "peripheral plasma", or "peripheral blood". NOTE: PK for peripheral sampling is not as well tested as for other tissues and is only set up for V21+. Please check your results carefully.
sheet	optionally specify the name of the sheet where you'd like to pull the PK data, in quotes. For example, if you have a user-defined AUC interval, specify the tab where those data are. NOTE: If you want typical first- or last-dose PK, this should be left as NA. This only applies for user-defined AUC intervals.
mean_type	What kind of means do you want to use for the center point on the graph? Options are "geometric" (default), "arithmetic", or "median".
variability_type	What variability statistic to you want to use for the error bars? Options are "percentiles" for the 5th to 95th percentiles (default), "90% CI", "SD", "CV", "GCV" (for geometric CV), or "range".
observed_PK	a data.frame of observed PK that you would like to compare. This must include the columns "ObsValue" or "Value" for the center value for the observed data and "ObsVariability" or "Variability" for the error bars for the observed data. Some filtering this will do automatically: If you include a column titled "File", we will only use PK data that have the same value in that column as what you supply for sim_data_file. If you include a column titled "PKparameter", we will only use PK data that match what you supply for PKparameter. If you want to include comparisons to more than one clinical study, add a column titled "Study" to your data. The value listed in that column will be used for labeling the study on your graph. If there is not a column titled "Study" in your observed PK, we will label the data in the graph as "observed". If you include a column titled "CompoundID", we will only include PK data that match what you supplied for compoundToExtract. If you include a column titled "Tissue", we will only include PK data that match what you supplied for tissue.
lines_for_population_stats	optionally include horizontal lines for the overall simulated population statistics by specifying the desired line color and type. Set this as a single text string of 1) the color for the lines (any R-friendly color specification will work), 2) the linetype for the central statistic (any R-friendly linetype will work), 3) the linetype for the variability statistic, and, optional, 4) the linewidth to use. If you omit the linewidth, we'll use a linewidth of 0.5 by default. The default of "gray80 solid dotted" will make a light gray solid line at the central statistic and a light gray dotted line at whatever you choose for the variability statistic. If you set this to "none", no lines will be included.
color_set	the set of colors to use. Options: "default" 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 colorBy_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. "black and white" ("BW" also works) black and white only. "white" means a black circle with a white center. If you set color_option = "S or O", the simulated trials will be white and the observed will be black. This looks like the trial-means plots in the Excel outputs from the Simulator. "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 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. "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.
color_option	How do you want to color information in the graph? Options are: "by study" (default) all simulated trials will be the first color from color_set and then each set of observed data will be a different color from that set "by trial" uses a different color from color_set for every trial, whether simulated or observed "simulated or observed" ("S or O" and "S vs O" will also work) color points based on whether they were simulated or observed
point_shape	optionally specify what shape to use. 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, an open circle will be used.
point_size	optionally specify what point size to use. If left as NA, the point size will be set to 3.
bar_width	optionally specify the error bar width. If left as NA, the error bar width will be set to 0.25.
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. (Setting up semi-log plot y axis intervals manually is a bit tricky and is not currently supported.)
legend_position	specify where you want the legend to be. Options are "left", "right" (default), "bottom", "top", or "none" if you don't want one at all.
include_dose_num	TRUE or FALSE (default) on whether to include the dose number when listing the PK parameter.
graph_title	optionally specify a title that will be centered across your graph or set of graphs
graph_title_size	the font size for the graph title if it's included; default is 14. This also determines the font size of the graph labels.
existing_exp_details	If you have already run extractExpDetails_mult to get all the details from the "Input Sheet" (e.g., when you ran extractExpDetails you said exp_details = "Summary and Input" or exp_details = "all"), you can save some processing time by supplying that object here, unquoted. If left as NA, this function will run extractExpDetails behind the scenes anyway to figure out some information about your experimental set up.
return_caption	TRUE or FALSE (default) for whether to return any caption text to use with the graph. This works best if you supply something for the argument existing_exp_details. If set to TRUE, you'll get as output a list of the graph, the figure heading, and the figure caption.
prettify_compound_names	TRUE (default), FALSE or a character vector: This is asking whether to make compound names prettier in the figure heading and caption. This was designed for simulations where the substrate and any metabolites, perpetrators, or perpetrator metabolites are among the standard options for the simulator, and leaving prettify_compound_names = TRUE will make the name of those compounds something more human readable. For example, "SV-Rifampicin-MD" will become "rifampicin", and "Sim-Midazolam" will become "midazolam". Setting this to FALSE will leave the compound names as is. For an approach with more control over what the compound names will look like in legends and Word output, set each compound to the exact name you want with a named character vector where the names are "substrate" and, as applicable, "inhibitor 1", "primary metabolite 1", etc. and the values are the names you want, e.g., prettify_compound_names = c("inhibitor 1" = "teeswiftavir", "substrate" = "superstatin").
clin_study_label_option	Clinical study names are generally much longer than the names of the simulated trial means, which will be just "1", "2", etc., so the labels like "Clinical Study 101, fasted healthy subjects" just won't fit nicely by comparison. For this reason, you can choose how observed data study names should be automatically shortened. Options: "observed or study number" when there's only 1 clinical study, we'll label that as "observed" in the graph, but when there's more than one, we'll label the studies as "study 1", "study 2", etc. "study number" this will make the label always be, e.g., "study 1", "study 2", etc., even if there is only 1 study. "keep" or "keep original" this will retain the original value for the study name, even if it's really long and awkward.
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". The nice thing about saving to Word is that the figure title and caption text will be filled in automatically. If you leave off ".png" or ".docx", the graph 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
fig_width	figure width in inches

Value

a ggplot2 graph

Examples

# None yet

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