pk_table: Make tables of PK values from Simulator output Excel files

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

Make tables of PK values from Simulator output Excel files

Description

pk_table creates tables of PK parameters for reports and presentations, including reporting means, CVs, and confidence intervals or percentiles and, optionally, comparisons to observed data. This function automatically finds the correct tabs and the correct cells in a Simulator output Excel file to obtain those data. Notes:

• Coding requires having a standardized way to input all the myriad possibilities for PK parameters, which can be tricky. Please try running make_example_PK_input to see examples for how to specify the PK parameters you need.

• For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Making PK tables/PK-tables.docx". (Sorry, we are unable to include a link to it here.)

• In the results, tmax will be listed as median, min, and max rather than mean, lower and higher confidence interval or 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.

• We strongly recommend saving the output to a Word file, which will apply any highlighting you request and some other nice formatting, will not drop trailing zeroes, and will include some text for possible table headings and captions.

Usage

pk_table(
  PKparameters = NA,
  sim_data_files = NA,
  compoundsToExtract = "substrate",
  tissues = "plasma",
  sheet_PKparameters = NA,
  existing_exp_details = NA,
  mean_type = NA,
  use_median_for_tmax = TRUE,
  includeCV = TRUE,
  includeSD = FALSE,
  includeConfInt = TRUE,
  includeMedian = FALSE,
  includeRange = FALSE,
  includePerc = FALSE,
  includeTrialMeans = FALSE,
  concatVariability = TRUE,
  variability_format = "to",
  conc_units = NA,
  include_dose_num = NA,
  PKorder = "default",
  file_order = "as is",
  add_header_for_DDI = TRUE,
  rounding = NA,
  prettify_columns = TRUE,
  prettify_compound_names = TRUE,
  name_clinical_study = NA,
  extract_forest_data = FALSE,
  checkDataSource = FALSE,
  save_table = NA,
  highlight_gmr_colors = NA,
  highlight_so_cutoffs = NA,
  highlight_so_colors = "yellow to red",
  shading_column,
  single_table = TRUE,
  page_orientation = "portrait",
  fontsize = 11,
  return_PK_pulled = FALSE,
  return_caption = FALSE,
  ...,
  convert_conc_units = NA
)

Arguments

PKparameters	the PK parameters to include. There are two main options for this: 1) supply a file to read or a data.frame (R speak for "a table") that lists which simulation files, compounds, tissues, and PK you want or 2) supply a character vector of which PK parameters you want and then also specify what you need in terms of which tissues, which compounds, which simulation files, and which tab to get the data from with the arguments tissues, compoundsToExtract, sim_data_files, and sheet_PKparameters. Details on each option: Option 1: a file to read or a data.frame This is the most versatile option and, we think, the clearest in terms of getting what you expected. Please try running make_example_PK_input to see examples for how to set up a csv or Excel file or data.frame to specify exactly which simulation file should get which PK parameter from which tissue and, when user-specified intervals are involved, from which tab in the Excel file those data should be pulled. Whatever you supply, the columns that will be read are: "File" (same thing as the argument sim_data_files) "Sheet" (same thing as the argument sheet_PKparameters) "Tissue" (same as the argument tissues) "CompoundID" (same as the argument compoundsToExtract) "ObsValue" for any observed data (no equivalent argument) "Variability" for any observed variability (no equivalent argument here, either) If you omit any of those columns, whatever you supply for their respective arguments will be used instead. If you supply something for one of them in the data.frame or file and also something for its argument, the argument will be ignored. Here is how to specify each of the possible inputs for Option 1: a csv file list the file name, including the file extension ".csv" inside quotes, e.g., "PK needed.csv" an Excel file list the file name, including the file extension ".xlsx", inside quotes, e.g., "PK needed.xlsx". We will be looking for a tab titled "PKparameters" (all one word and with the same capitalization). a data.frame If you'd like to supply a data.frame with the same columns you would have had in the .csv or Excel file, that works just the same. Option 2: specify the PK parameters you want for all your simulations This is a good option when you want the same information from all your simulations. List the PK parameters you want here and then, in the arguments tissues, compoundsToExtract, sim_data_files, and sheet_PKparameters specify which of each of those items you want. You'll get all possible combinations of these, so, for example, if you say PKparameters = c("AUCinf_dose1", "Cmax_dose1") and tissues = c("blood", "plasma"), you'll get the dose 1 AUCinf and Cmax for both blood and plasma for all the simulation files you list with sim_data_files. If you're going this route, here are the two options you have for the argument PKparameters: NA If you leave this as NA, by default, if you have a single-dose simulation, the parameters will include AUC and Cmax for dose 1, or, if you have a multiple-dose simulation, AUC and Cmax for the last dose. Also by default, if you have a perpetrator present, the parameters will include the AUC and Cmax values with and without the perpetrator as well as those ratios. a character vector of any combination of specific, individual parameters This character vector must contain SimcypConsultancy package coded names for each parameter you want, e.g., c("Cmax_dose1", "AUCtau_last"). Be sure to encapsulate the parameters you want with c(...). Please try running make_example_PK_input to see examples, or, to see the full set of all possible parameters to extract, enter view(PKParameterDefinitions) into the console. Parameters that don't make sense for your scenario – such as asking for AUCinf_dose1_withInhib when your simulation did not include a perpetrator – will be ignored.
sim_data_files	the Simcyp Simulator output Excel files to use. Options for how to specify these: NA to extract PK data for all the Excel files in the current folder or for all the files listed in what you supply to the argument PKparameters "recursive" to extract PK data for all the Excel files in the current folder and all subfolders. a character vector of simulator output files, each in quotes and encapsulated with c(...) If you do want specific simulations, please take pity on your poor R coders and do not use the same simulation file names in different subfolders; duplicate file names are just too confusing, and we might give you incorrect results.
compoundsToExtract	For which compounds do you want to extract PK data? Options are any combination of the following: "substrate" (default) "primary metabolite 1" "primary metabolite 2" "secondary metabolite" "inhibitor 1" – this can be an inducer, inhibitor, activator, or suppresesor, but it's labeled as "Inhibitor 1" in the simulator "inhibitor 2" for the 2nd inhibitor listed in the simulation "inhibitor 1 metabolite" for the primary metabolite of inhibitor 1 "all" for all possible compounds present in the simulations To specify multiple compounds, enclose the compound IDs with parentheses, e.g., compoundsToExtract = c("substrate", "inhibitor 1"), or, and we recommend this second option instead for clarity, supply them in a data.frame or csv file for the argument PKparameters.
tissues	For which tissue(s) would you like the PK parameters to be pulled? Options are any combination of: "plasma" (default) "unbound plasma" "blood" "unbound blood" "peripheral plasma" "peripheral blood" For multiple tissues, enclose them with parentheses, e.g., tissues = c("blood", "plasma") or, better, do not supply anything here and instead supply which tissue you want for which simulation and which compound, etc. when you supply a data.frame or csv file to the argument PKparameters.
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. sheet_PKparameters can only have a single value, though. If you want some parameters from a custom-interval tab and others from the regular tabs, you must supply that as part of a data.frame or csv file for the argument PKparameters. Please try running make_example_PK_input to see examples for how to do this.
existing_exp_details	If you have already run extractExpDetails_mult to get all the details from the "Input Sheet" (e.g., when you ran extractExpDetails you said exp_details = "Summary and Input" or exp_details = "all"), you can save some processing time by supplying that object here, unquoted. If left as NA, this function will run extractExpDetails behind the scenes anyway to figure out some information about your experimental set up.
mean_type	What kind of means and CVs do you want listed in the output table? Options are "geometric" (default), "arithmetic", or "arithmetic for most, geometric for ratios".
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 mean_type will also be used for tmax.
includeCV	TRUE (default) or FALSE for whether to include rows for CV in the table
includeSD	TRUE or FALSE (default) for whether to include rows for the standard deviation in the table
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)").
includeMedian	TRUE or FALSE (default) for whether to include rows for the median in the table
includeRange	TRUE or FALSE (default) for whether to include the minimum and maximum values
includePerc	TRUE or FALSE (default) for whether to include 5th to 95th percentiles
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.
concatVariability	TRUE (default) or FALSE 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.
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.)
conc_units	What concentration units should be used in the table? 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. If you leave this as NA, the units in the 1st simulation will be used as the units for all the simulations for consistency and clarity. Acceptable input is any concentration unit listed in the Excel form for PE data entry, e.g. conc_units = "ng/mL" or conc_units = "uM". Molar concentrations will be automatically converted using the molecular weight of whatever you set for compoundToExtract.
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.
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 PKparameters? Options are "default" or "user specified".
file_order	order of the simulations in the output table, default is to leave the order "as is", in which case the order will be whatever is specified with sim_data_files.
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.
rounding	option for what rounding to perform, if any. Options are: 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 round_consultancy, which does the rounding here. "none" No rounding will be performed. "significant X" where "X" is a number Output will be rounded to X significant figures. "signif X" also works fine. "round X" where "X" is a number Output will be rounded to X digits "Word only" Output saved to Word or a csv file will be rounded using the function 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 also want to use the results from pksummary_mult to make forest plots, which requires numbers that are not rounded.
prettify_columns	TRUE (default) or FALSE for whether to make easily human-readable column names. TRUE makes pretty column names such as "AUCinf (h*ng/mL)" whereas FALSE leaves the column with the R-friendly name from extractPK, e.g., "AUCinf_dose1".
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 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, prettify_compound_names = c("perpetrator" = "teeswiftavir", "substrate" = "superstatin"). 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", "substrate" = "superstatin").
name_clinical_study	optionally specify the name(s) of the clinical study or studies for any observed data. This only affects the caption of the graph. For example, specifying name_clinical_study = "101, fed cohort" will result in a figure caption that reads in part "clinical study 101, fed cohort". If you have more than one study, that's fine; we'll take care of stringing them together appropriately. Just list them as a character vector, e.g., name_clinical_study = c("101", "102", "103") will become "clinical studies 101, 102, and 103."
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 forest_plot. Since the forest_plot function only works with simulations with perpetrators (at least, for now), this will only work for simulations that included a perpetrator. All PK parameters in any forest data will be for the victim compound listed. The data.frame also includes columns for all the compounds that were included for the simulation, but all PK are for the victim compound listed.
checkDataSource	TRUE or FALSE (default) 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.
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 table saved as a Word or csv file. Do not include any slashes, dollar signs, or periods in the file name. (You can also save the table to a Word file later with the function formatTable_Simcyp.) If you supply only the file extension, e.g., save_table = "docx", the name of the file will be "PK summary table" with that extension. 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". All PK info will be included in a single Word or csv file, and, if checkDataSource = TRUE, that will be saved in a single csv file.
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.
highlight_so_cutoffs	optionally specify cutoffs for highlighting any simulated-to-observed ratios in Word file output. 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 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: 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 highlight_so_cutoffs = c(1, 1.25) and highlight_so_colors = c("green", "red"). This only applies when you save the table as a Word file.
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 highlight_so_cutoffs. Options: "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 highlight_so_colors with the default setting, values in the middle, "good" range of S/O values will be highlighted a light green. "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 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. a character vector of specific colors Any R-acceptable colors, will work here, e.g., 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 highlight_so_cutoffs.
shading_column	If you would like to alternate the shading of the rows in the output table, supply here the unquoted name of the column to check for when to change the shading; every time that column's value changes, the shading will alternate between white and light gray. By default, we will alternate the shading based on the simulation file name. Setting this argument can be a little bit tricky because we'll be looking for a column that's present in the output from this function, something you might not know until you run it. If you specify something and the shading doesn't show up as expected, double check what the final output column names are and make sure you're using one of those.
single_table	TRUE (default) or FALSE for whether to save all the PK data in a single table or break the data up by tissue, compound ID, and file into multiple tables. This only applies to the Word output.
page_orientation	set the page orientation for the Word file output to "portrait" (default) or "landscape"
fontsize	the numeric font size for Word output. Default is 11 point. This only applies when you save the table as a Word file.
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.
return_caption	TRUE or FALSE (default) for whether to return any caption text to use with the table. If set to TRUE, you'll get as output a list of the table, the table heading, and the table caption. When you've requested multiple individual tables, e.g., when single_table = FALSE, this will not return anything at this point. We may add that later, but at present, this is not set up to return multiple table captions.
...	used under-the-hood to check for mis-specified arguments
convert_conc_units	SOON TO BE DEPRECATED. Please use the argument "conc_units" instead.

Value

a data.frame

Examples

# none yet

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