ct_plot3: Concentration-time plots of the full time range, first dose,...

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

Concentration-time plots of the full time range, first dose, and last dose

Description

Conveniently group three concentration-time plots of multiple-dose regimen data together:

1. the full time range across the top,

2. the first dose in the lower left quadrant, and

3. the last dose in the lower right quadrant.

This uses either ct_plot or ct_plot_overlay behind the scenes to make the graphs, so most of the options available for those functions will work here.

Usage

ct_plot3(
  ct_dataframe,
  overlay = FALSE,
  figure_type = "means only",
  mean_type = "arithmetic",
  linear_or_log = "semi-log",
  graph_title_U = "Full time range",
  x_axis_interval_U = NA,
  graph_title_LL = "First dose",
  time_range_LL = "first dose",
  x_axis_interval_LL = NA,
  graph_title_LR = "Last dose",
  time_range_LR = "last dose",
  x_axis_interval_LR = NA,
  legend_position = "none",
  legend_orientation = NA,
  graph_labels = TRUE,
  conc_units_to_use = NA,
  hline_position = NA,
  hline_style = "red dotted",
  vline_position = NA,
  vline_style = "red dotted",
  qc_graph = FALSE,
  existing_exp_details = NA,
  prettify_compound_names = TRUE,
  name_clinical_study = NA,
  return_caption = FALSE,
  save_graph = NA,
  fig_height = 6,
  fig_width = 5,
  ...
)

Arguments

ct_dataframe	the input concentration-time data generated by running either the function extractConcTime or the function extractConcTime_mult
overlay	TRUE or FALSE for whether to make overlaid graphs, i.e., whether to use ct_plot_overlay (TRUE) or use ct_plot (FALSE) to generate the graphs. If you have more than one kind of tissue or more than one simulation file or more than one compound, we'll set this to TRUE automatically.
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: You may sometimes see some artifacts – especially for semi-log plots – where the ribbon gets partly cut off. For arcane reasons we don't want to bore you with here, we can't easily prevent this. However, a possible fix is to set your y axis limits for the semi-log plot to be wider using y_axis_limits_log. "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
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.
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_title_U	graph title for the upper, full-time-range graph; defaults to "Full time range"
x_axis_interval_U	optionally set the upper graph 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.
graph_title_LL	graph title for the lower left graph; defaults to "First dose"
time_range_LL	time range to use for the lower-left graph; defaults to "first dose" but any option acceptable for time_range for the function ct_plot will also work.
x_axis_interval_LL	optionally set the lower left graph 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.
graph_title_LR	graph title for the lower right graph; defaults to "Last dose"
time_range_LR	time range to use for the lower-right graph; defaults to "first dose" but any option acceptable for time_range for the function ct_plot will also work.
x_axis_interval_LR	optionally set the lower right graph 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.
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. If you include the legend but then some graphs do have a legend and some graphs do not (e.g., some have perpetrators and some do not so there's nothing to put in a legend), the alignment between sets of graphs will be a bit off.
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.
graph_labels	TRUE (default) or FALSE for whether to include labels (A, B, C) for each of the small graphs.
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.
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.
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 with qc_graph
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. For example, prettify_compound_names = c("Sim-Ketoconazole-400 mg QD" = "ketoconazole", "Wks-Drug ABC-low_ka" = "Drug ABC") will make those compounds "ketoconazole" and "Drug ABC" in a legend.
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."
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.
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 6
fig_width	figure width in inches; default is 5
...	arguments that pass through to ct_plot or ct_plot_overlay

Value

a set of 3 arranged ggplot2 graphs

Examples

# We'll use the objects LMVct and MDZ_Keto for these examples. They're
# included in the package. 

# Examples with a single compound, tissue, and simulation ----------------------

# These are all graphs where, if you made one of the panels on its own, you
# would use the function ct_plot.

# Simplest option:
ct_plot3(ct_dataframe = LMVct)

# Change the 3 graph titles
ct_plot3(ct_dataframe = LMVct, 
         graph_title_U = "Full time range for letermovir", 
         graph_title_LL = "Dose 1 of letermovir", 
         graph_title_LR = "Dose 8 of letermovir")

# Tweak the time intervals for the bottom row graphs
ct_plot3(ct_dataframe = LMVct, 
         graph_title_LL = "Dose 1 & 2", 
         time_range_LL = "doses 1 to 2", 
         graph_title_LR = "Dose 7 & 8", 
         time_range_LR = "doses 7 to 8")

# Make any other adjustments that you would typically make with ct_plot. 


# Examples with multiple compounds, tissues, and/or simulations overlaid -------

# These are all graphs where, if you made one of the panels on its own, you
# would use the function ct_plot_overlay.
ct_plot3(ct_dataframe = MDZ_Keto %>% 
            filter(CompoundID == "substrate" & 
                      Tissue == "plasma"), 
         overlay = TRUE, colorBy_column = Inhibitor)

# Make any other adjustments that you would typically make with ct_plot_overlay.
# This option might be a bit much! But at least it shows how it would be
# done. :)
ct_plot3(ct_dataframe = MDZ_Keto, 
         overlay = TRUE,
         colorBy_column = Inhibitor, 
         facet1_column = Tissue, 
         facet2_column = Compound)


# You can adjust the graph titles and time ranges the same way as with a single
# simulation.

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