R/pksummary_table.R
In shirewoman2/Consultancy: Standardized tools for using R within the Simcyp Consultancy Team
Defines functions
pksummary_table
Documented in
pksummary_table
#' Make a summary PK table for a report or slide deck - THIS FUNCTION HAS BEEN
#' DEPRECATED IN FAVOR OF THE FUNCTION pk_table.
#'
#'
#' @param sim_data_file a simulator output file. If you supplied a file name in
#' a data.frame of observed PK or a csv or Excel file of observed PK for
#' \code{observed_PK}, that file name will be used preferentially and you can
#' leave this blank. Similarly, if you supply a filled-out report input form
#' to the argument \code{report_input_file}, the file name you supplied
#' \emph{there} will be used preferentially, and you can leave this blank.
#' @param report_input_file (optional) This argument is an alternative way to
#' specify both what simulator Excel file to use and also what the observed PK
#' parameters were. Input is the name of the Excel file created by running
#' \code{\link{generateReportInputForm}}, which you have now filled out,
#' including the path if it's in any other directory than the current one.
#' Please see the "Details" section at the bottom for more information on this
#' option.
#' @param sheet_report the sheet in the Excel report file that contains
#' information about the study, e.g., "study info - DDI" or "study info - no
#' DDI" if you haven't renamed the tab. This only applies if you have supplied
#' an Excel file name for \code{report_input_file}. If you're supplying a
#' simulator output Excel file for \code{sim_data_file}, ignore this.
#' @param PKparameters (optional) the PK parameters to include as a character
#' vector. \itemize{
#'
#' \item{By default, if you have a single-dose simulation, the parameters will
#' include AUC and Cmax for dose 1, and, if you have a multiple-dose
#' simulation, AUC and Cmax for the last dose. Also by default, if you have an
#' perpetrator present, the parameters will include the AUC and Cmax values with
#' and without the perpetrator as well as those ratios.}
#'
#' \item{Alternatively, you can specify a vector of any combination of
#' specific, individual parameters, e.g., \code{c("Cmax_dose1",
#' "AUCtau_last").} Be sure to encapsulate the parameters you want with
#' \code{c(...)}. To see the full set of possible parameters to extract, enter
#' \code{view(PKParameterDefinitions)} into the console.}
#'
#' \item{If you would like PK pulled from a specific custom interval, please
#' supply a named character vector where the names are the PK parameters and the
#' values are the tabs. Example: \code{sheet_PKparameters = c("AUCinf_dose1" =
#' NA, "AUCt" = "Int AUC userT(1)(Sub)(CPlasma)", "AUCtau_last" = NA)}
#' \strong{Please note that the PK parameters that are for either dose 1 or the
#' last dose must have NA listed for the tab.} Another note: The code will
#' work best if any PK parameters for a custom interval do not have
#' a suffix indicating the dose number. Good: "AUCt". Bad: "AUCtau_last".
#' This is because we do not know
#' which dose number a custom interval is. This also helps use make sure that
#' each PK parameter has only one value so that it's clear which PK data are
#' being described. It is ok to supply this named
#' character vector to the argument \code{sheet_PKparameters} instead, but please do
#' not supply it to both.}
#'
#' \item{If you supply observed data using either the argument
#' \code{report_input_file} or the argument \code{observed_PK}, those PK
#' parameters will be included automatically.}
#'
#' \item{Parameters that don't make sense for your scenario -- such as asking
#' for \code{AUCinf_dose1_withInhib} when your simulation did not include an
#' inhibitor or perpetrator -- will not be included.}
#'
#' \item{tmax will be listed as median, minimum, and maximum rather than mean,
#' lower and higher 90\% confidence interval or 5th to 95th percentiles.
#' Similarly, if you request trial means, the values for tmax will be the
#' range of medians for the trials rather than the range of means.}}
#'
#' An example of acceptable input here: \code{PKparameters = c("AUCtau_last",
#' "AUCtau_last_withInhib", "Cmax_last", "Cmax_last_withInhib",
#' "AUCtau_ratio_last", "Cmax_ratio_last")}.
#' @param PKorder Would you like the order of the PK parameters to be the order
#' specified in the Consultancy Report Template (default), or would you like
#' the order to match the order you specified with the argument
#' \code{PKparameters}? Options are "default" or "user specified".
#' @param sheet_PKparameters (optional) If you want the PK parameters to be
#' pulled from a specific tab in the simulator output file, list that tab
#' here. Otherwise, this should be left as NA. If you want some parameters
#' from a custom-interval tab and others from the regular tabs, please supply
#' a named character vector where the names are the PK parameters and the
#' values are the tabs. Example: \code{sheet_PKparameters = c("AUCinf_dose1" =
#' NA, "AUCt" = "Int AUC userT(1)(Sub)(CPlasma)", "AUCtau_last" = NA)}
#' \itemize{\item{\strong{Please note that PK parameters that are for either dose 1 or the
#' last dose should have NA listed for the tab.}} \item{Another note: The code will
#' work best if any PK parameters for a custom interval do not have
#' a suffix indicating the dose number. Good: "AUCt". Bad: "AUCtau_last".
#' This is because we do not know
#' which dose number a custom interval is. This also helps use make sure that
#' each PK parameter has only one value so that it's clear which PK data are
#' being described.}
#' \item{It is ok to supply this named
#' character vector to the argument \code{PKparameters} instead, but please do
#' not supply it to both.}}
#' @param tissue For which tissue would you like the PK parameters to be pulled?
#' Options are "plasma" (default), "unbound plasma", "blood", "unbound blood",
#' "peripheral plasma", or "peripheral blood". \strong{NOTE: PK for peripheral
#' sampling is not as well tested as for other tissues and is only set up for
#' V21+. Please check your results carefully.}
#' @param compoundToExtract For which compound do you want to extract PK data?
#' Options are: \itemize{\item{"substrate" (default),} \item{"primary
#' metabolite 1",} \item{"primary metabolite 2",} \item{"secondary
#' metabolite",} \item{"inhibitor 1" -- this can be an inducer, inhibitor,
#' activator, or suppresesor, but it's labeled as "Inhibitor 1" in the
#' simulator,} \item{"inhibitor 2" for the 2nd inhibitor listed in the
#' simulation,} \item{"inhibitor 1 metabolite" for the primary metabolite of
#' inhibitor 1}}
#' @param observed_PK (optional) If you have a data.frame, a named numeric
#' vector, or an xlsx or csv file with observed PK parameters, supply the full
#' file name in quotes or the data.frame or vector here, and the
#' simulated-to-observed mean ratios will be calculated. If you supply an xlsx
#' file, it \emph{must} have a tab titled "observed PK", which is what will be
#' read. The supplied data.frame or file can be long (one column named
#' "PKparameter", one column named "Value", and optionally a column called
#' "CV") or it can be wide (one column for each PK parameter). Whether it's
#' long or wide, the PK parameters you list \emph{must} be among the PK
#' parameter options listed in \code{PKParameterDefinitions}. If you would
#' like the output table to include the observed data CV for any of the
#' parameters and you've got your data in a wide format (one column per
#' parameter), add "_CV" to the end of the parameter name, e.g.,
#' "AUCinf_dose1_CV". Please see the "Example" section of this help file for
#' examples of how to set this up.
#' @param existing_exp_details If you have already run
#' \code{\link{extractExpDetails_mult}} or \code{\link{extractExpDetails}} to
#' get all the details from the "Input Sheet" (e.g., when you ran
#' extractExpDetails you said \code{exp_details = "Input Sheet"} or
#' \code{exp_details = "all"}), you can save some processing time by supplying
#' that object here, unquoted. If left as NA, this function will run
#' \code{extractExpDetails} behind the scenes to figure out some information
#' about your experimental set up.
#' @param mean_type What kind of means and CVs do you want listed in the output
#' table? Options are "arithmetic", "geometric" (default), or "arithmetic for
#' most, geometric for ratios". If you supplied a report input form, only
#' specify this if you'd like to override the value listed there.
#' @param use_median_for_tmax TRUE (default) or FALSE for whether to use median
#' for tmax values, regardless of what the other summary statistics are. This
#' is typically the case, but, if you've got client data where they actually
#' gave you tmax using the same summary statistic as the other PK parameters
#' (like geometric mean, for example), then set this to FALSE and whatever
#' mean type you specified with the argument \code{mean_type} will also be
#' used for tmax.
#' @param includeTrialMeans TRUE or FALSE (default) for whether to include the
#' range of trial means for a given parameter. Note: This is calculated from
#' individual values rather than being pulled directly from the output.
#' @param includeCV TRUE (default) or FALSE for whether to include rows for CV
#' in the table
#' @param includeSD TRUE or FALSE (default) for whether to include rows for the
#' standard deviation in the table
#' @param includeMedian TRUE or FALSE (default) for whether to include rows for
#' the median in the table
#' @param includeConfInt TRUE (default) or FALSE for whether to include whatever
#' confidence intervals were included in the simulator output file. Note that
#' the confidence intervals are geometric since that's what the simulator
#' outputs (see an AUC tab and the summary statistics; these values are the
#' ones for, e.g., "90\% confidence interval around the geometric mean(lower
#' limit)").
#' @param includePerc TRUE or FALSE (default) for whether to include the 5th to
#' 95th percentiles
#' @param includeRange TRUE or FALSE (default) for whether to include the
#' minimum and maximum values
#' @param concatVariability TRUE or FALSE (default) for whether to concatenate
#' the variability. If "TRUE", the output will be formatted into a single row
#' and listed as the lower confidence interval or percentile to the upper CI
#' or percentile, e.g., "2400 to 2700". Please note that the current
#' SimcypConsultancy template lists one row for each of the upper and lower
#' values, so this should be set to FALSE for official reports.
#' @param variability_format formatting used to indicate the variability when
#' the variability is concatenated. Options are "to" (default) to get output
#' like "X to Y", "hyphen" to get output like "X - Y", "brackets" to get
#' output like "[X, Y]", or "parentheses" for the eponymous symbol if you're
#' an American and a bracket if you're British, e.g., "(X, Y)". (Sorry for the
#' ambiguity; this was written by an American who didn't originally realize
#' that there was another name for parentheses.)
#' @param 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.
#' @param rounding option for what rounding to perform, if any. Options are:
#' \describe{\item{NA or "Consultancy"}{All output will be rounded according
#' to Simcyp Consultancy Team standards: to three significant figures when the
#' value is < 100 or to the ones place if the value is >= 100. Please see the
#' function \code{\link{round_consultancy}}, which does the rounding here.}
#' \item{"none"}{No rounding will be performed.} \item{"significant X" where
#' "X" is a number}{Output will be rounded to X significant figures. "signif
#' X" also works fine.} \item{"round X" where "X" is a number}{Output will be
#' rounded to X digits} \item{"Word only"}{Output saved to Word or a csv file
#' will be rounded using the function \code{\link{round_consultancy}}, but
#' nothing will be rounded in the output R object. This can be useful when you
#' want to have nicely rounded and formatted output in a Word file but you
#' \emph{also} want to use the results from \code{pksummary_table} to make
#' forest plots, which requires numbers that are \emph{not} rounded.}}
#' @param convert_conc_units Would you like to convert the units to something
#' other than what was used in the simulation? Default is NA to leave the
#' units as is, but if you set the concentration units to something else, this
#' will attempt to convert the units to match that. This only adjusts only the
#' simulated values, since we're assuming that that's the most likely problem
#' and that observed units are relatively easy to fix, and it also only
#' affects AUC and Cmax values. Acceptable input is any concentration unit
#' listed in the Excel form for PE data entry, e.g. \code{convert_conc_units =
#' "ng/mL"} or \code{convert_conc_units = "uM"}. Molar concentrations will be
#' automatically converted using the molecular weight of whatever you set for
#' \code{compoundToExtract}.
#' @param prettify_columns TRUE (default) or FALSE for whether to make easily
#' human-readable column names. TRUE makes pretty column names such as "Dose 1
#' AUCinf (h*ng/mL)" whereas FALSE leaves the column with the R-friendly name
#' from \code{\link{extractPK}}, e.g., "AUCinf_dose1".
#' @param prettify_compound_names TRUE (default) or FALSE on whether to make
#' compound names prettier in the prettified column titles 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 \code{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". Set each compound to the name
#' you'd prefer to see in your column titles if you would like something
#' different. For example, \code{prettify_compound_names = c("perpetrator" =
#' "teeswiftavir", "substrate" = "superstatin")}. Please note that "perpetrator"
#' includes \emph{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: \code{prettify_compound_names =
#' c("perpetrator" = "teeswiftavir and 1-OH-teeswiftavir", "substrate" =
#' "superstatin")}.
#' @param extract_forest_data TRUE or FALSE (default) to get forest-plot data at
#' the same time. This only applies when the compound to extract is the
#' substrate or a substrate metabolite. If set to TRUE, this will return a
#' list that includes data formatted for use with the function
#' \code{\link{forest_plot}}. Since the \code{\link{forest_plot}} function
#' only works with simulations with perpetrators (at least, for now), this
#' will only work for simulations that included a perpetrator. This is
#' probably most useful for the \code{\link{pksummary_mult}} function since a
#' forest plot with only one simulation isn't terribly informative.
#' @param checkDataSource TRUE (default) or FALSE for whether to include in the
#' output a data.frame that lists exactly where the data were pulled from the
#' simulator output file. Useful for QCing.
#' @param save_table optionally save the output table and, if requested, the QC
#' info, by supplying a file name in quotes here, e.g., "My nicely formatted
#' table.docx" or "My table.csv", depending on whether you'd prefer to have
#' the main PK table saved as a Word or csv file. Do not include any slashes,
#' dollar signs, or periods in the file name. (If you assign the output of
#' \code{pksummary_table} to an R object, you can also save the table later to
#' a Word file with the function \code{\link{formatTable_Simcyp}}.) If you
#' supply only the file extension, e.g., \code{save_table = "docx"}, the name
#' of the file will be the file name plus "PK summary table" with that
#' extension, and the output file will be located in the same folder as
#' \code{sim_data_file}. If you supply something other than just "docx" or
#' just "csv" for the file name but you leave off the file extension, we'll
#' assume you want it to be ".csv". While the main PK table data will be in
#' whatever file format you requested, if you set \code{checkDataSource =
#' TRUE}, the QC data will be in a csv file on its own and will have "- QC"
#' added to the end of the file name.
#' @param fontsize the numeric font size for Word output. Default is 11 point.
#' This only applies when you save the table as a Word file.
#' @param highlight_gmr_colors optionally specify a set of colors to use for
#' highlighting geometric mean ratios for DDIs. Options are "yellow to red",
#' "green to red" or a vector of 4 colors of your choosing. If left as NA, no
#' highlighting for GMR level will be done.
#' @param highlight_so_cutoffs optionally specify cutoffs for highlighting any
#' simulated-to-observed ratios. Anything that is above those values or below
#' the inverse of those values will be highlighted. To figure out what cells
#' to highlight, this looks for a column titled "Statistic" or "Stat", then
#' looks for what row contains "S/O" or "simulated (something something)
#' observed" (as in, we'll use some wildcards to try to match your specific
#' text). Next, it looks for any values in that same row that are above those
#' cutoffs. This overrides anything else you specified for highlighting. The
#' default is NA, for \emph{not} highlighting based on S/O value. Acceptable
#' input for, say, highlighting values that are > 125\% or < 80\% of the
#' observed and also, with a second color, values that are > 150\% or < 66\%
#' would be: \code{highlight_so_cutoffs = c(1.25, 1.5)}. If you would like the
#' middle range of values to be highlighted, include 1 in your cutoffs. For
#' example, say you would like everything that's < 80\% or > 125\% to be
#' highlighted red but you'd like the "good" values from 80\% to 125\% to be
#' green, you can get that by specifying
#' \code{highlight_so_cutoffs = c(1, 1.25)} and \code{highlight_so_colors =
#' c("green", "red")}. This only applies when you save the table as a Word file.
#' @param highlight_so_colors optionally specify a set of colors to use in the
#' Word file output for highlighting S/O values outside the limits you
#' specified with \code{highlight_so_cutoffs}. Options: \describe{
#'
#' \item{"yellow to red" (default)}{A range of light yellow to light orange to
#' light red. If you have included 1 in your cutoffs and you leave
#' \code{highlight_so_colors} with the default setting, values in the middle,
#' "good" range of S/O values will be highlighted a light green.}
#'
#' \item{"traffic"}{light green, yellow, and red designed to display values
#' outside 1.25, 1.5, and 2 fold of unity, respectively. If you include 1 in
#' \code{highlight_so_cutoffs}, you'll get a darker green for "good" S/O
#' values. This color scheme was borrowed from Lisa, so if you've seen her
#' slides, these will look familiar.}
#'
#' \item{a character vector of specific colors}{Any R-acceptable colors, will
#' work here, e.g., \code{highlight_so_colors = c("yellow", "orange", "red")}}
#' If you do specify your own bespoke colors, you'll need to make sure that
#' you supply one color for every value in \code{highlight_so_cutoffs}.}
#' @param return_PK_pulled TRUE or FALSE (default) for whether to return as a
#' list item what PK parameters were pulled. This is used internally for
#' writing table headings later.
#' @param add_header_for_DDI TRUE (default) or FALSE for whether to add an extra
#' header row to the top of your table denoting when the PK are for baseline,
#' with a perpetrator, or are the geometric mean ratios.
#' @param page_orientation set the page orientation for the Word file output to
#' "portrait" (default) or "landscape"
#'
#' @return Returns a data.frame of PK summary data and, if observed data were
#' provided, simulated-to-observed ratios. If \code{checkDataSource = TRUE},
#' output will instead be a list of that data.frame (named "Table") and
#' information on where the values came from for QCing (named "QC").
#' @export
#' @examples
#' pksummary_table("abc1a-5mg-qd.xlsx")
#'
#' pksummary_table(report_input_file = "My report input - project abc-1a.xlsx",
#' sheet_report = "study info - Clinical study 001A",
#' includeTrialMeans = TRUE)
#'
#' # An example of how to format observed data as a data.frame:
#' pksummary_table(sim_data_file = "My simulated data.xlsx",
#' observed_PK = data.frame(AUCinf_dose1 = 60,
#' AUCinf_dose1_CV = 0.38,
#' Cmax_dose1 = 22,
#' Cmax_dose1_CV = 0.24))
#'
#' # Or you can supply a named numeric vector:
#' pksummary_table(sim_data_file = "My simulated data.xlsx",
#' observed_PK = c("AUCinf_dose1" = 60,
#' "AUCinf_dose1_CV" = 0.38,
#' "Cmax_dose1" = 22,
#' "Cmax_dose1_CV" = 0.24))
#'
#' # Or an Excel or csv file:
#' pksummary_table(sim_data_file = "mdz-5mg-sd.xlsx",
#' observed_PK = "mdz observed PK.csv")
#'
pksummary_table <- function(sim_data_file = NA,
compoundToExtract = "substrate",
tissue = "plasma",
PKparameters = NA,
PKorder = "default",
sheet_PKparameters = NA,
observed_PK = NA,
existing_exp_details = NA,
report_input_file = NA,
sheet_report = NA,
mean_type = NA,
use_median_for_tmax = TRUE,
includeCV = TRUE,
includeSD = FALSE,
includeConfInt = TRUE,
includeMedian = FALSE,
includeRange = FALSE,
includePerc = FALSE,
includeTrialMeans = FALSE,
concatVariability = FALSE,
variability_format = "to",
convert_conc_units = NA,
include_dose_num = NA,
add_header_for_DDI = TRUE,
rounding = NA,
prettify_columns = TRUE,
prettify_compound_names = TRUE,
extract_forest_data = FALSE,
checkDataSource = TRUE,
return_PK_pulled = FALSE,
highlight_gmr_colors = NA,
highlight_so_cutoffs = NA,
highlight_so_colors = "yellow to red",
save_table = NA,
page_orientation = "portrait",
fontsize = 11,
adjust_conc_units = NA){
stop(wrapn("Our apologies, but the functions pksummary_table and pksummary_mult have been deprecated in favor of the function pk_table. Please switch to pk_table, which is similar but, for various arcane reasons, works better and is easier to manage code-wise than pksummary_table."))
}
shirewoman2/Consultancy documentation built on Feb. 18, 2025, 10 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Defines functions pksummary_table
Documented in pksummary_table
#' Make a summary PK table for a report or slide deck - THIS FUNCTION HAS BEEN
#' DEPRECATED IN FAVOR OF THE FUNCTION pk_table.
#'
#'
#' @param sim_data_file a simulator output file. If you supplied a file name in
#' a data.frame of observed PK or a csv or Excel file of observed PK for
#' \code{observed_PK}, that file name will be used preferentially and you can
#' leave this blank. Similarly, if you supply a filled-out report input form
#' to the argument \code{report_input_file}, the file name you supplied
#' \emph{there} will be used preferentially, and you can leave this blank.
#' @param report_input_file (optional) This argument is an alternative way to
#' specify both what simulator Excel file to use and also what the observed PK
#' parameters were. Input is the name of the Excel file created by running
#' \code{\link{generateReportInputForm}}, which you have now filled out,
#' including the path if it's in any other directory than the current one.
#' Please see the "Details" section at the bottom for more information on this
#' option.
#' @param sheet_report the sheet in the Excel report file that contains
#' information about the study, e.g., "study info - DDI" or "study info - no
#' DDI" if you haven't renamed the tab. This only applies if you have supplied
#' an Excel file name for \code{report_input_file}. If you're supplying a
#' simulator output Excel file for \code{sim_data_file}, ignore this.
#' @param PKparameters (optional) the PK parameters to include as a character
#' vector. \itemize{
#'
#' \item{By default, if you have a single-dose simulation, the parameters will
#' include AUC and Cmax for dose 1, and, if you have a multiple-dose
#' simulation, AUC and Cmax for the last dose. Also by default, if you have an
#' perpetrator present, the parameters will include the AUC and Cmax values with
#' and without the perpetrator as well as those ratios.}
#'
#' \item{Alternatively, you can specify a vector of any combination of
#' specific, individual parameters, e.g., \code{c("Cmax_dose1",
#' "AUCtau_last").} Be sure to encapsulate the parameters you want with
#' \code{c(...)}. To see the full set of possible parameters to extract, enter
#' \code{view(PKParameterDefinitions)} into the console.}
#'
#' \item{If you would like PK pulled from a specific custom interval, please
#' supply a named character vector where the names are the PK parameters and the
#' values are the tabs. Example: \code{sheet_PKparameters = c("AUCinf_dose1" =
#' NA, "AUCt" = "Int AUC userT(1)(Sub)(CPlasma)", "AUCtau_last" = NA)}
#' \strong{Please note that the PK parameters that are for either dose 1 or the
#' last dose must have NA listed for the tab.} Another note: The code will
#' work best if any PK parameters for a custom interval do not have
#' a suffix indicating the dose number. Good: "AUCt". Bad: "AUCtau_last".
#' This is because we do not know
#' which dose number a custom interval is. This also helps use make sure that
#' each PK parameter has only one value so that it's clear which PK data are
#' being described. It is ok to supply this named
#' character vector to the argument \code{sheet_PKparameters} instead, but please do
#' not supply it to both.}
#'
#' \item{If you supply observed data using either the argument
#' \code{report_input_file} or the argument \code{observed_PK}, those PK
#' parameters will be included automatically.}
#'
#' \item{Parameters that don't make sense for your scenario -- such as asking
#' for \code{AUCinf_dose1_withInhib} when your simulation did not include an
#' inhibitor or perpetrator -- will not be included.}
#'
#' \item{tmax will be listed as median, minimum, and maximum rather than mean,
#' lower and higher 90\% confidence interval or 5th to 95th percentiles.
#' Similarly, if you request trial means, the values for tmax will be the
#' range of medians for the trials rather than the range of means.}}
#'
#' An example of acceptable input here: \code{PKparameters = c("AUCtau_last",
#' "AUCtau_last_withInhib", "Cmax_last", "Cmax_last_withInhib",
#' "AUCtau_ratio_last", "Cmax_ratio_last")}.
#' @param PKorder Would you like the order of the PK parameters to be the order
#' specified in the Consultancy Report Template (default), or would you like
#' the order to match the order you specified with the argument
#' \code{PKparameters}? Options are "default" or "user specified".
#' @param sheet_PKparameters (optional) If you want the PK parameters to be
#' pulled from a specific tab in the simulator output file, list that tab
#' here. Otherwise, this should be left as NA. If you want some parameters
#' from a custom-interval tab and others from the regular tabs, please supply
#' a named character vector where the names are the PK parameters and the
#' values are the tabs. Example: \code{sheet_PKparameters = c("AUCinf_dose1" =
#' NA, "AUCt" = "Int AUC userT(1)(Sub)(CPlasma)", "AUCtau_last" = NA)}
#' \itemize{\item{\strong{Please note that PK parameters that are for either dose 1 or the
#' last dose should have NA listed for the tab.}} \item{Another note: The code will
#' work best if any PK parameters for a custom interval do not have
#' a suffix indicating the dose number. Good: "AUCt". Bad: "AUCtau_last".
#' This is because we do not know
#' which dose number a custom interval is. This also helps use make sure that
#' each PK parameter has only one value so that it's clear which PK data are
#' being described.}
#' \item{It is ok to supply this named
#' character vector to the argument \code{PKparameters} instead, but please do
#' not supply it to both.}}
#' @param tissue For which tissue would you like the PK parameters to be pulled?
#' Options are "plasma" (default), "unbound plasma", "blood", "unbound blood",
#' "peripheral plasma", or "peripheral blood". \strong{NOTE: PK for peripheral
#' sampling is not as well tested as for other tissues and is only set up for
#' V21+. Please check your results carefully.}
#' @param compoundToExtract For which compound do you want to extract PK data?
#' Options are: \itemize{\item{"substrate" (default),} \item{"primary
#' metabolite 1",} \item{"primary metabolite 2",} \item{"secondary
#' metabolite",} \item{"inhibitor 1" -- this can be an inducer, inhibitor,
#' activator, or suppresesor, but it's labeled as "Inhibitor 1" in the
#' simulator,} \item{"inhibitor 2" for the 2nd inhibitor listed in the
#' simulation,} \item{"inhibitor 1 metabolite" for the primary metabolite of
#' inhibitor 1}}
#' @param observed_PK (optional) If you have a data.frame, a named numeric
#' vector, or an xlsx or csv file with observed PK parameters, supply the full
#' file name in quotes or the data.frame or vector here, and the
#' simulated-to-observed mean ratios will be calculated. If you supply an xlsx
#' file, it \emph{must} have a tab titled "observed PK", which is what will be
#' read. The supplied data.frame or file can be long (one column named
#' "PKparameter", one column named "Value", and optionally a column called
#' "CV") or it can be wide (one column for each PK parameter). Whether it's
#' long or wide, the PK parameters you list \emph{must} be among the PK
#' parameter options listed in \code{PKParameterDefinitions}. If you would
#' like the output table to include the observed data CV for any of the
#' parameters and you've got your data in a wide format (one column per
#' parameter), add "_CV" to the end of the parameter name, e.g.,
#' "AUCinf_dose1_CV". Please see the "Example" section of this help file for
#' examples of how to set this up.
#' @param existing_exp_details If you have already run
#' \code{\link{extractExpDetails_mult}} or \code{\link{extractExpDetails}} to
#' get all the details from the "Input Sheet" (e.g., when you ran
#' extractExpDetails you said \code{exp_details = "Input Sheet"} or
#' \code{exp_details = "all"}), you can save some processing time by supplying
#' that object here, unquoted. If left as NA, this function will run
#' \code{extractExpDetails} behind the scenes to figure out some information
#' about your experimental set up.
#' @param mean_type What kind of means and CVs do you want listed in the output
#' table? Options are "arithmetic", "geometric" (default), or "arithmetic for
#' most, geometric for ratios". If you supplied a report input form, only
#' specify this if you'd like to override the value listed there.
#' @param use_median_for_tmax TRUE (default) or FALSE for whether to use median
#' for tmax values, regardless of what the other summary statistics are. This
#' is typically the case, but, if you've got client data where they actually
#' gave you tmax using the same summary statistic as the other PK parameters
#' (like geometric mean, for example), then set this to FALSE and whatever
#' mean type you specified with the argument \code{mean_type} will also be
#' used for tmax.
#' @param includeTrialMeans TRUE or FALSE (default) for whether to include the
#' range of trial means for a given parameter. Note: This is calculated from
#' individual values rather than being pulled directly from the output.
#' @param includeCV TRUE (default) or FALSE for whether to include rows for CV
#' in the table
#' @param includeSD TRUE or FALSE (default) for whether to include rows for the
#' standard deviation in the table
#' @param includeMedian TRUE or FALSE (default) for whether to include rows for
#' the median in the table
#' @param includeConfInt TRUE (default) or FALSE for whether to include whatever
#' confidence intervals were included in the simulator output file. Note that
#' the confidence intervals are geometric since that's what the simulator
#' outputs (see an AUC tab and the summary statistics; these values are the
#' ones for, e.g., "90\% confidence interval around the geometric mean(lower
#' limit)").
#' @param includePerc TRUE or FALSE (default) for whether to include the 5th to
#' 95th percentiles
#' @param includeRange TRUE or FALSE (default) for whether to include the
#' minimum and maximum values
#' @param concatVariability TRUE or FALSE (default) for whether to concatenate
#' the variability. If "TRUE", the output will be formatted into a single row
#' and listed as the lower confidence interval or percentile to the upper CI
#' or percentile, e.g., "2400 to 2700". Please note that the current
#' SimcypConsultancy template lists one row for each of the upper and lower
#' values, so this should be set to FALSE for official reports.
#' @param variability_format formatting used to indicate the variability when
#' the variability is concatenated. Options are "to" (default) to get output
#' like "X to Y", "hyphen" to get output like "X - Y", "brackets" to get
#' output like "[X, Y]", or "parentheses" for the eponymous symbol if you're
#' an American and a bracket if you're British, e.g., "(X, Y)". (Sorry for the
#' ambiguity; this was written by an American who didn't originally realize
#' that there was another name for parentheses.)
#' @param 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.
#' @param rounding option for what rounding to perform, if any. Options are:
#' \describe{\item{NA or "Consultancy"}{All output will be rounded according
#' to Simcyp Consultancy Team standards: to three significant figures when the
#' value is < 100 or to the ones place if the value is >= 100. Please see the
#' function \code{\link{round_consultancy}}, which does the rounding here.}
#' \item{"none"}{No rounding will be performed.} \item{"significant X" where
#' "X" is a number}{Output will be rounded to X significant figures. "signif
#' X" also works fine.} \item{"round X" where "X" is a number}{Output will be
#' rounded to X digits} \item{"Word only"}{Output saved to Word or a csv file
#' will be rounded using the function \code{\link{round_consultancy}}, but
#' nothing will be rounded in the output R object. This can be useful when you
#' want to have nicely rounded and formatted output in a Word file but you
#' \emph{also} want to use the results from \code{pksummary_table} to make
#' forest plots, which requires numbers that are \emph{not} rounded.}}
#' @param convert_conc_units Would you like to convert the units to something
#' other than what was used in the simulation? Default is NA to leave the
#' units as is, but if you set the concentration units to something else, this
#' will attempt to convert the units to match that. This only adjusts only the
#' simulated values, since we're assuming that that's the most likely problem
#' and that observed units are relatively easy to fix, and it also only
#' affects AUC and Cmax values. Acceptable input is any concentration unit
#' listed in the Excel form for PE data entry, e.g. \code{convert_conc_units =
#' "ng/mL"} or \code{convert_conc_units = "uM"}. Molar concentrations will be
#' automatically converted using the molecular weight of whatever you set for
#' \code{compoundToExtract}.
#' @param prettify_columns TRUE (default) or FALSE for whether to make easily
#' human-readable column names. TRUE makes pretty column names such as "Dose 1
#' AUCinf (h*ng/mL)" whereas FALSE leaves the column with the R-friendly name
#' from \code{\link{extractPK}}, e.g., "AUCinf_dose1".
#' @param prettify_compound_names TRUE (default) or FALSE on whether to make
#' compound names prettier in the prettified column titles 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 \code{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". Set each compound to the name
#' you'd prefer to see in your column titles if you would like something
#' different. For example, \code{prettify_compound_names = c("perpetrator" =
#' "teeswiftavir", "substrate" = "superstatin")}. Please note that "perpetrator"
#' includes \emph{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: \code{prettify_compound_names =
#' c("perpetrator" = "teeswiftavir and 1-OH-teeswiftavir", "substrate" =
#' "superstatin")}.
#' @param extract_forest_data TRUE or FALSE (default) to get forest-plot data at
#' the same time. This only applies when the compound to extract is the
#' substrate or a substrate metabolite. If set to TRUE, this will return a
#' list that includes data formatted for use with the function
#' \code{\link{forest_plot}}. Since the \code{\link{forest_plot}} function
#' only works with simulations with perpetrators (at least, for now), this
#' will only work for simulations that included a perpetrator. This is
#' probably most useful for the \code{\link{pksummary_mult}} function since a
#' forest plot with only one simulation isn't terribly informative.
#' @param checkDataSource TRUE (default) or FALSE for whether to include in the
#' output a data.frame that lists exactly where the data were pulled from the
#' simulator output file. Useful for QCing.
#' @param save_table optionally save the output table and, if requested, the QC
#' info, by supplying a file name in quotes here, e.g., "My nicely formatted
#' table.docx" or "My table.csv", depending on whether you'd prefer to have
#' the main PK table saved as a Word or csv file. Do not include any slashes,
#' dollar signs, or periods in the file name. (If you assign the output of
#' \code{pksummary_table} to an R object, you can also save the table later to
#' a Word file with the function \code{\link{formatTable_Simcyp}}.) If you
#' supply only the file extension, e.g., \code{save_table = "docx"}, the name
#' of the file will be the file name plus "PK summary table" with that
#' extension, and the output file will be located in the same folder as
#' \code{sim_data_file}. If you supply something other than just "docx" or
#' just "csv" for the file name but you leave off the file extension, we'll
#' assume you want it to be ".csv". While the main PK table data will be in
#' whatever file format you requested, if you set \code{checkDataSource =
#' TRUE}, the QC data will be in a csv file on its own and will have "- QC"
#' added to the end of the file name.
#' @param fontsize the numeric font size for Word output. Default is 11 point.
#' This only applies when you save the table as a Word file.
#' @param highlight_gmr_colors optionally specify a set of colors to use for
#' highlighting geometric mean ratios for DDIs. Options are "yellow to red",
#' "green to red" or a vector of 4 colors of your choosing. If left as NA, no
#' highlighting for GMR level will be done.
#' @param highlight_so_cutoffs optionally specify cutoffs for highlighting any
#' simulated-to-observed ratios. Anything that is above those values or below
#' the inverse of those values will be highlighted. To figure out what cells
#' to highlight, this looks for a column titled "Statistic" or "Stat", then
#' looks for what row contains "S/O" or "simulated (something something)
#' observed" (as in, we'll use some wildcards to try to match your specific
#' text). Next, it looks for any values in that same row that are above those
#' cutoffs. This overrides anything else you specified for highlighting. The
#' default is NA, for \emph{not} highlighting based on S/O value. Acceptable
#' input for, say, highlighting values that are > 125\% or < 80\% of the
#' observed and also, with a second color, values that are > 150\% or < 66\%
#' would be: \code{highlight_so_cutoffs = c(1.25, 1.5)}. If you would like the
#' middle range of values to be highlighted, include 1 in your cutoffs. For
#' example, say you would like everything that's < 80\% or > 125\% to be
#' highlighted red but you'd like the "good" values from 80\% to 125\% to be
#' green, you can get that by specifying
#' \code{highlight_so_cutoffs = c(1, 1.25)} and \code{highlight_so_colors =
#' c("green", "red")}. This only applies when you save the table as a Word file.
#' @param highlight_so_colors optionally specify a set of colors to use in the
#' Word file output for highlighting S/O values outside the limits you
#' specified with \code{highlight_so_cutoffs}. Options: \describe{
#'
#' \item{"yellow to red" (default)}{A range of light yellow to light orange to
#' light red. If you have included 1 in your cutoffs and you leave
#' \code{highlight_so_colors} with the default setting, values in the middle,
#' "good" range of S/O values will be highlighted a light green.}
#'
#' \item{"traffic"}{light green, yellow, and red designed to display values
#' outside 1.25, 1.5, and 2 fold of unity, respectively. If you include 1 in
#' \code{highlight_so_cutoffs}, you'll get a darker green for "good" S/O
#' values. This color scheme was borrowed from Lisa, so if you've seen her
#' slides, these will look familiar.}
#'
#' \item{a character vector of specific colors}{Any R-acceptable colors, will
#' work here, e.g., \code{highlight_so_colors = c("yellow", "orange", "red")}}
#' If you do specify your own bespoke colors, you'll need to make sure that
#' you supply one color for every value in \code{highlight_so_cutoffs}.}
#' @param return_PK_pulled TRUE or FALSE (default) for whether to return as a
#' list item what PK parameters were pulled. This is used internally for
#' writing table headings later.
#' @param add_header_for_DDI TRUE (default) or FALSE for whether to add an extra
#' header row to the top of your table denoting when the PK are for baseline,
#' with a perpetrator, or are the geometric mean ratios.
#' @param page_orientation set the page orientation for the Word file output to
#' "portrait" (default) or "landscape"
#'
#' @return Returns a data.frame of PK summary data and, if observed data were
#' provided, simulated-to-observed ratios. If \code{checkDataSource = TRUE},
#' output will instead be a list of that data.frame (named "Table") and
#' information on where the values came from for QCing (named "QC").
#' @export
#' @examples
#' pksummary_table("abc1a-5mg-qd.xlsx")
#'
#' pksummary_table(report_input_file = "My report input - project abc-1a.xlsx",
#' sheet_report = "study info - Clinical study 001A",
#' includeTrialMeans = TRUE)
#'
#' # An example of how to format observed data as a data.frame:
#' pksummary_table(sim_data_file = "My simulated data.xlsx",
#' observed_PK = data.frame(AUCinf_dose1 = 60,
#' AUCinf_dose1_CV = 0.38,
#' Cmax_dose1 = 22,
#' Cmax_dose1_CV = 0.24))
#'
#' # Or you can supply a named numeric vector:
#' pksummary_table(sim_data_file = "My simulated data.xlsx",
#' observed_PK = c("AUCinf_dose1" = 60,
#' "AUCinf_dose1_CV" = 0.38,
#' "Cmax_dose1" = 22,
#' "Cmax_dose1_CV" = 0.24))
#'
#' # Or an Excel or csv file:
#' pksummary_table(sim_data_file = "mdz-5mg-sd.xlsx",
#' observed_PK = "mdz observed PK.csv")
#'
pksummary_table <- function(sim_data_file = NA,
compoundToExtract = "substrate",
tissue = "plasma",
PKparameters = NA,
PKorder = "default",
sheet_PKparameters = NA,
observed_PK = NA,
existing_exp_details = NA,
report_input_file = NA,
sheet_report = NA,
mean_type = NA,
use_median_for_tmax = TRUE,
includeCV = TRUE,
includeSD = FALSE,
includeConfInt = TRUE,
includeMedian = FALSE,
includeRange = FALSE,
includePerc = FALSE,
includeTrialMeans = FALSE,
concatVariability = FALSE,
variability_format = "to",
convert_conc_units = NA,
include_dose_num = NA,
add_header_for_DDI = TRUE,
rounding = NA,
prettify_columns = TRUE,
prettify_compound_names = TRUE,
extract_forest_data = FALSE,
checkDataSource = TRUE,
return_PK_pulled = FALSE,
highlight_gmr_colors = NA,
highlight_so_cutoffs = NA,
highlight_so_colors = "yellow to red",
save_table = NA,
page_orientation = "portrait",
fontsize = 11,
adjust_conc_units = NA){
stop(wrapn("Our apologies, but the functions pksummary_table and pksummary_mult have been deprecated in favor of the function pk_table. Please switch to pk_table, which is similar but, for various arcane reasons, works better and is easier to manage code-wise than pksummary_table."))
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.