forest_plot | R Documentation |
forest_plot
creates a forest plot of AUC and Cmax ratios
from Simcyp Simulator results. Please use the function
pk_table
with the argument "extract_forest_data" set to TRUE
to generate the simulated input data for forest_dataframe
. This
function will also work with observed data; please see notes for the
argument "observed_PK
" for how to include observed data.
In the graph, data will be broken up on the y axis by the simulation file
name and, optionally, along the x axis by anything you specify for
facet_column_x
. Since file names do not generally make the most
lovely of y axis labels, please use the argument y_axis_labels
to
specify how you'd like your y axis to look. If you're a little
confused here or you're just the kind of person who prefers to wing it
rather than, say, reading the instructions when assembling furniture, we
recommend skipping to the end of this help file and trying out the examples
to see what we mean.
forest_plot(
forest_dataframe,
y_axis_labels,
y_order = NA,
PKparameters = NA,
observed_PK = NA,
use_AUCt_when_AUCinf_NA = FALSE,
include_AUCt_for_AUCinf_caption = TRUE,
facet_column_x,
facet_title_x = NA,
show_numbers_on_right = FALSE,
mean_type = "geometric",
variability_type = "90% CI",
x_axis_limits = NA,
x_axis_title = NA,
x_axis_number_type = "ratios",
x_order = NA,
y_axis_title = "none",
pad_y_axis = TRUE,
legend_position = "none",
color_set = "grays",
point_shape = c(24, 21),
point_color_column,
point_color_set = "default",
angle_x_axis_text = 0,
graph_title = NA,
graph_title_size = 14,
table_title = NA,
rel_widths = c(5, 1),
prettify_ylabel = NA,
PK_labels = NA,
include_dose_num = NA,
include_ratio_in_labels = TRUE,
error_bar_height = NA,
show_borders = TRUE,
vline_at_1 = "gray dashed",
dose_units = "mg",
save_graph = NA,
return_caption = FALSE,
fig_height = 6,
fig_width = 5,
prettify_compound_names = NA
)
forest_dataframe |
a data.frame with extracted forest-plot data,
generated from running
|
y_axis_labels |
a column in |
y_order |
optionally set the order of simulation files on the y axis. If
|
PKparameters |
optionally specify which PK parameters in
|
observed_PK |
observed PK data, with the following columns:
|
use_AUCt_when_AUCinf_NA |
TRUE or FALSE (default) for whether to swap out AUCt for dose 1 when the Simulator failed to extrapolate to infinity. Here's the deal: If you have some simulations with AUCinf for dose 1 and then some where you have AUCt, you'll have both AUCinf and AUCt on the y axis for all the simulations but there will only be points for AUCt for the simulations where extrapolation failed. That makes a graph that's a little redundant and even a little confusing. If you set this to TRUE, we will use AUCt whenever AUCinf wasn't available and we will not include AUCt on the graph. |
include_AUCt_for_AUCinf_caption |
TRUE (default) or FALSE for whether to
include a caption on the forest plot noting which simulations had AUCt used
in place of AUCinf when the Simulator had trouble extrapolating to
infinity. This only applies when |
facet_column_x |
optionally break up the graph horizontally into small
multiples. The designated column name should be unquoted, e.g.,
|
facet_title_x |
title to use for the facet column along the x axis |
show_numbers_on_right |
TRUE or FALSE (default) for whether to show the numbers used for the centre statistic (the point) and any variability (the error bars). This only works when the graph has not been facetted along the x direction. If it's facetted along the x direction, it wouldn't be clear which numbers belonged to which facet. |
mean_type |
type of mean to graph; options are "geometric" (default),
"arithmetic", or "median", but this only works when those data are included
in |
variability_type |
type of variability to show as whiskers; options are "90% CI" (default, geometric), "5th to 95th percentiles", "range", "geometric CV" ("geoCV" or "GCV" are fine), "arithmetic CV" ("CV" is fine), or "standard deviation" ("sd" is also ok for that last one, and it's arithmetic). |
x_axis_limits |
the x axis limits to use; default is 0.06 to 12. |
x_axis_title |
optionally supply a character vector or an expression to use for the x axis title |
x_axis_number_type |
set the x axis number type to be "ratios" (default), "percents" (converts the ratios to a percent), or "keep trailing zeroes" (still uses ratios but, unlike the default, guesses at a reasonable number of digits to include based on the range of the data and includes trailing zeroes as necessary) |
x_order |
optionally specify the order in which the x-axis facets should
appear. For example, if you |
y_axis_title |
optionally specify a vertical title to be displayed to
the left of the y axis. Example: |
pad_y_axis |
optionally add a smidge of padding to the y axis (default is TRUE, which includes some generally reasonable padding). If set to FALSE, the y axis tick marks will be placed closer to the top and bottom of your data. The default amount of padding varies depending on how many PK parameters you're including, but try something in the realm of 0 to 3. |
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. |
color_set |
the set of colors to use for shading the graph background to indicate the level of interaction depicted. Options are:
The cutoff values (1.25, 2, or 5 fold) match those in "Clinical Drug Interaction Studies – Cytochrome P450 Enzyme- and Transporter-Mediated Drug Interactions: Guidance for industry", US Food and Drug Administration Center for Drug Evaluation and Research, 2020, p. 19. |
point_shape |
the shape of the points to show for the center statistic
(e.g., the geometric mean). The default is to show a white triangle for
observed data and a white circle for simulated data, so |
point_color_column |
the unquoted name of a column in
|
point_color_set |
color set to use for points. Options:
|
angle_x_axis_text |
At what angle should the x axis text be printed? Default is 0 degrees for regular, horizontal text. |
graph_title |
optionally specify a title that will be centered across the graph |
graph_title_size |
the font size for the graph title if it's included; default is 14. |
table_title |
if you have included a table of the numbers by setting
|
rel_widths |
specify the relative widths of the graph and the table
(only applies if you included a table on the right side of the graph) as a
numeric vector. The default makes the graph 5x larger than the table, and
acceptable input looks like this: |
prettify_ylabel |
NA (default), TRUE, or FALSE on whether to attempt to
make text included in |
PK_labels |
optionally specify what you would like to have appear on the
y axis for labels for each PK parameter with a named list of expressions,
e.g., |
include_dose_num |
NA (default), TRUE, or FALSE on whether to include the dose number when listing the PK parameter. By default, the parameter will be labeled, e.g., "Dose 1 Cmax ratio" or "Last dose AUCtau ratio", if you have PK data for both the first dose and the last dose. Also by default, if you have data only for the first dose or only for the last dose, the dose number will be omitted and it will be labeled, e.g., "AUCtau ratio" or "Cmax ratio". Set this to TRUE or FALSE as desired to override the default behavior and get exactly what you want. |
include_ratio_in_labels |
TRUE (default) or FALSE on whether to include "ratio" in the labels for the PK parameters. |
error_bar_height |
optionally specify a number for the height of the line at the end of the error bar. If left as NA, it will be set to 0.3. If set to 0, the error bars will be just lines. Try it and you'll see what we mean. |
show_borders |
TRUE (default) or FALSE for whether to show a light gray
line between the files on the y axis. Note: This works best when
|
vline_at_1 |
specify the type of vertical line to show where the ratio =
1; default is to show a gray dashed line, and you can get no line by
specifying |
dose_units |
the units used in dosing, which only applies if you set
|
save_graph |
optionally save the output graph by supplying a file name in quotes here, e.g., "My forest plot.png" or "My forest plot.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. |
return_caption |
TRUE or FALSE (default) for whether to return any caption text to use with the graph. If set to TRUE, you'll get as output a list of the graph, the figure heading, and the figure caption. |
fig_height |
figure height in inches; default is 6 |
fig_width |
figure width in inches; default is 5 |
prettify_compound_names |
SOON TO BE DEPRECATED. This is the same thing as "prettify_ylabel", which we think is more general and thus more accurate at describing what this argument does. |
Output is a graph.
# We'll use some example forest-plot data for the substrate bufuralol
# with various perpetrators. To start, we'll use all the default settings.
forest_plot(forest_dataframe = BufForestData_20mg)
# You can used the argument y_axis_labels to specify what to use for the
# y axis labels instead of the simulation file names. One option: Use a
# named character vector to list the file names and what you want to
# show instead. This can be as verbose as you like, and it's ok to use
# "\n" for a new line if you want.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = c("buf-20mg-sd-fluv-36mg-qd.xlsx" = "fluvoxamine",
"buf-20mg-sd-itra-200mg-qd.xlsx" = "itraconazole",
"buf-20mg-sd-quin-200mg-qd.xlsx" = "quinidine",
"buf-20mg-sd-tic-219mg-bid.xlsx" = "ticlopidine\nSingh et al. 2017 study"))
# Or use a different column in forest_dataframe to specify y_axis_labels.
# Please note that there must be one unique value in y_axis_labels for
# each simulation file.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1)
# By default, the graph will show the strongest inhibitors on top and
# the strongest inducers on the bottom, sorted by their AUC GMR. However,
# if you liked the order you already had things in whatever you supplied
# for forest_dataframe, you can tell the forest_plot function not to change
# that by setting y_order to "as is".
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
y_order = "as is")
# If it would be sensible to break up your graph by a column in
# forest_dataframe, you can do that with the argument facet_column_x. We'll
# switch the example data to some with two dose levels here.
forest_plot(forest_dataframe = BufForestData,
y_axis_labels = Inhibitor1,
facet_column_x = Dose_sub)
# You can add a title to the facets to indicate what they are with
# facet_title_x.
forest_plot(forest_dataframe = BufForestData,
y_axis_labels = Inhibitor1,
facet_column_x = Dose_sub,
facet_title_x = "Dose bufuralol")
# Or you can break up your graph by the PK parameter shown.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
facet_column_x = PKparameter)
# If what you supplied for forest_dataframe includes other statistics,
# you can graph those instead of the default, which is the geometric
# mean (point) and geometric 90 percent confidence interval (error bars).
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
mean_type = "median",
variability_type = "range")
# Here's how to include a table of the numbers used for the centre
# statistic and variability along the right side of the graph.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
legend_position = "bottom",
show_numbers_on_right = TRUE,
color_set = "yellow to red")
# Sometimes, it can take some tweaking to get this to look *just right*, so
# let's specify what we want for the table title and make the table
# proportionately wider compared to the graph.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
legend_position = "bottom",
show_numbers_on_right = TRUE,
table_title = "GMR values",
rel_widths = c(2, 1),
color_set = "yellow to red")
# You can compare observed PK data as long as they are laid out the same
# way as the simulated data. Please see the argument `observed_PK` for
# details, but here's an example.
view(BufObsForestData_20mg)
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
observed_PK = BufObsForestData_20mg)
# If you have some observed PK data that are not matched to specific
# simulated data, you can include them by setting a fake file name in the
# column "File", which should really be thought of as "the set of data that
# comprise one row in the graph". Here's an example:
AddnlObsPK <- bind_rows(BufObsForestData_20mg,
data.frame(File = "Rifampicin obs data", # call it whatever you like
Inhibitor1 = "rifampicin",
PKparameter = c("AUCt_ratio_dose1",
"Cmax_ratio_dose1"),
geomean = c(0.4, 0.5),
CI90_lower = c(0.35, 0.42),
CI90_upper = c(0.45, 0.6)))
forest_plot(forest_dataframe = BufForestData_20mg,
observed_PK = AddnlObsPK,
y_axis_labels = Inhibitor1,
legend_position = "right")
# Here are some options for modifying the aesthetics of your graph:
# -- Add an overall graph title and a y axis title to make it clear that
# we're looking at the effects of various perpetrators on bufuralol PK (at
# least, that's what we're doing in this example).
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
include_dose_num = FALSE,
y_axis_title = "Perpetrator",
graph_title = "Effects of various DDI perpetrator\ndrugs on bufuralol PK")
# -- Adjust the x axis limits with x_axis_limits
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
x_axis_limits = c(0.9, 5))
# -- Include a legend for the shading
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
legend_position = "bottom")
# -- Change the shading to be like in Chen Jones 2022 CPT
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
legend_position = "bottom",
color_set = "yellow to red")
# -- Or specify exactly which colors you want for which interaction level, and
# make the vertical line at 1 be a different color and line type.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
legend_position = "bottom",
color_set = c("negligible" = "white", "weak" = "#C6CDF7",
"moderate" = "#7294D4", strong = "#E6A0C4"),
vline_at_1 = "purple dotted")
# -- Or make the shading disappear and also make the error bars just be lines.
# Also make the error bars lose the hat at either end, and don't show any lines
# in between the files.
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
legend_position = "bottom",
color_set = "none",
show_borders = FALSE,
error_bar_height = 0)
# -- Make the compound names match *exactly* what was in the Simulator file
# rather than being automatically prettified
forest_plot(forest_dataframe = BufForestData_20mg,
y_axis_labels = Inhibitor1,
prettify_ylabel = FALSE)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.