annotateDetails: Annotate Simcyp Simulator experimental details

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

Annotate Simcyp Simulator experimental details

Description

annotateDetails uses output from either extractExpDetails or extractExpDetails_mult, formats it, adds columns for

1. which compound the information pertains to (substrate, inhibitor, etc.),

2. which section of the Simcyp Simulator this detail is found in (physchem, absorption, distribution, etc.),

3. notes describing what the detail is, and

4. which sheet in the Simulator output Excel file or in the Simulator workspace the information was pulled from.

It will also optionally filter the data to return only specifically requested information. If you find yourself overwhelmed at the amount of information, we recommend looking at just one compound at a time. You can set the compoundID argument to just the compound ID you want – "substrate", "inhibitor 1", etc. – or set the compound argument to just the compound you want – "midazolam" or "Client Drug X" – and that will also help make things less overwhelming and easier to find. For detailed instructions and examples, please see the SharePoint file "Simcyp PBPKConsult R Files - Simcyp PBPKConsult R Files/SimcypConsultancy function examples and instructions/Checking simulation experimental details/Checking-simulation-experimental-details.docx". (Sorry, we are unable to include a link to it here.)

Usage

annotateDetails(
  existing_exp_details,
  compoundID = NA,
  compound = NA,
  template_sim = NA,
  sims_to_include = NA,
  show_only_diff_from_template = FALSE,
  simulator_section = NA,
  detail_set = "all",
  find_matching_details = NA,
  show_compound_col = TRUE,
  omit_all_missing = TRUE,
  file_order = NA,
  return_list = FALSE,
  save_output = NA,
  output_tab_name = "Simulation experimental details",
  filename_text = NA
)

Arguments

existing_exp_details	output from extractExpDetails or extractExpDetails_mult
compoundID	optionally supply one or more of "substrate", "primary metabolite 1", "primary metabolite 2", "secondary metabolite", "inhibitor 1", "inhibitor 2", or "inhibitor 1 metabolite" to return information only on that/those compound(s). Remember to contain more than one compound ID with c(...).
compound	optionally supply a specific compound name or part of a specific compound name to get all possible compounds that match that and only compounds that match that. Regular expressions are acceptable here, e.g., compound = "midaz|keto" to find any compound with either "midaz" or "keto" in the name. Not case sensitive. If you request only information on a specific compound, we will assume what what you care about is the set of parameters used for that compound and not whether that compound was the substrate or the inhibitor. This will change the output somewhat because we won't include the column "CompoundID" and we will concatenate all the possible compound names in the column "Compound". Try this out and you'll see what we mean.
template_sim	optionally include a specific file name – it must be one of the files included in the object you supply for existing_exp_details – that can be used as a template simulation to compare all the other simulations to. Any details in any simulations that do NOT match the template simulation details will be highlighted in red if you save the output to an Excel file using save_output. NOTE: If you use a template simulation, we strongly recommend you also set compoundID to be only the compound ID you want, e.g., compoundID = "substrate" and/or set the compound name to be only the compound you want, e.g., compound = "midaz" (this will match any compound names that include the letters "midaz" and is NOT case sensitive), and set show_compound_col = FALSE. This will result in a much clearer Excel file.
sims_to_include	optionally specify which simulation files you'd like to include in the annotated output. Acceptable input: NA (default) get all the simulations included in existing_exp_details a character vector of the file names you want The items in the character vector must exactly match file names in the column "File" of the "MainDetails" item in existing_exp_details, including the ".xlsx" or ".db" file extension a regular expression This will include in the output only files that match the regular expression. This must have length = 1, and it IS case sensitive. For example, say you only want to look at development or verification simulations and you included "dev" or "ver" in those file names, respectively. Here is how you could specify that (the verical pipe | means "or" for regular expressions): sim_to_include = "dev|ver"
show_only_diff_from_template	TRUE or FALSE (default) to show only the details that differ from the template simulation, which reduces the number of rows in your output and can make it easier to find what has changed between simulations
simulator_section	optionally supply a specific simulator section or sections from which to find simulation experimental details and then return only those details. Options are "Absorption", "Distribution", "Elimination", "Transport", "Interaction", "Phys Chem and Blood Binding", "Population", or "Trial Design". Not case sensitive. If you want more than one, enclose them with c(...)
detail_set	optionally supply a set of details and this will return only those details. Options: "all" all possible details (default) "Summary tab" details available from the "Summary tab" "Input Sheet" details available from the "Input Sheet" tab "population tab" details about the population used (data come from the tab with the same name as the population simulated) "Simcyp inputs" all the details that you normally fill out on the "Simcyp inputs (and QC)" tab of a compound data sheet plus trial design information "methods" or "trial design" all the details that show up in the methods section of a report: number of trials, number of individuals simulated, population, percent female, age range, dose amount and regimen, etc. "lactation" details from the "Input Sheet" tab that pertain to lactation such as the milk-to-plasma ratio and whether a breast perfusion-limited model was used. "CustomDosing" ("custom dosing" is also ok) custom-dosing information. This will be on a tab named "CustomDosing" unless you specify a tab name you want. "DissolutionProfiles" ("dissolution profiles" is also ok) drug-dissolution profiles. This will be on a tab named "DissolutionProfiles" unless you specify a tab name you want. "ReleaseProfiles" ("release profiles" is also ok) drug-release profiles This will be on a tab named "ReleaseProfiles" unless you specify a tab name you want. "ConcDependent_fup" concentration-dependent fu,p. This will be on a tab named "ConcDependent_fup" unless you specify a tab name you want. "ConcDependent_BP" concentration-dependent B/P. This will be on a tab named "ConcDependent_BP" unless you specify a tab name you want. "pH_dependent_solubility" pH-dependent drug solubility. This will be on a tab named "pH_dependent_solubility" unless you specify a tab name you want. a string of the specific details you want, each in quotes and encapsulated with c(...), For a complete list of possibilities, type view(ExpDetailDefinitions) into the console. Parameters are reported with a suffix depending on which compound they pertain to: "_sub" for the substrate, "_met1" for the primary metabolite, "_met2" for the second primary metabolite, "_secmet" for the secondary metabolite, "_inhib" for the 1st inhibitor or inducer listed, "_inhib2" for the 2nd inhibitor or inducer listed, or "_inh1met" for the inhibitor 1 metabolite. An example of acceptable input: c("pKa1_sub", "fa_inhib2", "Regimen_sub") Not case sensitive.
find_matching_details	optionally supply a string of text to search for in the column "Detail". Regular expressions are supported here, so use, e.g., "|" to mean "or", ".*" to mean "match any character any number of times", "^" to mean "starts with...", and "$" to mean "ends with...". An example: find_matching_details = "^CLint.*CYP3A.*sub$" to find all details that start with "CLint", then, somewhere in the name, include "CYP3A", and then end with "sub" (for "substrate"). Case sensitive.
show_compound_col	TRUE (default), FALSE, or "concatenate" for whether to include in the results the column "Compound", which is the compound's specific name in each simulation. Why would you ever omit this? If you have a compound with a slightly different name across multiple simulations, e.g., "DrugX" and "Drug X", and "Drug X - reduced Ki", you'll get a new row for every possible combination of "Compound" and "Detail", which might not make for easy comparisons. For example, a Ki value for "DrugX" will be in one row and the same Ki value for "Drug X" will be on a separate row. Try setting this to TRUE when you have similarly named compounds that really should be compared and see how that compares to the default. If you set this to "concatenate", you'll get all the possible compound names together; in the example we just gave, you would see "DrugX, Drug X, or Drug X - reduced Ki" listed as the compound.
omit_all_missing	TRUE (default) or FALSE for whether to omit a detail if the values are NA for all files
file_order	optionally specify the order in which files should be shown in the annotated output, e.g., file_order = c("file A.xlsx", "file B.xlsx", "file C.xlsx")
return_list	TRUE or FALSE (default) for whether to return the entire list of information from existing_exp_details. Before running this function, existing_exp_details was a list. Probably, though, all you want out of this function most of the time is a single data.frame with the main information annotated. If you want more than that, set this to TRUE.
save_output	optionally save the output by supplying a csv or Excel file name in quotes here, e.g., "Simulation details.csv" or "Simulation details.xlsx". Do not include any slashes, dollar signs, or periods in the file name. If you leave off the file extension, it will be saved as a csv file.
output_tab_name	the tab name to use when saving the output as an Excel file. If you specify a tab that does not already exist in the Excel file you specified with save_output, this will add a new tab and not overwrite the existing ones. This means that you can, for example, run annotateDetails one time where you look at the detail set "Simcyp inputs" and save that tab eponymously and then you can run annotateDetails again, this time using the detail set "Trial design" and naming this second tab accordingly, and the result will be a single Excel file named according to what you specified with save_output with one tab for Simcyp inputs and one tab for the trial design parameters.
filename_text	SOON TO BE DEPRECATED optionally specify a string of text to use for looking at only a subset of files.

Value

Returns a data.frame of simulation experimental details including the following columns:

SimulatorSection

the simulator section this detail is from, e.g., "absorption" or "elimination"

DataSource

the source of the data; this will be a sheet name in an Excel output file or a workspace or database file

Notes

an explanation of what this detail is

CompoundID

the simulator compound ID that this information pertains to, e.g., "substrate" or "inhibitor 1"

Compound

the name of the compound in the simulator, e.g., "Sim-Midazolam"

Detail

the specific experimental detail

All files have this value for this compound and compound ID

If all of the files have the exact same value for this particular combination of detail, compound, and compound ID, that value will show up in this column. The idea is that this makes it easy to check that everything that should be the same in a plethora of simulations actually is the same.

one column for every file included

the extracted simulator experimental details for each file will show up in their own columns

Examples

annotateDetails(existing_exp_details = MDZdetails)

# Get annotated details regarding absorption.
annotateDetails(existing_exp_details = MDZdetails, simulator_section = "absorption")

# Get annotated details on whatever was used as inhibitor 1
annotateDetails(existing_exp_details = MDZdetails, compoundID = "inhibitor 1")

# Get annotated details for any compounds with "midaz" or "keto" in the name.
annotateDetails(existing_exp_details = MDZdetails, compound = "midaz|keto")

# Get (most of) the details to put into a table of simulation inputs:
annotateDetails(existing_exp_details = MDZdetails, detail_set = "Simcyp inputs")

# Combine multiple options to get just a few specific details:
annotateDetails(existing_exp_details = MDZdetails,
            simulator_section = "absorption",
            compound = "midaz|keto",
            compoundID = "substrate")

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