View source: R/ct_plot_overlay.R
ct_plot_overlay | R Documentation |
ct_plot_overlay
is meant to be used in conjunction with
extractConcTime_mult
to create a graph with overlaid
concentration-time data for multiple tissues, compounds, or simulations for
easy comparisons. Please see the "Note" section at the bottom of the help
file for a more-detailed overview of what this function is designed to do.
ct_plot_overlay(
ct_dataframe,
obs_to_sim_assignment = NA,
mean_type = "arithmetic",
figure_type = "means only",
linear_or_log = "semi-log",
normalize_by_dose = FALSE,
colorBy_column,
color_labels = NA,
legend_label_color = NA,
color_set = "default",
obs_shape = NA,
obs_color = 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,
linetype_column,
linetype_labels = NA,
linetypes = c("solid", "dashed"),
line_width = NA,
line_transparency = NA,
legend_label_linetype = NA,
facet1_column,
facet1_title = NA,
facet2_column,
facet2_title = NA,
facet_ncol = NA,
facet_nrow = NA,
floating_facet_scale = FALSE,
facet_spacing = NA,
time_range = NA,
x_axis_interval = NA,
x_axis_label = NA,
time_units_to_use = NA,
pad_x_axis = TRUE,
pad_y_axis = TRUE,
y_axis_limits_lin = NA,
y_axis_limits_log = NA,
y_axis_interval = NA,
y_axis_label = NA,
conc_units_to_use = NA,
hline_position = NA,
hline_style = "red dotted",
vline_position = NA,
vline_style = "red dotted",
graph_labels = TRUE,
graph_title = NA,
graph_title_size = 14,
legend_position = NA,
legend_orientation = NA,
border = TRUE,
prettify_compound_names = TRUE,
qc_graph = FALSE,
existing_exp_details = NA,
name_clinical_study = NA,
return_caption = FALSE,
save_graph = NA,
fig_height = 6,
fig_width = 5,
assume_unique = TRUE
)
ct_dataframe |
the input concentration-time data generated by running
the function |
obs_to_sim_assignment |
optionally specify which observed files should
be compared to which simulator files. If left as NA and what you supplied
for |
mean_type |
plot "arithmetic" (default) or "geometric" mean concentrations or "median" concentrations as the main (thickest or only) line for each data set. If this aggregate measure is not available in the simulator output, you'll receive a warning message and we'll plot one that is available. |
figure_type |
the type of figure to plot.
|
linear_or_log |
the type of graph to be returned. Options:
|
normalize_by_dose |
TRUE or FALSE (default) for whether to show dose-normalized concentration-time profiles |
colorBy_column |
(optional) the column in |
color_labels |
optionally specify a character vector for how you'd like
the labels for whatever you choose for |
legend_label_color |
optionally indicate on the legend something
explanatory about what the colors represent. For example, if
|
color_set |
the set of colors to use. Options:
|
obs_shape |
optionally specify what shapes are used to depict observed
data for a) the substrate drug alone and b) the substrate drug in the
presence of a perpetrator. Input should look like this, for example:
|
obs_color |
optionally specify a color to use for observed data if the
color isn't already mapped to a specific column. By default, observed data
will be the same color as whatever else matches those observed data in
|
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_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. |
linetype_column |
the column in |
linetype_labels |
optionally specify a character vector for how you'd
like the labels for whatever you choose for |
linetypes |
the line types to use. Default is "solid" for all lines.
You'll need one line type for each possible value in the column you
specified for |
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. |
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. |
legend_label_linetype |
optionally indicate on the legend something
explanatory about what the line types represent. For example, if
|
facet1_column |
optionally break up the graph into small multiples; this
specifies the first of up to two columns to break up the data by, and the
designated column name should be unquoted, e.g., |
facet1_title |
optionally specify a title to describe facet 1. This is
ignored if |
facet2_column |
optionally break up the graph into small multiples; this
specifies the second of up to two columns to break up the data by, and the
designated column name should be unquoted, e.g., |
facet2_title |
optionally specify a title to describe facet 2. This is
ignored if |
facet_ncol |
optionally specify the number of columns of facetted graphs
you would like to have. This only applies when you have specified a column
for |
facet_nrow |
optionally specify the number of rows of facetted graphs
you would like to have. This only applies when you have specified a column
for |
floating_facet_scale |
TRUE, FALSE (default), "x", "y", or "xy" for whether to allow the axes for each facet of a multi-facetted graph to scale freely to best fit whatever data are present. Default is FALSE, which means that all data will be on the same scale for easy comparison. However, this could mean that some graphs have lines that are hard to see, so you can set this to TRUE to allow the axes to shrink or expand according to what data are present for that facet. If this is set to "x", "y", or "xy", then the scale will only float along that axis. Play around with this to see what we mean. Floating axes comes with a trade-off for the looks of the graphs, though: Setting this to TRUE does mean that your x axis won't automatically have pretty breaks that are sensible for times in hours and that you can't specify intervals or limits for either the x or the y axis. If you're a ggplot2 user, here's what's going on under the hood: If you set
|
facet_spacing |
Optionally set the spacing between facets. If left as
NA, a best-guess as to a reasonable amount of space will be used. Units are
"lines", so try, e.g. |
time_range |
time range to display. Options:
|
x_axis_interval |
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 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 |
pad_y_axis |
optionally add a smidge of padding to the y axis (default
is TRUE, which includes some generally reasonable padding). As with
|
y_axis_limits_lin |
optionally set the Y axis limits for the linear
plot, e.g., |
y_axis_limits_log |
Optionally set the Y axis limits for the semi-log
plot, e.g., |
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
|
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_style |
the line color and type to use for any horizontal lines
that you add to the graph with |
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_style |
the line color and type to use for any vertical lines that
you add to the graph with |
graph_labels |
TRUE (default) 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. |
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. |
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. |
border |
TRUE (default) or FALSE for whether to include a border around each 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
|
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 |
existing_exp_details |
output from |
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 |
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 |
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 partly filled in automatically, although you should check that the text makes sense in light of your exact graph. If you leave off ".png" or ".docx", 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 automatically saved to disk. |
fig_height |
figure height in inches; default is 6 |
fig_width |
figure width in inches; default is 5 |
assume_unique |
TRUE (default) or FALSE for whether to assume that the concentration-time data contain no replicates, which messes things up and will likely cause this function to crash. Why would you want to skip this? Because it can take a LOOOOOOONG time if you have a lot of points. If you're sure your data are unique, set this to TRUE and save a fair amount of processing time to make your graph. If you're not sure what we're talking about here or if you get error messages that aren't terribly clear (which generally means that R wrote them and not your friendly SimcypConsultancy package authors), try setting this to FALSE. |
a ggplot2 graphs or a set of arranged ggplot2 graphs
To make an overlaid graph, the ct_plot_overlay function will ask you to
map specific columns in your source data to aesthetics in your graph, e.g.,
you can color the lines in your data based on which tissue is being graphed
(column in ct_dataframe: Tissue) or set the line type based on whether a
DDI perpetrator drug is present (column in ct_dataframe: Inhibitor) or
break up the graphs into small multiples based on which simulation it is
(column in ct_dataframe: File). When you run this function, two of the
messages you'll see will be "Columns that vary in your data: ..." and
"Graphing aesthetics you've assigned: ..." We set up these messages to try
to let you know what columns in your source data – the object you supplied
for ct_dataframe
– have multiple unique values that might be useful
for mapping aesthetics in your graphs. If you have a problem with your
graphs such as multiple lines that are the same color or multiple lines
that are the same line type and that's not what you expected and it's not
clear why you're getting that graph, this pair of messages is meant to help
you figure out what groups are present in your data and which of them you
have mapped to an aesthetic aspect of your graph.
The faceting arguments may take a little playing around to understand and
will probably be clearest if you're already a ggplot2 user. (This and all
graphing functions in the SimcypConsultancy package use the package ggplot2
to make graphs.) Here's what's going on under the hood with the faceting
arguments: If you set floating_facet_scale = FALSE
, the default,
then ct_plot_overlay
will use facet_grid to break up your graphs and
set facet1_column
to the rows and facet2_column
to the
columns. If you set floating_facet_scale = TRUE
, then
ct_plot_overlay
will use facet_wrap to break up your data and
facet1_column
will be the first variable it uses and
facet2_column
will be the second.
A note reqgarding observed data: There are some nuances to
overlaying observed data. 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 3 - overlaying
plots/Concentration-time-plot-examples-3.docx". (Sorry, we are unable to
include a link to it here.) 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.
data(MDZct)
ct_plot_overlay(ct_dataframe = MDZct, colorBy_column = File)
# Setting the legend labels for color to be more interpretable. Note
# that the order matches the order listed here, not the alphabetical
# order of the files.
ct_plot_overlay(ct_dataframe = MDZct, colorBy_column = File,
color_labels = c("mdz-5mg-sd-fa1.xlsx" = "fa 1",
"mdz-5mg-sd-fa0_8.xlsx" = "fa 0.8",
"mdz-5mg-sd-fa0_6.xlsx" = "fa 0.6",
"mdz-5mg-sd-fa0_4.xlsx" = "fa 0.4"))
# An example of how you might set the column "File" for a specific
# observed data file:
MyData <- MyData %>%
mutate(File = case_when(ObsFile == "ObservedData1.xlsx" ~ "SimFileA.xlsx",
ObsFile == "ObservedData2.xlsx" ~ "SimFileB.xlsx"))
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.