calc_PK_ratios_mult: Calculate the ratio of PK parameters between multiple pairs...

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

Calculate the ratio of PK parameters between multiple pairs of simulations

Description

calc_PK_ratios_mult matches PK data from pairs of simulator output Excel files and calculates the mean and confidence intervals of the ratios of the requested PK parameters. For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Calculating PK ratios from separate simulations/Calculating-PK-ratios.docx". (Sorry, we are unable to include a link to it here.)

Usage

calc_PK_ratios_mult(
  PKparameters = NA,
  compoundToExtract = NA,
  tissue = NA,
  sheet_PKparameters = NA,
  existing_exp_details = NA,
  paired = TRUE,
  match_subjects_by = "individual and trial",
  distribution_type = "t",
  mean_type = "geometric",
  include_num_denom_columns = TRUE,
  conf_int = 0.9,
  includeConfInt = TRUE,
  includeCV = TRUE,
  include_dose_num = NA,
  concatVariability = TRUE,
  variability_format = "to",
  prettify_columns = TRUE,
  prettify_compound_names = TRUE,
  rounding = NA,
  checkDataSource = TRUE,
  extract_forest_data = FALSE,
  save_table = NA,
  name_clinical_study = NA,
  shading_column,
  highlight_gmr_colors = NA,
  single_table = TRUE,
  page_orientation = "landscape",
  fontsize = 11,
  sim_data_file_pairs = "deprecated"
)

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 tissue, which compound, which simulation files, and which tab to get the data from with the arguments tissue, compoundToExtract, sim_data_file_numerator, sim_data_file_denominator, 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: "Numerator_File" this is the same thing as the argument sim_data_file_numerator "Denominator_File" This is the same thing as the argument sim_data_file_denominator) "Numerator_Sheet" or "Denominator_Sheet" When it's a user-defined AUC interval you want, this specifies which sheet in the Simulator output Excel file to use for the corresponding PK parameter in the numerator or denominator, respectively. If it's a regular first-dose or last-dose PK parameter, leave this blank or as NA; we know which sheets to use for those values. You can specify as many different sheets as needed with one row for every new sheet. "Numerator_Tissue" or "Denominator_Tissue" This is the same as the argument tissue except you can specify it separately for each set of PK parameters. "Numerator_CompoundID" or "Denominator_CompoundID" This is the same as the argument compoundToExtract except that you can specify it separately for each set of PK parameters. If you omit any of those columns, whatever you supply for their respective arguments will be used instead. Note that the respective arguments will use the same value for both the numerator and the denominator simulations. 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 just the PK parameters you want 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 tissue, compoundToExtract, and sheet_PKparameters specify what you want for each of those. 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.
compoundToExtract	For which compound do you want to extract PK data? Options are: "substrate" (default if left as NA), "primary metabolite 1", "primary metabolite 2", "secondary metabolite", "inhibitor 1" – this can be an inducer, inhibitor, activator, or suppressor, but it's labeled as "Inhibitor 1" in the simulator, "inhibitor 2" for the 2nd perpetrator listed in the simulation, "inhibitor 1 metabolite" for the primary metabolite of inhibitor 1 If you have want one compound for the numerator PK and a different one for the denominator PK, that must be specified in a data.frame or a csv file that you supply to the argument PKparameters.
tissue	For which tissue would you like the PK parameters to be pulled? Options are "plasma" (default if left as NA) "unbound plasma" "blood" "unbound blood" "peripheral plasma" "peripheral blood" If you want one tissue for the numerator PK and a different one for the denominator PK, that must be specified in a data.frame or a csv file that you supply to the argument PKparameters.
sheet_PKparameters	If you have a user-defined AUC interval and you want the PK parameters for to be pulled from that specific tab in the Simulator output Excel files, list that tab here. If you want standard first-dose or last-dose PK parameters, leave this as the default NA; we know where to find those. If you want one tab for the numerator simulation and a different tab for the denominator simulation, that must be specified in a data.frame or a csv file that you supply to the argument PKparameters.
existing_exp_details	If you have already run extractExpDetails_mult to get information about how the simulations were set up, you can save some processing time by supplying that object here, unquoted. If left as NA, this function will run extractExpDetails_mult behind the scenes to figure out some information about your experimental set up.
paired	TRUE (default) or FALSE for whether the study design is paired, as in, the subjects are identical between the two simulations. THIS IS AN IMPORTANT DISTINCTION AND WILL AFFECT HOW THE CALCULATIONS ARE PERFORMED! An example of a paired study would be a DDI study where each subject has a measurement without the perpetrator of interest and then has a second measurement with the perpetrator. The comparison is for repeated measurements of the same subject. An example of an unpaired study design would be comparing healthy volunteers to subjects with hepatic impairment because those are measurements on different subjects. For paired study designs, the order of operations is to calculate each subject's mean ratio and then to calculate the mean of those ratios. For unpaired study designs, the order of operations is to calculate the mean for the numerator simulation and then divide it by the mean for the denominator simulation. Would this be clearer if you could see the mathematical equations? We agree but can't easily include equations in the help file. However, if you run this and save the output to a Word file, the equations will be included in the output.
match_subjects_by	For a paired study design, how would you like to match your subjects? Options are "individual and trial" (default), which matches by both the simulated individual ID number AND by the trial number, or "individual only", which matches only by the individual ID number. This will be ignored for unpaired study designs. Why are we even bothering with this, you ask? Just to be totally safe, we normally match simulated subjects by both the individual subject ID and by the trial number. We thought that this would always work and would be the safest option, but we discovered that, for some scenarios where you might expect the individuals to be exactly the same between two simulations, they actually were randomly assigned to different trials. Mismatched subjects would lead to inaccurate calculations, so we want to avoid that. If you use the default setting of "individual and trial" but the trials are NOT the same between simulations, you'll get a warning and no results, which we think is vastly superior to getting incorrect results.
distribution_type	use a "t" distribution (default) or a "Z" distribution. Note: The Simcyp Simulator calculates geometric confidence intervals with a t distribution.
mean_type	What kind of means and confidence intervals do you want listed in the output table? Options are "arithmetic" or "geometric" (default).
include_num_denom_columns	TRUE (default) or FALSE for whether to include columns in the output table for the numerator data alone and columns for the denominator alone. For example, if you wanted to calculate the dose 1 AUC ratio for cancer patients compared to healthy volunteers, settting include_num_denom_columns = TRUE would give you that ratio and also a column with summary statistics on the AUC for cancer patients and a column with summary statistics on the AUC for healthy volunteers. Setting it to FALSE would give you only the ratios.
conf_int	confidence interval to use; default is 90%
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)").
includeCV	TRUE (default) or FALSE for whether to include rows for CV in the table
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.
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.)
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". We're still tweaking this to make it look just right!
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("inhibitor" = "teeswiftavir", "substrate" = "superstatin"). Please note that "inhibitor" 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("inhibitor" = "teeswiftavir and 1-OH-teeswiftavir", "substrate" = "superstatin").
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
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.
extract_forest_data	TRUE or FALSE (default) to get forest-plot data at the same time. If set to TRUE, this will return a list that includes data formatted for use with the function forest_plot. This will assume that the denominator is the baseline or control scenario and the numerator is the comparison. In the output for this, the column "Dose_sub" will contain the dose of the substrate in the denominator simualtions, and the column "Dose_inhib" will contain the dose of the inhibitor (if there was one) in the numerator simulations or the dose of the substrate in the numerator simulations if there was not. If there was not an inhibitor, the column "Inhibitor 1" will contain the file names for the numerator sims.
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 supply only the file extension, e.g., save_table = "docx", the name of the file will be the file name plus "PK summary table" with that extension and output will be located in the same folder as 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 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.
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."
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.
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.
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" or "landscape" (default)
fontsize	the numeric font size for Word output. Default is 11 point. This only applies when you save the table as a Word file.
sim_data_file_pairs	DEPRECATED. This argument was used in the past to specify which pairs of files to compare, but we are changing the way we're asking you to tell us that. Now, we'd like you to give us this information with the argument PKarameters and ONLY there. We apologize for the inconvenience, but, to be frank, this is a pretty complicated function to put together, and we needed to simplify things.

Value

A list or a data.frame of PK data that optionally includes where the data came from and data to use for making forest plots

Examples

# No examples yet.

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