ct_plot: Concentration-time plots to match Consultancy template

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

Concentration-time plots to match Consultancy template

Description

Using observed and simulated concentration-time data generated from the function extractConcTime, make publication-quality graphs that comply with the Simcyp Consultancy Team's standards. We've tried to include a fair number of options here for flexibility, but many of the function arguments are optional; most of the time, you'll get decent-looking graphs while only setting a minimal number of arguments.

For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Concentration-time plots 1 - one sim at a time/Concentration-time-plot-examples-1.docx". (Sorry, we are unable to include a link to it here.)

A few notes:

1. Not all substrate metabolites, inhibitors, or inhibitor metabolites are available in all tissues. If it's not present in your output, we can't graph it here.

2. If you have observed concentration-time data to match your simulated data but you don't see those observed data on your graph, please check the help file for the function you used – either extractConcTime or extractConcTime_mult – to extract your data. Something has likely gone wrong in the data extraction.

3. If you attempt to use data generated by extractConcTime_mult here, you can get weird results if you're not careful to include only one tissue and one compound. If you see something odd, try including the legend with, e.g., legend_position = "right" to help decipher what might have gone awry. It can also be informative to use the function ct_plot_overlay to make a draft version of your graph because that function will give you some messages about what data are included.

4. If you want to plot enzyme abundance data, please see enz_plot or enz_plot_overlay.

Usage

ct_plot(
  ct_dataframe = NA,
  figure_type = "percentiles",
  Tissue_subtype = NA,
  mean_type = "arithmetic",
  time_range = NA,
  x_axis_interval = NA,
  x_axis_label = NA,
  time_units_to_use = NA,
  pad_x_axis = TRUE,
  pad_y_axis = TRUE,
  adjust_obs_time = FALSE,
  t0 = "simulation start",
  y_axis_limits_lin = NA,
  y_axis_limits_log = NA,
  y_axis_interval = NA,
  y_axis_label = NA,
  conc_units_to_use = NA,
  obs_color = NA,
  obs_shape = NA,
  obs_size = NA,
  obs_fill_trans = NA,
  obs_line_trans = NA,
  connect_obs_points = FALSE,
  obs_on_top = TRUE,
  include_errorbars = FALSE,
  errorbar_width = 0.5,
  showBLQ = FALSE,
  line_type = NA,
  line_transparency = NA,
  line_color = NA,
  line_width = NA,
  hline_position = NA,
  hline_style = "red dotted",
  vline_position = NA,
  vline_style = "red dotted",
  legend_position = "none",
  legend_orientation = NA,
  legend_label = NA,
  prettify_compound_names = TRUE,
  linear_or_log = "both vertical",
  graph_labels = TRUE,
  graph_title = NA,
  graph_title_size = 14,
  qc_graph = FALSE,
  existing_exp_details = NA,
  return_caption = FALSE,
  name_clinical_study = NA,
  save_graph = NA,
  fig_height = NA,
  fig_width = NA,
  subsection_ADAM = "deprecated"
)

Arguments

ct_dataframe	the input concentration-time data generated by running the function extractConcTime. Not quoted.
figure_type	type of figure to plot. Options are: "percentiles" (default) plots an opaque line for the mean data, lighter lines for the 5th and 95th percentiles of the simulated data, and open circles for the observed data. If an effecter were present, the default is dashed lines for the data in the presence of a perpetrator. "trial means" plots an opaque line for the mean data, lighter lines for the mean of each trial of simulated data, and open circles for the observed data. If a perpetrator were present, lighter dashed lines indicate the mean of each trial of simulated data in the presence of the perpetrator. "percentile ribbon" plots an opaque line for the mean data, transparent shading for the 5th to 95th percentiles of the simulated data, and open circles for the observed data. If a perpetrator were present, the default is to show the data without the perpetrator in blue and the data in the presence of the perpetrator in red. NOTE: There is a known bug within RStudio that causes filled semi-transparent areas like you get with the "percentile ribbon" figure type 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! "means only" plots a black line for the mean data and, if an perpetrator was modeled, a dashed line for the concentration-time data with Inhibitor 1. "Freddy" Freddy's favorite style of plot with trial means in light gray, the overall mean in thicker black, the 5th and 95th percentiles in dashed lines, and the observed data in semi-transparent purple-blue. Graphs with a perpetrator present lose the trial means, and the percentiles switch to solid, gray lines. An editorial comment: While this does not align with the officially sanctioned template at this time, this looks sharp, makes it easy to see the defining characteristics of the data, and I recommend checking it out, even just for your own purposes of examining your data. If the color is too much for you but you like the rest, try setting obs_color = "black", obs_shape = c(1, 2). -LSh "compound summary" matches the concentration-time plots in Simcyp compound summary files. These are similar to "Freddy" types of graphs in that they show the mean as a dark line, the trial means as lighter lines, dashed lines for the 5th and 95th percentiles, but then they additionally color observed points by a column titled "Study" that you will need to add to your data. (And yes, it must be titled "Study" exactly.) Everything else in these graphs will be gray or black, but you can specify the color of the observed points with the argument "obs_color" and the shape of the points with the argument "obs_shape".
Tissue_subtype	Certain types of models have additional subtypes of tissues. Currently, the SimcypConsultancy package supports ADAM-model and brain-compartment tissue subtypes. In these scenarios, it's not sufficient to say "colon" or "brain" because those tissues have multiple subtypes. This is where you can specify which you want. Default is "free compound in lumen" but is ignored when ct_dataframe doesn't contain ADAM data.
mean_type	graph "arithmetic" (default) or "geometric" means or "median" for median concentrations. If that option was not included in the output, you'll get a warning and the graph will include one that was.
time_range	time range to show relative to the start of the simulation. 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. "first dose" only the time range of the first dose "last dose" only the time range of the last dose "penultimate dose" only the time range of the 2nd-to-last dose, which can be useful for BID data where the end of the simulation extended past the dosing interval or data when the substrate was dosed BID and the perpetrator was dosed QD a specific dose number with "dose" or "doses" as the prefix the time range encompassing the requested doses, e.g., time_range = "dose 3" for the 3rd dose or time_range = "doses 1 to 4" for doses 1 to 4 a specific day number with "day" or "days" as the prefix the time range encompassing the requested days, e.g., time_range = "day 2" for the 24-hour period starting on day 2, e.g., 24-48 hours, or time_range = "days 1 to 4" for the 4-day period from 0 to 96 hours "all obs" or "all observed" if you feel like spelling it out Time range will be limited to only times when observed data are present. "last dose to last observed" or "last obs" for short Time range will be limited to the start of the last dose until the last observed data point. "last dose to end" or "last to end" for short Time range will be limited to the start of the last dose until the end of the simulation.
x_axis_interval	optionally set the x-axis major tick-mark interval. Acceptable input: any number or leave as NA to accept default values, which are generally reasonable guesses as to aesthetically pleasing and PK-relevant intervals.
x_axis_label	optionally supply a character vector or an expression to use for the x axis label
time_units_to_use	time units to use for graphs. If left as NA, the time units in the source data will be used. Options are "hours", "minutes", "days", or "weeks".
pad_x_axis	optionally add a smidge of padding to the the x axis (default is TRUE, which includes some generally reasonable padding). If changed to FALSE, the y axis will be placed right at the beginning of your time range and all data will end exactly at the end of the time range specified. If you want a specific amount of x-axis padding, set this to a number; the default is c(0.02, 0.04), which adds 2% more space to the left side and 4% more to the right side of the x axis. If you only specify one number, we'll assume that's the percent you want added to the left side.
pad_y_axis	optionally add a smidge of padding to the y axis (default is TRUE, which includes some generally reasonable padding). As with pad_x_axis, if changed to FALSE, the x axis will be placed right at the bottom of your data, possibly cutting a point in half. If you want a specific amount of y-axis padding, set this to a number; the default is c(0.02, 0), which adds 2% more space to the bottom and nothing to the top of the y axis. If you only specify one number, we'll assume that's the percent you want added to the bottom.
adjust_obs_time	TRUE or FALSE (default) for whether to adjust the time listed in the observed data file to match the last dose administered. This only applies to multiple-dosing regimens. If TRUE, the graph will show the observed data overlaid with the simulated data such that the dose in the observed data was administered at the same time as the last dose in the simulated data. If FALSE, the observed data will start at whatever times are listed in the Excel file.
t0	What event should be used for time zero? Options are: "simulation start" (default), "dose 1", "penultimate dose", or "last dose". This does not change which data are included in the graph; instead, this determines whether the x axis numbers are offset so that, e.g., the last dose is administered at time 0.
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.)
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.
y_axis_interval	set the linear y-axis major tick-mark interval. Acceptable input: any number or leave as NA to accept default values, which are generally reasonable guesses as to aesthetically pleasing intervals.
y_axis_label	optionally supply a character vector or an expression to use for the y axis label
conc_units_to_use	concentration units to use for graphs. If left as NA, the concentration units in the source data will be used. Acceptable options are "mg/L", "mg/mL", "µg/L" (or "ug/L"), "µg/mL" (or "ug/mL"), "ng/L", "ng/mL", "µM" (or "uM"), or "nM". If you want to use a molar concentration and your source data were in mass per volume units or vice versa, you'll need to provide something for the argument existing_exp_details.
obs_color	If you would like the observed data points to be in color, either specify a color here or leave this as NA to get all black points for most graph types or, if you set something for line_color, whatever colors were used for that, semi-transparent blue-purple for a figure_type of "Freddy", or a different color for each study (you must have a column titled "Study" in ct_dataframe for this to work) for a figure_type of "compound summary". Setting this to "none" will remove observed data from the graph. Hex color codes are also ok to use. If you've got a figure_type of "compound summary", then you can specify each color you want or you can call on one of the possible color sets: 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. "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. Great for showing systematic changes in a continuous variable. "purples" a set of purples fading from lavender to aubergine. Great for showing systematic changes in a continuous variable. "reds" a set of reds from pink to brick. Great for showing systematic changes in a 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.
obs_shape	optionally specify what shapes are used to depict observed data for 1. the substrate drug alone and 2. the substrate drug in the presence of a perpetrator. Input should look like this, for example: c(1, 2) to get an open circle and an open triangle. 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, substrate alone will be an open circle and substrate + inhibitor 1 will be an open triangle.
obs_size	optionally specify the size of the points to use for the observed data. If left as NA, the size will be 2.
obs_fill_trans	optionally specify the transparency for the fill of the observed data points, which can be helpful when you have a lot of points overlapping. This only applies when you have specified a value for obs_color since, for most of the graph types, the observed data is depicted as an open circle by default. Acceptable values are from 0 (fully transparent, so no fill at all) to 1 (completely opaque or black). If left as the default NA, the observed data points will be 50 same as if this were set to 0.5.
obs_line_trans	optionally specify the transparency for the outline of the observed data points, which can be helpful when you have a lot of points overlapping. Acceptable values are from 0 (fully transparent, so no line at all) to 1 (completely opaque or black). If left as the default NA, the observed data points will be opaque, so the same as if this were set to 1.
connect_obs_points	TRUE or FALSE (default) for whether to add connecting lines between observed data points from the same individual
obs_on_top	TRUE (default) or FALSE for whether to show the observed data on top of the simulated data. If FALSE, the simulated data will be on top.
include_errorbars	TRUE or FALSE (default) for whether to include error bars for observed data points. This ONLY applies when you have supplied observed data from V22 or higher because those data files included a column titled "SD/SE", which is what we'll use for determining the error bar heights.
errorbar_width	width of error bars to use in hours (or, if you've used some other time unit, in whatever units are in your data). Default is 0.5.
showBLQ	TRUE or FALSE (default) to display observed concentrations that were clearly below the lower limit of quantitation, that is, concentrations equal to 0 after time 0. The default (FALSE) removes these values so that they will not show up on graphs.
line_type	Optionally specify what types of lines are used to depict the substrate drug alone and the substrate drug in the presence of a perpetrator (when applicable). Input should look like this, for example: c("solid", "dashed") to get a solid line for the substrate drug and a dashed line for inhibitor 1. To see all possible line_type options: ggpubr::show_line_types() If left as NA, substrate alone will be a solid line and substrate + inhibitor 1 will be a dashed line. If figure_type is "Freddy" and there's no perpetrator present, which is a slightly different scenario than the other graph types, the 1st line type specified will be for the mean simulated concentration and the trial means, and the 2nd line type specified will be for the 5th and 95th percentiles.
line_transparency	optionally specify the transparency for the trial mean or percentile lines. Acceptable values are from 0 (fully transparent, so no line at all) to 1 (completely opaque or black). If left as the default NA, this value will be automatically determined.
line_color	optionally specify what colors to use for the lines. Acceptable input for, e.g., the substrate alone to be blue and the substrate + Inhibitor 1 to be red: c("blue", "red"). If left as the default NA, lines will be black or gray. Hex color codes are also acceptable to use.
line_width	optionally specify how thick to make the lines. Acceptable input is a number; the default is 1 for most lines and 0.8 for some, to give you an idea of where to start.
hline_position	numerical position(s) of any horizontal lines to add to the graph. The default is NA to have no lines, and good syntax if you do want lines would be, for example, hline_position = 10 to have a horizontal line at 10 ng/mL (or whatever your concentration units are) or hline_position = c(10, 100, 1000) to have horizontal lines at each of those y values. Examples of where this might be useful would be to indicate a toxicity threshold, a target Cmin, or the lower limit of quantification for the assay used to generate the concentration-time data.
hline_style	the line color and type to use for any horizontal lines that you add to the graph with hline_position. Default is "red dotted", but any combination of 1) a color in R and 2) a named linetype is acceptable. Examples: "red dotted", "blue dashed", or "#FFBE33 longdash". To see all the possible linetypes, type ggpubr::show_line_types() into the console.
vline_position	numerical position(s) of any vertical lines to add to the graph. The default is NA to have no lines, and good syntax if you do want lines would be, for example, vline_position = 12 to have a vertical line at 12 h or vline_position = seq(from = 0, to = 168, by = 24) to have horizontal lines every 24 hours for one week. Examples of where this might be useful would be indicating dosing times or the time at which some other drug was started or stopped.
vline_style	the line color and type to use for any vertical lines that you add to the graph with vline_position. Default is "red dotted", but any combination of 1) a color in R and 2) a named linetype is acceptable. Examples: "red dotted", "blue dashed", or "#FFBE33 longdash". To see all the possible linetypes, type ggpubr::show_line_types() into the console.
legend_position	specify where you want the legend to be. Options are "left", "right", "bottom", "top", or "none" (default) if you don't want one at all.
legend_orientation	optionally specify how the legend entries should be oriented. Options are "vertical" or "horizontal", and, if left as NA, the legend entries will be "vertical" when the legend is on the left or right and "horizontal" when it's on the top or bottom.
legend_label	optionally indicate on the legend whether the perpetrator is an inhibitor, inducer, activator, or suppressor. Input will be used as the label in the legend for the line style and the shape. If left as the default NA when a legend is included and a perpetrator is present, the label in the legend will be "Inhibitor".
prettify_compound_names	TRUE (default), FALSE or a character vector: This is asking whether to make compound names prettier in legend entries and in any Word output files. 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, "perpetrator" and the values are the names you want, e.g., prettify_compound_names = c("perpetrator" = "teeswiftavir", "substrate" = "superstatin"). Please note that "perpetrator" includes all the perpetrators and perpetrator metabolites present, so, if you're setting the perpetrator name, you really should use something like this if you're including perpetrator metabolites: prettify_compound_names = c("perpetrator" = "teeswiftavir and 1-OH-teeswiftavir", "substrate" = "superstatin").
linear_or_log	the type of graph to be returned. Options: "semi-log" y axis is log transformed "linear" no axis transformation "both vertical" (default) both the linear and the semi-log graphs will be returned, and graphs are stacked vertically "both horizontal" both the linear and the semi-log graphs will be returned, and graphs are side by side horizontally "horizontal and vertical" both the linear and the semi-log graphs will be returned, and graphs are side by side horizontally (one graph; file name will end in "- horizontal") and stacked vertically (second graph; file name will end in "- vertical"). This option, which was designed to create the vertically stacked version of a graph for a report and the horizontal, side-by-side version for a presentation, is a bit different from the others since it will return two separate files. In the RStudio "Plots" window, you'll only see the vertically stacked version. Setting fig_height and fig_width will adjust only the dimensions of the horizontal figure; the default values will be used for the vertical one. If you request Word output, only the vertical plot will be saved in Word format; the horizontal plot will be saved as a png file.
graph_labels	TRUE or FALSE for whether to include labels (A, B, C, etc.) for each of the small graphs. (Not applicable if only outputting linear or only semi-log graphs.)
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.
qc_graph	TRUE or FALSE (default) on whether to create a second copy of the graph where the left panel shows the original graph and the right panel shows information about the simulation trial design. This works MUCH faster when you have already used extractExpDetails_mult to get information about how your simulation or simulations were set up and supply that object to the argument existing_exp_details.
existing_exp_details	output from extractExpDetails or extractExpDetails_mult to be used for creating figure headings and captions tailored to the specific simulation when saving to a Word file or for use with qc_graph
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.
name_clinical_study	optionally specify the name(s) of the clinical study or studies for any observed data. This only affects the caption of the graph. For example, specifying name_clinical_study = "101, fed cohort" will result in a figure caption that reads in part "clinical study 101, fed cohort". If you have more than one study, that's fine; we'll take care of stringing them together appropriately. Just list them as a character vector, e.g., name_clinical_study = c("101", "102", "103") will become "clinical studies 101, 102, and 103."
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
subsection_ADAM	SOON TO BE DEPRECATED. We have now added non-ADAM-model tissues to the subtypes of tissues you can extract from Simulator output, so the old "subsection_ADAM" name we had used for which subtype of tissue it was no longer works as well. Please use "Tissue_subtype" instead going forward.
study_design_matches_obs	optionally specify whether the study design for the simulated data matched that of any observed data. This only affects the caption of the graph. If set to TRUE, this assumes that the number of subjects in the clinical study matches the number of subjects per trial in the simulated data.

Value

Output is a ggplot2 graph or two ggplot2 graphs arranged with ggpubr::ggarrange()

Examples

# Load some concentration-time data to play with:
data(LMVct)

ct_plot(ct_dataframe = LMVct)
ct_plot(ct_dataframe = LMVct, figure_type = "percentiles")
ct_plot(ct_dataframe = LMVct)
ct_plot(ct_dataframe = LMVct)

# Perhaps you don't want to show *all* the data but instead want to
# limit the time interval that is graphed. Use `time_range` here:
ct_plot(ct_dataframe = LMVct, time_range = c(0, 24))

# Or you can let it automatically calculate the time frame
# for a given set of doses
ct_plot(ct_dataframe = LMVct
        time_range = "first dose")
ct_plot(ct_dataframe = LMVct,
        time_range = "last dose")

# The default graph may be too busy when Inhibitor 1 is present,
# so you may want to consider only plotting means as an alternative:
ct_plot(ct_dataframe = LMVct,
        figure_type = "means only")

# Add some further options for the look of your graph -- especially useful
# if the default settings are clipping your data.
ct_plot(ct_dataframe = LMVct,
        obs_color = "red",
        line_color = "blue",
        y_axis_limits_log = c(50, 2000),
        pad_x_axis = TRUE,
        legend_label = "Inhibitor")

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