enz_plot: Plots of enzyme abundance changes over time to match...

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

Plots of enzyme abundance changes over time to match Consultancy template

Description

Using simulated enzyme-abundance data generated from running the function extractEnzAbund, make publication-quality graphs that match the consultancy template formatting instructions. For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Enzyme abundance plots/Enzyme-abundance-plot-examples.docx". (Sorry, we are unable to include a link to it here.)

Usage

enz_plot(
  sim_enz_dataframe,
  gut_tissue = "colon",
  figure_type = "means only",
  mean_type = "arithmetic",
  linear_or_log = "linear",
  time_range = NA,
  x_axis_interval = NA,
  x_axis_label = NA,
  pad_x_axis = TRUE,
  pad_y_axis = TRUE,
  y_axis_limits_lin = NA,
  y_axis_limits_log = NA,
  y_axis_label = NA,
  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_label = NA,
  prettify_compound_names = TRUE,
  graph_labels = TRUE,
  graph_title = NA,
  graph_title_size = 14,
  qc_graph = FALSE,
  existing_exp_details = NA,
  return_caption = FALSE,
  save_graph = NA,
  fig_height = 4,
  fig_width = 6
)

Arguments

sim_enz_dataframe	the data.frame of enzyme abundance data obtained from running the function extractEnzAbund. Not quoted.
gut_tissue	Which of the two types of gut tissue would you like to plot? Acceptable options are "colon" (default) or "small intestine". Applicable only when the tissue extracted with extractEnzAbund included gut tissue and ignored in all other cases.
figure_type	type of figure to plot. Options are: "means only" (default) plots a black line for the mean data and, if a perpetrator was modeled, a dashed line for the concentration-time data with Inhibitor 1. "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. "percentiles" 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. "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. "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 = "none". -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.
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. specific doses If you would like to plot a specific dose number for "time_range" similar to how you would for ct_plot, you must also specify which compound's dose number you want, e.g., time_range = "dose 1 substrate" or time_range = "last dose inhibitor 1" or even time_range = "doses 4 to 6 substrate".
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
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.
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.
y_axis_label	optionally supply a character vector or an expression to use for the y axis label
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 = 100 to have a horizontal line at 100 percent of the baseline enzyme abundance or hline_position = c(50, 100, 200) to have horizontal lines at each of those y values.
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_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 name is "perpetrator" and the value is the name you want, e.g., prettify_compound_names = c("perpetrator" = "teeswiftavir"). 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").
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
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.
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

Value

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

Examples

enz_plot(sim_enz_dataframe = CYP3A4_liver)
enz_plot(sim_enz_dataframe = CYP3A4_gut, legend_position = "right")
enz_plot(sim_enz_dataframe = CYP3A4_gut,
         gut_tissue = "small intestine",
         figure_type = "percentile ribbon",
         legend_position = "right")

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